Lottery API

Parameters

Provide game, state or country.

• game  optional

  Game slug, e.g. powerball, megamillions, us-ny-take5. Common spellings such as mega-millions also work. See /v1/lotterygames for every game.

• state  optional Business tier and above, or any annual plan

  US state or territory code (e.g. IL, TX, PR). Returns the latest draw of every covered game in that state, including the national games it sells, in one call.

• country  optional Business tier and above, or any annual plan

  ISO 3166-1 alpha-2 code (e.g. US). Returns the latest draw of every covered game in that country, in one call.

• date  optional Premium only

  Draw date (YYYY-MM-DD). Developer plans: the last two years. Business tier and above: any date in the archive.

• session  optional

  For games with several draws a day (e.g. midday, evening). Defaults to the latest draw that day.

• draw_number  optional Premium only

  For games that draw every few minutes (keno and similar): return this draw. Searched within date if given, otherwise the last 3 days.

Headers

• X-Api-Key  required

  API Key associated with your account.

Response

The /v1/lottery endpoint returns a JSON object with the following fields (a JSON array of them when state or country is used), or an error if the request is unsuccessful.

• game

  Game slug, e.g. powerball.

• game_name

  Display name of the game.

• country

  ISO 3166-1 alpha-2 country code.

• draw_date

  Draw date in the operator's local time zone (YYYY-MM-DD).

• session

  Only for games with several named draws a day: e.g. midday or evening.

• draw_number

  The operator's draw number. Games that draw every few minutes (keno and similar) are identified by it.

• draw_time

  Scheduled draw time in ISO 8601 with the operator's UTC offset.

• main_numbers

  Winning numbers as integers. Digit games (Pick 3, Cash 4, Numbers...) keep draw order and racing games list the runners in finishing order; other games use the order the operator publishes.

• bonus_numbers

  Separately drawn bonus ball(s), e.g. the Powerball, Mega Ball or a Pick game's Fireball or Wild Ball; [] for games without one.

• bonus_name

  Name of the bonus ball, when the game has one.

• multiplier

  Drawn multiplier (e.g. Power Play), when the game draws one.

• multiplier_name

  Name of the multiplier.

• secondary_draws

  Extra draws on the same ticket, e.g. Powerball Double Play or Illinois Lotto's Lotto Million 1 and Lotto Million 2.

• extras

  Game-specific details, e.g. a keno Bulls-Eye or a race time. Each key is described in the game's extras in /v1/lotterygames.

• jackpot

  Jackpot for this draw: currency, amount (advertised), cash_value, estimated and won.

• jackpot.cash_value Premium only

  Cash value of this draw's jackpot. On the free plan it reads This field is for premium subscribers only.

• next_draw

  Date and time of the next draw, and its estimated jackpot.

• next_draw.jackpot Premium only

  Estimated jackpot and cash value of the next draw. On the free plan it reads This field is for premium subscribers only.

• rules_version

  Effective date of the number format in force on this draw date. Use it to read older draws correctly when a game's format changed.

• revision

  Starts at 1 and increases if the operator corrects the draw.

• source

  The lottery operator that ran the draw (name, url), when we retrieved it (retrieved_at), and cross_checked: true once a second independent source has confirmed the numbers.

• message

  Only on the free plan: explains the 60-minute delay and the premium fields.

Parameters

• game  required

  Game slug.

• start  optional

  Earliest draw date to include (YYYY-MM-DD).

• end  optional

  Latest draw date to include (YYYY-MM-DD).

• session  optional

  Only draws from this session, for games with several draws a day.

• limit  optional

  Number of draws to return (1-1000). Default 100.

• offset  optional

  Number of draws to skip, for paging. Default 0.

Headers

• X-Api-Key  required

  API Key associated with your account.

Response

The /v1/lotteryhistorical endpoint returns a JSON array of draw objects (same fields as /v1/lottery), or an error.

Parameters

• game  optional

  Return one game.

• state  optional

  Return the games of one US state or territory, e.g. IL.

• country  optional

  Return the games of one country.

Headers

• X-Api-Key  required

  API Key associated with your account.

Response

The /v1/lotterygames endpoint returns a JSON array of game objects, or an error.

• matrix

  Current number format: count and range of main and bonus numbers.

• sessions

  Named draws per day, in order (e.g. ["midday", "evening"]).

• rapid

  true for games that draw every few minutes; their draws are identified by draw_number.

• draw_schedule

  Draw days, local time and IANA time zone; for rapid games, the interval in minutes and the first and last draw times.

• jackpot_odds

  Odds of the top prize as N in 1 in N.

• prize_tiers

  Prize table, where the game has fixed prizes.

• rules_history

  Every number-format change with its effective date.

• extras

  Description of each game-specific key that draws of this game may carry in extras.

• history_start, latest_draw_date

  Range of the archive.

• endpoints, docs

  Where to query the game and its documentation page.

Parameters

• game  required

  powerball, megamillions or millionaireforlife.

• date  required

  Draw date (YYYY-MM-DD). Developer plans: the last two years. Business tier and above: any supported draw.

• numbers  required

  Main numbers on the ticket, comma separated.

• bonus  required

  Bonus ball on the ticket (Powerball, Mega Ball or Millionaire Ball).

• power_play  optional

  Powerball only: true if the ticket has Power Play.

• double_play  optional

  Powerball only: true to also score the Double Play draw.

• multiplier  optional

  Mega Millions only: the 2x-10x multiplier printed on the ticket (2, 3, 4, 5 or 10). Without it, the prize range is returned.

Headers

• X-Api-Key  required

  API Key associated with your account.

Response

The /v1/lotterycheck endpoint returns a JSON object with the following fields, or an error.

• matched_main, matched_bonus

  How many main and bonus numbers matched.

• tier

  Prize tier, e.g. 3+1.

• prize

  Prize amount, "jackpot". Mega Millions without multiplier returns prize_min and prize_max instead.

• double_play

  Result of the Double Play draw, when requested.

• disclaimer

  Reminder that only the official lottery pays prizes.

Parameters

• country  optional

  ISO 3166-1 alpha-2 code, e.g. US.

• state  optional

  US state or territory code, e.g. TX.

• currency  optional

  ISO 4217 code, e.g. USD.

• min  optional

  Only jackpots of at least this amount.

Headers

• X-Api-Key  required

  API Key associated with your account.

Response

The /v1/lotteryjackpots endpoint returns a JSON array of jackpot objects, or an error.

• game, game_name, country

  The game.

• draw_date, draw_time

  When the jackpot will be drawn.

• amount, cash_value, currency

  Advertised jackpot and its cash value, where published.

• last_draw_date

  Date of the draw that set this estimate.