REST API Documentation

Table of Contents

Introduction
Authentication
Get Lottery States
Get Lotteries
Get Lottery
Get Lottery Draw Years
Get Lottery Results
Error Handling

Introduction

Welcome to the Lottery Results Feed API! This API allows you to retrieve comprehensive lottery data, including available states, specific lotteries, draw years, and historical results. This documentation provides all the necessary information to integrate with our API.

Base URL: https://www.lotteryresultsfeed.com/api/

All API responses are in JSON format.

Authentication

This API uses Bearer token authentication. You need to obtain a token by logging in to the /login endpoint and include it in the Authorization header of subsequent requests.

Login

Endpoint: POST: /login

Authenticates a user and returns an authentication token.

Request Body


{
    "email": "YOUR_EMAIL_ADDRESS",
    "password": "YOUR_PASSWORD"
}

PHP Example Request


use GuzzleHttp\Client;

$baseUri = 'https://www.lotteryresultsfeed.com/api/';

$client = new Client([
    'base_uri' => $baseUri,
    'timeout' => 5.0,
]);

try {
    $response = $client->post('login', [
        'headers' => ['Accept' => 'application/json'],
        'form_params' => [
            'email' => 'YOUR_EMAIL_ADDRESS',
            'password' => 'YOUR_PASSWORD',
        ]
    ]);

    $result = json_decode($response->getBody()->getContents(), true);
    $token = $result['token'];
    // Store the token securely (e.g., in session, cache)
    session(['api_token' => $token]);

} catch (\GuzzleHttp\Exception\GuzzleException $e) {
    // Handle the error appropriately
    echo 'Error during login: ' . $e->getMessage();
}

Response (Success - 200 OK)


{
    "user": {
        "first_name": "Lottery",
        "last_name": "Admin",
        "name": "Lottery Admin",
        "email": "admin@lotteryfeed.com",
        "created_at": "2021-11-11T14:49:09.000000Z",
        "updated_at": "2024-05-06T14:01:55.000000Z"
    },
    "token": "YOUR_GENERATED_TOKEN"
}

We strongly recommend caching the authentication token locally to avoid repeated login requests.

Get Lottery States

Endpoint: GET: /lottery/states

Retrieves all available states for a given country.

Query Parameters

country (required, string): The country code. Currently, only us is supported.

PHP Example Request


$token = session('api_token');
if ($token) {
    try {
        $client = new Client(['base_uri' => $baseUri, 'timeout' => 5.0]);
        $response = $client->get('lottery/states', [
            'headers' => [
                'Accept' => 'application/json',
                'Authorization' => 'Bearer ' . $token
            ],
            'query' => [
                'country' => 'us'
            ]
        ]);
        $states = json_decode($response->getBody()->getContents(), true);
        print_r($states);
    } catch (\GuzzleHttp\Exception\GuzzleException $e) {
        echo 'Error fetching states: ' . $e->getMessage();
    }
} else {
    echo 'Authentication token not found. Please log in first.';
}

Response (Success - 200 OK)


{
    "states": {
        "ar": "Arkansas",
        "az": "Arizona",
        "ca": "California",
        "co": "Colorado",
        "ct": "Connecticut",
        "dc": "District of Columbia",
        "de": "Delaware",
        "fl": "Florida",
        "ga": "Georgia",
        "...": "..."
    }
}

Get Lotteries

Endpoint: GET: /lottery/lotteries

Retrieves all lotteries for a specific country and state.

Query Parameters

country (required, string): The country code (e.g., us).
state (required, string): The state code (e.g., az).

PHP Example Request


$token = session('api_token');
$state = 'az'; // Example state
if ($token) {
    try {
        $client = new Client(['base_uri' => $baseUri, 'timeout' => 5.0]);
        $response = $client->get('lottery/lotteries', [
            'headers' => [
                'Accept' => 'application/json',
                'Authorization' => 'Bearer ' . $token
            ],
            'query' => [
                'country' => 'us',
                'state' => $state,
            ]
        ]);
        $lotteries = json_decode($response->getBody()->getContents(), true);
        print_r($lotteries);
    } catch (\GuzzleHttp\Exception\GuzzleException $e) {
        echo 'Error fetching lotteries: ' . $e->getMessage();
    }
} else {
    echo 'Authentication token not found. Please log in first.';
}

Response (Success - 200 OK)


{
    "lotteries": [
        {
            "id": 1,
            "country": "us",
            "state": "az",
            "name": "Powerball",
            "slug": "powerball",
            "main_balls_to_pick": "5",
            "main_balls_count": "69",
            "bonus_balls_to_pick": "1",
            "bonus_balls_count": "26",
            "bonus_balls_name": "Power Ball",
            "bonus_balls_name_short": "PB",
            "is_multi_state": "1",
            "draw_days": {
                "Monday": "1",
                "Tuesday": "0",
                "Wednesday": "1",
                "Thursday": "0",
                "Friday": "0",
                "Saturday": "1",
                "Sunday": "0"
            },
            "url": "https://www.powerball.com/",
            "logo_url": "https://www.lotteryresultsfeed.com/images/lottery-logos/az-powerball.svg",
            "jackpot_odds": "292201338",
            "..." : "..."
        }
        // ... more lottery objects
    ]
}

Get Lottery

Endpoint: GET: /lottery/lottery

Retrieves a specific lottery by country, state, and slug.

Query Parameters

country (required, string): The country code (e.g., us).
state (required, string): The state code (e.g., az).
slug (required, string): The unique identifier of the lottery (e.g., powerball).

PHP Example Request


$token = session('api_token');
$state = 'az';
$slug = 'powerball';
if ($token) {
    try {
        $client = new Client(['base_uri' => $baseUri, 'timeout' => 5.0]);
        $response = $client->get('lottery/lottery', [
            'headers' => [
                'Accept' => 'application/json',
                'Authorization' => 'Bearer ' . $token
            ],
            'query' => [
                'country' => 'us',
                'state' => $state,
                'slug' => $slug,
            ]
        ]);
        $lottery = json_decode($response->getBody()->getContents(), true);
        print_r($lottery);
    } catch (\GuzzleHttp\Exception\GuzzleException $e) {
        echo 'Error fetching lottery details: ' . $e->getMessage();
    }
} else {
    echo 'Authentication token not found. Please log in first.';
}

Response (Success - 200 OK)


{
    "lottery": {
        "id": 1,
        "country": "us",
        "state": "az",
        "name": "Powerball",
        "slug": "powerball",
        "main_balls_to_pick": "5",
        "main_balls_count": "69",
        "bonus_balls_to_pick": "1",
        "bonus_balls_count": "26",
        "bonus_balls_name": "Power Ball",
        "bonus_balls_name_short": "PB",
        "is_multi_state": "1",
        "draw_days": {
            "Monday": "1",
            "Tuesday": "0",
            "Wednesday": "1",
            "Thursday": "0",
            "Friday": "0",
            "Saturday": "1",
            "Sunday": "0"
        },
        "url": "https://www.powerball.com/",
        "logo_url": "https://www.lotteryresultsfeed.com/images/lottery-logos/az-powerball.svg",
        "jackpot_odds": "292201338",
        "..." : "..."
    }
}

Get Lottery Draw Years

Endpoint: GET: /lottery/draw-years

Retrieves all available draw years for a specific lottery.

Query Parameters

id (required, integer): The ID of the lottery.

PHP Example Request


$token = session('api_token');
$lotteryId = 1; // Example lottery ID
if ($token) {
    try {
        $client = new Client(['base_uri' => $baseUri, 'timeout' => 5.0]);
        $response = $client->get('lottery/draw-years', [
            'headers' => [
                'Accept' => 'application/json',
                'Authorization' => 'Bearer ' . $token
            ],
            'query' => [
                'id' => $lotteryId,
            ]
        ]);
        $drawYears = json_decode($response->getBody()->getContents(), true);
        print_r($drawYears);
    } catch (\GuzzleHttp\Exception\GuzzleException $e) {
        echo 'Error fetching draw years: ' . $e->getMessage();
    }
} else {
    echo 'Authentication token not found. Please log in first.';
}

Response (Success - 200 OK)


{
    "draw_years": [
        "2024",
        "2023",
        "2022",
        "2021",
        "2020",
        "2019",
        "2018",
        "2017",
        "2016",
        "2015"
    ]
}

Get Lottery Results

Endpoint: GET: /lottery/results

Retrieves all draw results for a specific lottery, optionally filtered by year.

Query Parameters

id (required, integer): The ID of the lottery.
year (optional, integer): The year for which to retrieve results. If not provided, all available results are returned.

PHP Example Request


$token = session('api_token');
$lotteryId = 1; // Example lottery ID
$year = 2023; // Example year (optional)
if ($token) {
    try {
        $client = new Client(['base_uri' => $baseUri, 'timeout' => 5.0]);
        $response = $client->get('lottery/results', [
            'headers' => [
                'Accept' => 'application/json',
                'Authorization' => 'Bearer ' . $token
            ],
            'query' => [
                'id' => $lotteryId,
                'year' => $year, // Include year if you want to filter
            ]
        ]);
        $results = json_decode($response->getBody()->getContents(), true);
        print_r($results);
    } catch (\GuzzleHttp\Exception\GuzzleException $e) {
        echo 'Error fetching results: ' . $e->getMessage();
    }
} else {
    echo 'Authentication token not found. Please log in first.';
}

Response (Success - 200 OK)


{
    "results": [
        {
            "draw_date": "2023-12-30",
            "balls": [
                "10",
                "11",
                "26",
                "27",
                "34"
            ],
            "ball_bonus": "7",
            "jackpot": "500000000"
        },
        {
            "draw_date": "2023-12-27",
            "balls": [
                "5",
                "12",
                "22",
                "25",
                "30"
            ],
            "ball_bonus": "12",
            "jackpot": "485000000"
        },
        // ... more results
    ]
}

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request. Here are some common error codes you might encounter:

200 OK: The request was successful.
201 Created: The request was successful and a new resource was created.
400 Bad Request: The request could not be understood or was missing required parameters. Check the request parameters and body.
401 Unauthorized: Authentication is required to access the resource. Ensure you are providing a valid authentication token in the Authorization header.
403 Forbidden: You do not have permission to access this resource.
404 Not Found: The requested resource could not be found. Check the endpoint URL and parameters.
405 Method Not Allowed: The specified HTTP method is not allowed for this endpoint. Check the allowed methods in the endpoint documentation.
422 Unprocessable Entity: The request was well-formed but was unable to be processed due to semantic errors. This often indicates validation errors. The response body will usually contain details about the errors.
500 Internal Server Error: An unexpected error occurred on the server. If this occurs, please contact the API administrator.

Example Error Response (422 Unprocessable Entity)


{
    "message": "The given data was invalid.",
    "errors": {
        "email": [
            "The email field is required."
        ],
        "password": [
            "The password field is required."
        ]
    }
}

Example Error Response (401 Unauthorized)


                    {
                        "message": "Unauthorized"
                    }