API Documentation

Welcome to the Resultsza API documentation. Here you will find all the information needed to use our API effectively.

Available Endpoints

1. Get Latest Results

This endpoint retrieves the latest results for all lottery games in a single API call. The response includes division details and winnings per division for each game. If the optional date parameter is used, the results will show all games that had a draw on the specified date.

GET /api/get_latest_results?api_key=YOUR_API_KEY

Optional Parameters:

• date=YYYY-MM-DD: Fetch results for a specific date. If omitted, the API returns the most recent results.

Example Request:

curl -i "https://resultsZA.co.za/api/get_latest_results?api_key=YOUR_API_KEY&date=2024-12-10"

Response Format:

The response will contain the following fields:

• status: Indicates whether the request was successful (e.g., "success").
• results: A dictionary containing results for all games.
• Each game's result includes:
  • date: The draw date in ISO 8601 format (UTC).
  • draw_id: Unique identifier for the draw.
  • draw_machine: The machine used for the draw.
  • game_type: The type of lottery game (e.g., "Lotto").
  • total_pool_size: The total prize pool for the draw.
  • total_sales: The total ticket sales for the draw.
  • winning_numbers: An array of integers representing the winning numbers.
  • bonus_ball / powerball: The bonus ball or powerball number (if applicable).
  • next_draw_date: The next draw date in ISO 8601 format (UTC).
  • divisions: An array of objects, each representing a prize division:
    • division: The division name or identifier.
    • winners: The number of winners in the division.
    • winning_amount: The prize amount per winner in ZAR.

Example JSON Response:

{
    "status": "success",
    "results": {
        "daily_lotto_results": {
            "date": "2024-12-10T20:00:00Z",
            "draw_id": 2098,
            "draw_machine": "RNG2",
            "game_type": "Daily Lotto",
            "total_pool_size": 1633997.5,
            "total_sales": 3262896.0,
            "winning_numbers": [5, 11, 20, 28, 35],
            "bonus_ball": null,
            "next_draw_date": "2024-12-11T20:00:00Z",
            "divisions": [
                {"division": "DIV 1", "winners": 6, "winning_amount": 96799.2},
                {"division": "DIV 2", "winners": 466, "winning_amount": 287.1},
                {"division": "DIV 3", "winners": 13571, "winning_amount": 19.7},
                {"division": "DIV 4", "winners": 130413, "winning_amount": 5.0}
            ]
        },
        "lotto_results": {
            "date": "2024-12-07T20:00:00Z",
            "draw_id": 2497,
            "draw_machine": "RNG2",
            "game_type": "Lotto",
            "total_pool_size": 16460059.56,
            "total_sales": 16554055.0,
            "winning_numbers": [10, 20, 30, 47, 49, 50],
            "bonus_ball": 21,
            "next_draw_date": "2024-12-11T20:00:00Z",
            "divisions": [
                {"division": "DIV 1", "winners": 0, "winning_amount": 0.0},
                {"division": "DIV 2", "winners": 1, "winning_amount": 104016.2},
                {"division": "DIV 3", "winners": 104, "winning_amount": 1739.4},
                {"division": "DIV 4", "winners": 113, "winning_amount": 2001.1},
                {"division": "DIV 5", "winners": 3442, "winning_amount": 110.3},
                {"division": "DIV 6", "winners": 3083, "winning_amount": 107.1},
                {"division": "DIV 7", "winners": 45524, "winning_amount": 50.0},
                {"division": "DIV 8", "winners": 32534, "winning_amount": 20.0}
            ]
        }
    }
}
        

Note: The structure will include results for all game types drawn on the specified date if the date parameter is used.

2. Get Results by Game

Retrieve draw results for a specific game type.

GET /api/get_results_by_game?api_key=YOUR_API_KEY&game=GAME_NAME

Optional Parameters:

• date=YYYY-MM-DD: Fetch results for a specific date.

Example Requests:

curl -i "https://resultsZA.co.za/api/get_results_by_game?api_key=YOUR_API_KEY&game=Lotto"

curl -i "https://resultsZA.co.za/api/get_results_by_game?api_key=YOUR_API_KEY&game=Lotto&date=2024-11-16"

Response Format:

{
    "status": "success",
    "results": [
        {
            "draw_id": 123,
            "draw_date": "2023-03-20T20:00:00Z",
            "winning_numbers": [1, 5, 7, 9, 10],
            "bonus_ball": 22
        }
    ]
}

Note: The "get_results_by_game" endpoint only provides the winning numbers and does not include the division and winnings info.

3. Generate Random Numbers

Generate random numbers for any game type. (The numbers generated will be in accordance to each game type's rules)

GET /api/generate_random_numbers?api_key=YOUR_API_KEY&game=GAME_NAME&lines=NUMBER_OF_LINES

Parameters:

• game=GAME_NAME (Required): Specify the game type (e.g., Lotto, Powerball).
• lines=NUMBER_OF_LINES (Optional, default=1): Number of lines to generate. If omitted, a single line will be generated.

Example Requests:

curl -i "https://resultsZA.co.za/api/generate_random_numbers?api_key=YOUR_API_KEY&game=Lotto"

curl -i "https://resultsZA.co.za/api/generate_random_numbers?api_key=YOUR_API_KEY&game=Lotto&lines=5"

Response Format:

{
    "status": "success",
    "game": "Lotto",
    "lines": 5,
    "random_numbers": [
        [1, 2, 3, 4, 5, 6],
        [7, 8, 9, 10, 11, 12],
        ...
    ]
}

4. Get Hot and Cold Numbers

Retrieve hot (most frequently drawn) and cold (least frequently drawn) numbers for a game.

GET /api/get_hot_cold_numbers_stats?api_key=YOUR_API_KEY&product=GAME_NAME

Example Request:

curl -i "https://resultsZA.co.za/api/get_hot_cold_numbers_stats?api_key=YOUR_API_KEY&product=Lotto"

Response Format:

{
    "status": "success",
    "product": "Lotto",
    "hot": [5, 12, 19, ...],
    "cold": [45, 23, 7, ...]
}

5. Get Number Frequencies

Fetch the frequency of numbers drawn for a specific game type.

GET /api/get_number_frequencies?api_key=YOUR_API_KEY&product=GAME_NAME

Example Request:

curl -i "https://resultsZA.co.za/api/get_number_frequencies?api_key=YOUR_API_KEY&product=Powerball Plus"

Response Format:

{
    "status": "success",
    "product": "Lotto",
    "statistics": [
        {"number": 5, "frequency": 20, "last_drawn": "2023-03-15"},
        ...
    ]
}

6. Get Number Pairs

Fetch the most common number pairs that are drawn together for a game type. (Top 10 number pairs will be returned)

GET /api/get_number_pairs?api_key=YOUR_API_KEY&product=GAME_NAME

Example Request:

curl -i "https://resultsZA.co.za/api/get_number_pairs?api_key=YOUR_API_KEY&product=Lotto"

Response Format:

{
    "status": "success",
    "product": "Lotto",
    "pairs": [
        {"number1": 5, "number2": 7, "frequency": 15, "last_drawn": "2023-03-10"},
        ...
    ]
}

7. Winning Number Checker

This endpoint allows you to submit played numbers and check them against the winning numbers of a specific game type and draw date. The response includes match details, division, and winnings.

Note: This endpoint allows you to check up to 10 lines of played numbers per game type.

POST /api/check_played_numbers?api_key=YOUR_API_KEY&game=GAME_NAME&date=YYYY-MM-DD

Request Body Format:

The request body must be in JSON format and include the following for multiple lines of numbers played:

{
    "played_numbers": [
        [10, 20, 30, 40, 50, 5],
        [1, 6, 29, 11, 15, 17]
    ]
}

Or for a single line played

{
    "played_numbers": [1, 6, 29, 11, 15, 17]
}

Notes:

• For Powerball and Powerball Plus, the last number in each line is treated as the Powerball, and the first five numbers are the main numbers.
• For other games, all numbers in a line are treated as main numbers.

Example API Call:

curl -X POST "https://resultsZA.co.za/api/check_played_numbers?api_key=YOUR_API_KEY&game=Lotto Plus 1&date=2024-12-07" \
-H "Content-Type: application/json" \
-d '{
    "played_numbers": [
        [10, 20, 30, 40, 50, 5],
        [1, 6, 29, 11, 15, 17]
    ]
}'

Response Format:

{
    "status": "success",
    "game": "Lotto",
    "draw_date": "2024-12-07",
    "results": {
        "line1_results": {
            "played_numbers": [10, 20, 21, 30, 40, 50],
            "winning_numbers": [10, 20, 30, 47, 49, 50],
            "bonus_ball": 21,
            "matches": {
                "main_matches": 4,
                "bonus_match": true
            },
            "division": "DIV 4",
            "winning_amount": "2001.10"
        },
        "line2_results": {
            "played_numbers": [1, 6, 29, 11, 15, 17],
            "winning_numbers": [10, 20, 30, 47, 49, 50],
            "bonus_ball": 21,
            "matches": {
                "main_matches": 0,
                "bonus_match": false
            },
            "division": null,
            "winning_amount": null
        }
    }
}

Response Fields:

• status: Indicates whether the request was successful.
• game: The type of lottery game.
• draw_date: The date of the draw.
• results: Contains results for each line of played numbers:
  • played_numbers: The numbers submitted for this line.
  • winning_numbers: The official winning numbers for the draw.
  • bonus_ball / powerball: The bonus or powerball number for the draw.
  • matches: Details of the matches:
    • main_matches: The count of main numbers matched.
    • bonus_match / powerball_match: Whether the bonus or powerball was matched.
  • division: The prize division won, if applicable.
  • winning_amount: The prize amount for the division, if applicable.

8. Bulk Number Checker

This endpoint allows you to check a larger set of played numbers against the winning numbers of a specific game type and draw date. It supports up to 500 lines of played numbers in a single request and deducts tokens based on the number of lines checked.

POST /api/bulk_check_numbers?api_key=YOUR_API_KEY&game=GAME_NAME&date=YYYY-MM-DD

Token Consumption:

• 5 tokens for up to 50 lines checked.
• Requests exceeding 50 lines but not divisible by 50 will consume tokens for the next multiple of 50 (e.g., 53 lines consume 10 tokens).

Request Body Format:

The request body must be in JSON format:

{
    "played_numbers": [
        [10, 20, 30, 40, 50, 5],
        [1, 6, 29, 11, 15, 17],
        ...
    ]
}

Notes:

• For Powerball and Powerball Plus, the last number in each line is treated as the Powerball.
• For other games, all numbers in a line are treated as main numbers, and the bonus ball is checked separately.
• Lines exceeding the 500-line cap will return an error.

Example API Call:

curl -X POST "https://resultsZA.co.za/api/bulk_check_numbers?api_key=YOUR_API_KEY&game=Lotto Plus 1&date=2024-12-11" \
-H "Content-Type: application/json" \
-d '{
    "played_numbers": [
        [10, 20, 30, 40, 50, 5],
        [1, 6, 29, 11, 15, 17],
        ...
    ]
}'

Response Format:

{
    "status": "success",
    "game": "Lotto Plus 1",
    "draw_date": "2024-12-11",
    "lines_checked": 50,
    "results": {
        "line1_results": {
            "played_numbers": [10, 20, 30, 40, 50, 5],
            "winning_numbers": [10, 20, 30, 47, 49, 50],
            "bonus_ball": 21,
            "matches": {
                "main_matches": 4,
                "bonus_match": true
            },
            "division": "DIV 4",
            "winning_amount": "2001.10"
        },
        ...
    }
}

Note: Ensure your API key has sufficient tokens before submitting a bulk check request.

9. Text-to-Lucky Numbers

Have you ever wondered what lottery numbers your name, a favorite quote, or any text could generate? This endpoint takes your input text and converts it into a hash, using a clever algorithm to generate a unique line of lucky numbers for your chosen game type, while strictly adhering to the game rules (number counts and ranges).

POST /api/text_to_lucky_numbers?api_key=YOUR_API_KEY&game=GAME_NAME

How It Works:

• Your input text is hashed using a secure algorithm.
• The hash is then converted into numbers based on the rules of the chosen game type.
• For Powerball, it generates 5 main numbers and a separate Powerball number. For all other games, the correct number of main numbers is generated.
• Every text input creates a unique, deterministic set of lucky numbers, perfect for a fun and personalized lottery experience!

Request Parameters:

• api_key (required): Your API key to access this endpoint.
• game (required): The game type for which you want to generate numbers. Supported values:
  • Lotto
  • Powerball
  • Daily Lotto

Request Body Format:

The request body must be in JSON format:

{
    "text": "Your custom input text",
    "game_type": "Lotto"
}

Example API Call:

curl -X POST "https://resultsZA.co.za/api/text_to_lucky_numbers?api_key=YOUR_API_KEY&game=Powerball" \
-H "Content-Type: application/json" \
-d '{
    "text": "John Doe"
}'

Response Format:

{
    "status": "success",
    "text": "John Doe",
    "game_type": "Powerball",
    "lucky_numbers": [7, 22, 33, 41, 50],
    "powerball": 18
}

Token Consumption:

• Each request consumes 1 token.
• Regardless of the game type, only one personalized line of numbers is generated per request.

Use Cases:

• Generate a unique line of numbers for fun or inspiration.
• Discover what numbers your name or favorite phrase might "predict."
• Perfect for sharing with friends or adding an extra layer of excitement to your lottery play.

10. Check API Token Balance

Check the remaining API token balance for your account. This call does not consume any API tokens.

GET /check_api_key_balance?api_key=YOUR_API_KEY

Example Request:

curl -i "https://resultsZA.co.za/check_api_key_balance?api_key=YOUR_API_KEY"

Response Format:

{
    "status": "success",
    "tokens_remaining": 25,
    "is_paying_customer": true
}

Note: This endpoint does not deduct any tokens from your remaining balance.

Please replace YOUR_API_KEY with your actual API key and GAME_NAME with the name of the lottery game (e.g., "Lotto", "Powerball"). Ensure the date format is YYYY-MM-DD for date-specific queries.

Supported Game Types

• Daily Lotto
• Lotto
• Lotto Plus 1
• Lotto Plus 2
• Powerball
• Powerball Plus