REST API Documentation

Table of Contents

Introduction
Authentication
Get Lottery Countries
Get Lottery States
Get Lotteries
Get Lottery
Get Lottery Draw Years
Get Lottery Results
Get Numbers Frequency
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 Countries

Endpoint: GET: /lottery/countries

Retrieves all available countries for lottery results.

PHP Example Request


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

Response (Success - 200 OK)


{
    "countries": {
        "us",
        "ca",
        "germany",
        "italy",
        "ie",
        "uk"
    }
}

Get Lottery Countries with Details

Endpoint: GET: /lottery/countries-details

Retrieves all available countries including available lotteries count and country information.

Query Parameters

country (optional, string): The country code. Refer to: API: lottery countries

PHP Example Request


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

Response (Success - 200 OK)


{
    "countries": [
        {
            "slug": "us",
            "lottery_count": 351,
            "info": {
                "id": 235,
                "name": "United States",
                "alpha2": "US",
                "alpha3": "USA",
                "iso_numeric": 840,
                "currency_code": "USD",
                "currency_name": "US Dollar",
                "currency_symbol": "$",
                "flag": "153-united-states-of-america.svg",
                "flag_url": "https://www.lotteryresultsfeed.com/assets/images/country-flags-rectangular/svg/153-united-states-of-america.svg"
            }
        }
    ]
}

Get Lottery States

Endpoint: GET: /lottery/states

Retrieves all available states for a given country.

Currently states are only for USA and Canada lotteries. European lotteries don`t have states.

Query Parameters

country (required, string): The country code. Refer to: API: lottery countries

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 Lottery States with Details

Endpoint: GET: /lottery/states-details

Retrieves all available states for a given country including available lotteries count.

Query Parameters

country (required, string): The country code. Refer to: API: lottery countries

PHP Example Request


$token = session('api_token');
if ($token) {
    try {
        $client = new Client(['base_uri' => $baseUri, 'timeout' => 5.0]);
        $response = $client->get('lottery/states-details', [
            '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": [
        {
            "code": "ar",
            "name": "Arkansas",
            "lottery_count": 7
        },
        {
            "code": "az",
            "name": "Arizona",
            "lottery_count": 6
        },
        ...
    }
}

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 only for USA and Canada, 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 only for USA and Canada, 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
    ]
}

Get Numbers Frequency

Endpoint: GET: /lottery/frequency

Retrieves frequency analysis of lottery numbers, showing how often each number has been drawn. Results are sorted by frequency in descending order.

Query Parameters

id (required, integer): The ID of the lottery.
year (optional, integer): The year for which to calculate frequency. Cannot be used with date range filters.
draw_date_from (optional, date): Start date for date range filter (format: YYYY-MM-DD). Cannot be in the future.
draw_date_to (optional, date): End date for date range filter (format: YYYY-MM-DD).

Note: The year parameter cannot be used simultaneously with draw_date_from or draw_date_to. When using year, it automatically sets the date range from January 1 to December 31 of that year.

PHP Example Request


$token = session('api_token');
$lotteryId = 1; // Example lottery ID

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

// Example 2: Get frequency for date range
if ($token) {
    try {
        $client = new Client(['base_uri' => $baseUri, 'timeout' => 5.0]);
        $response = $client->get('lottery/frequency', [
            'headers' => [
                'Accept' => 'application/json',
                'Authorization' => 'Bearer ' . $token
            ],
            'query' => [
                'id' => $lotteryId,
                'draw_date_from' => '2024-01-01',
                'draw_date_to' => '2024-06-30',
            ]
        ]);
        $frequency = json_decode($response->getBody()->getContents(), true);
        print_r($frequency);
    } catch (\GuzzleHttp\Exception\GuzzleException $e) {
        echo 'Error fetching frequency data: ' . $e->getMessage();
    }
}

// Example 3: Get all-time frequency
if ($token) {
    try {
        $client = new Client(['base_uri' => $baseUri, 'timeout' => 5.0]);
        $response = $client->get('lottery/frequency', [
            'headers' => [
                'Accept' => 'application/json',
                'Authorization' => 'Bearer ' . $token
            ],
            'query' => [
                'id' => $lotteryId,
            ]
        ]);
        $frequency = json_decode($response->getBody()->getContents(), true);
        print_r($frequency);
    } catch (\GuzzleHttp\Exception\GuzzleException $e) {
        echo 'Error fetching frequency data: ' . $e->getMessage();
    }
}

Response (Success - 200 OK)


{
    "lottery": {
        "id": 1,
        "name": "Powerball",
        "main_balls_count": 69,
        "bonus_balls_count": 26,
        "bonus_balls_name": "PowerBall",
        "bonus_balls_name_short": "PB"
    },
    "filters": {
        "year": 2024,
        "draw_date_from": null,
        "draw_date_to": null,
        "applied_filters": {
            "draw_date_from": "2024-01-01",
            "draw_date_to": "2024-12-31"
        }
    },
    "frequency": {
        "main_balls_frequency": {
            "23": {
                "frequency": 15,
                "last_draw_date": "2024-06-28"
            },
            "45": {
                "frequency": 14,
                "last_draw_date": "2024-06-25"
            },
            "67": {
                "frequency": 13,
                "last_draw_date": "2024-06-21"
            }
        },
        "bonus_balls_frequency": {
            "10": {
                "frequency": 8,
                "last_draw_date": "2024-06-28"
            },
            "5": {
                "frequency": 7,
                "last_draw_date": "2024-06-25"
            },
            "19": {
                "frequency": 6,
                "last_draw_date": "2024-06-21"
            }
        }
    }
}

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"
                    }