Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Ninjas Lottery API
description: 'Combined OpenAPI specification for every API Ninjas endpoint. Requests go to https://api.api-ninjas.com with an `X-Api-Key` header; get a free key at https://api-ninjas.com/register. Human-readable docs: https://api-ninjas.com/api. Index for LLMs: https://api-ninjas.com/llms.txt.'
version: 1.0.0
contact:
name: API Ninjas
url: https://api-ninjas.com
license:
name: Proprietary
servers:
- url: https://api.api-ninjas.com
description: API Ninjas Production
security:
- ApiKeyAuth: []
tags:
- name: Lottery
description: The Lottery API provides winning numbers, jackpots and draw history for Powerball, Mega Millions and the draw games of every US state lottery, plus Puerto Rico and the US Virgin Islands, including keno-style games that draw every few minutes, plus a ticket checker.
paths:
/v1/lottery:
get:
summary: Get the latest or dated draw for a lottery game, state or country
description: Returns the latest draw for a game, the draw on a given date, or the latest draw of every game in a US state or a country. On paid plans results usually appear within minutes of the official publication; on the free plan they appear about 60 minutes later. Provide game, state or country. Returns a JSON object, or a JSON array of them when state or country is used.
operationId: getLotteryDraw
parameters:
- name: game
in: query
required: false
description: Game slug, e.g. powerball, megamillions, us-ny-take5. Common spellings such as mega-millions also work. See /v1/lotterygames for every game. Provide game, state or country.
schema:
type: string
example: powerball
- name: state
in: query
required: false
description: 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. Business tier and above, or any annual plan.
schema:
type: string
example: IL
- name: country
in: query
required: false
description: ISO 3166-1 alpha-2 code (e.g. US). Returns the latest draw of every covered game in that country, in one call. Business tier and above, or any annual plan.
schema:
type: string
example: US
- name: date
in: query
required: false
description: 'Draw date (YYYY-MM-DD). Premium only. Developer plans: the last two years. Business tier and above: any date in the archive.'
schema:
type: string
format: date
example: '2026-10-05'
- name: session
in: query
required: false
description: For games with several draws a day (e.g. midday, evening). Defaults to the latest draw that day.
schema:
type: string
example: evening
- name: draw_number
in: query
required: false
description: '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.'
schema:
type: integer
security:
- ApiKeyAuth: []
responses:
'200':
description: Successful response
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/LotteryDraw'
- type: array
items:
$ref: '#/components/schemas/LotteryDraw'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
tags:
- Lottery
/v1/lotteryhistorical:
get:
summary: Get past draws for a lottery game
description: Returns past draws for a game, newest first. The free plan gets the latest 10 draws (each visible about 60 minutes after the draw); Developer plans a rolling two years; Business tier and above the full archive.
operationId: getLotteryHistoricalDraws
parameters:
- name: game
in: query
required: true
description: Game slug.
schema:
type: string
example: powerball
- name: start
in: query
required: false
description: Earliest draw date to include (YYYY-MM-DD).
schema:
type: string
format: date
- name: end
in: query
required: false
description: Latest draw date to include (YYYY-MM-DD).
schema:
type: string
format: date
- name: session
in: query
required: false
description: Only draws from this session, for games with several draws a day.
schema:
type: string
- name: limit
in: query
required: false
description: Number of draws to return (1-1000). Default 100.
schema:
type: integer
minimum: 1
maximum: 1000
default: 100
- name: offset
in: query
required: false
description: Number of draws to skip, for paging. Default 0.
schema:
type: integer
minimum: 0
default: 0
security:
- ApiKeyAuth: []
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/LotteryHistoricalResponse'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
tags:
- Lottery
/v1/lotterygames:
get:
summary: List lottery games with rules, schedules and odds
description: Lists the covered games with their number format, draw schedule, jackpot odds, prize tiers, rule-change history and archive range.
operationId: listLotteryGames
parameters:
- name: game
in: query
required: false
description: Return one game.
schema:
type: string
example: powerball
- name: state
in: query
required: false
description: Return the games of one US state or territory, e.g. IL.
schema:
type: string
example: IL
- name: country
in: query
required: false
description: Return the games of one country.
schema:
type: string
example: US
security:
- ApiKeyAuth: []
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/LotteryGamesResponse'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
tags:
- Lottery
/v1/lotterycheck:
get:
summary: Check a lottery ticket against a draw
description: Premium only. Scores a ticket against a draw and returns the matched prize tier and prize. Supports Powerball (with Power Play and Double Play), Mega Millions (with the ticket's built-in multiplier) and Millionaire for Life. Ticket numbers are never stored. The result is not a prize claim.
operationId: checkLotteryTicket
parameters:
- name: game
in: query
required: true
description: powerball, megamillions or millionaireforlife.
schema:
type: string
enum:
- powerball
- megamillions
- millionaireforlife
example: powerball
- name: date
in: query
required: true
description: 'Draw date (YYYY-MM-DD). Developer plans: the last two years. Business tier and above: any supported draw.'
schema:
type: string
format: date
example: '2026-10-05'
- name: numbers
in: query
required: true
description: Main numbers on the ticket, comma separated.
schema:
type: string
example: 16,23,32,1,2
- name: bonus
in: query
required: true
description: Bonus ball on the ticket (Powerball, Mega Ball or Millionaire Ball).
schema:
type: integer
example: 9
- name: power_play
in: query
required: false
description: 'Powerball only: true if the ticket has Power Play.'
schema:
type: boolean
example: true
- name: double_play
in: query
required: false
description: 'Powerball only: true to also score the Double Play draw.'
schema:
type: boolean
example: true
- name: multiplier
in: query
required: false
description: 'Mega Millions only: the 2x-10x multiplier printed on the ticket (2, 3, 4, 5 or 10). Without it, the prize range is returned.'
schema:
type: integer
enum:
- 2
- 3
- 4
- 5
- 10
security:
- ApiKeyAuth: []
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/LotteryCheckResponse'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
tags:
- Lottery
/v1/lotteryjackpots:
get:
summary: List upcoming lottery jackpots
description: Premium only. Lists the next advertised jackpot for every active game that publishes one, largest first within each currency.
operationId: listLotteryJackpots
parameters:
- name: country
in: query
required: false
description: ISO 3166-1 alpha-2 code, e.g. US.
schema:
type: string
example: US
- name: state
in: query
required: false
description: US state or territory code, e.g. TX.
schema:
type: string
example: TX
- name: currency
in: query
required: false
description: ISO 4217 code, e.g. USD.
schema:
type: string
example: USD
- name: min
in: query
required: false
description: Only jackpots of at least this amount.
schema:
type: number
security:
- ApiKeyAuth: []
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/LotteryJackpotsResponse'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
tags:
- Lottery
components:
schemas:
LotteryGame:
type: object
properties:
game:
type: string
example: powerball
description: Game slug.
name:
type: string
example: Powerball
description: Display name of the game.
country:
type: string
example: US
description: ISO 3166-1 alpha-2 country code.
subdivision:
type:
- string
- 'null'
description: ISO 3166-2 code of the state or territory, for state games (e.g. US-NY).
operator:
type: string
example: Multi-State Lottery Association
description: The lottery operator that runs the game.
currency:
type: string
example: USD
description: ISO 4217 currency code of the game's prizes.
ticket_price:
type:
- number
- 'null'
example: 2
description: Price of one play.
status:
type: string
example: active
description: Game status, e.g. active.
sessions:
type:
- array
- 'null'
items:
type: string
description: Named draws per day, in order (e.g. ["midday", "evening"]).
rapid:
type: boolean
description: true for games that draw every few minutes; their draws are identified by draw_number.
draw_schedule:
type: object
description: Draw days, local time and IANA time zone; for rapid games, the interval in minutes and the first and last draw times.
properties:
days:
type: array
items:
type: string
description: Draw days (mon, tue, wed, thu, fri, sat, sun).
time:
type:
- string
- 'null'
description: Local draw time (HH:MM).
timezone:
type: string
description: IANA time zone of the draw time.
every_minutes:
type: integer
description: 'Rapid games: minutes between draws.'
first:
type: string
description: 'Rapid games: local time of the first draw of the day (HH:MM).'
last:
type: string
description: 'Rapid games: local time of the last draw of the day (HH:MM).'
matrix:
type: object
description: 'Current number format: count and range of main and bonus numbers.'
properties:
main:
$ref: '#/components/schemas/LotteryNumberFormat'
bonus:
$ref: '#/components/schemas/LotteryNumberFormat'
bonus_name:
type:
- string
- 'null'
example: Powerball
description: Name of the bonus ball, when the game has one.
add_ons:
type: array
items:
type: string
description: Add-on plays and extra draws offered with the game, e.g. Power Play or Double Play.
jackpot_odds:
type:
- integer
- 'null'
example: 292201338
description: Odds of the top prize as N in 1 in N.
prize_tiers:
type:
- array
- 'null'
items:
type: object
properties:
tier:
type: string
description: Prize tier, e.g. 5+1.
match_main:
type: integer
description: Main numbers matched.
match_bonus:
type: integer
description: Bonus numbers matched.
prize:
oneOf:
- type: number
- type: string
description: Prize amount, or "jackpot".
description: Prize table, where the game has fixed prizes.
prize_tiers_per_draw:
type: boolean
description: Whether prizes are set per draw rather than fixed.
rules_history:
type: array
items:
type: object
properties:
effective:
type:
- string
- 'null'
format: date
description: Date the number format took effect (YYYY-MM-DD).
main:
$ref: '#/components/schemas/LotteryNumberFormat'
bonus:
$ref: '#/components/schemas/LotteryNumberFormat'
note:
type: string
description: Summary of the number format.
description: Every number-format change with its effective date.
history_start:
type: string
format: date
example: '2010-02-03'
description: Date of the earliest draw in the archive (YYYY-MM-DD).
latest_draw_date:
type: string
format: date
example: '2026-10-05'
description: Date of the latest draw in the archive (YYYY-MM-DD).
extras:
type:
- object
- 'null'
description: Description of each game-specific key that draws of this game may carry in extras.
additionalProperties:
type: string
properties: {}
endpoints:
type: array
items:
type: string
example:
- /v1/lottery?game=powerball
- /v1/lotteryhistorical?game=powerball
description: Where to query the game.
docs:
type: string
example: https://api-ninjas.com/api/powerball
description: The game's documentation page.
LotteryGamesResponse:
type: array
items:
$ref: '#/components/schemas/LotteryGame'
LotteryCheckResponse:
type: object
properties:
game:
type: string
example: powerball
description: Game slug.
draw_date:
type: string
format: date
example: '2026-10-05'
description: Draw date that was checked (YYYY-MM-DD).
numbers:
type: array
items:
type: integer
example:
- 16
- 23
- 32
- 1
- 2
description: Main numbers on the ticket.
bonus:
type: array
items:
type: integer
example:
- 9
description: Bonus ball on the ticket.
matched_main:
type: integer
example: 3
description: How many main numbers matched.
matched_bonus:
type: integer
example: 1
description: How many bonus numbers matched.
tier:
type:
- string
- 'null'
example: 3+1
description: Prize tier, e.g. 3+1.
prize:
oneOf:
- type: number
- type: string
description: Prize amount, or "jackpot". Mega Millions without multiplier returns prize_min and prize_max instead.
example: 200
currency:
type: string
example: USD
description: ISO 4217 currency code of the prize.
prize_min:
type: number
example: 400
description: 'Mega Millions without multiplier: lowest prize for the matched tier.'
prize_max:
type: number
example: 2000
description: 'Mega Millions without multiplier: highest prize for the matched tier.'
prize_note:
type: string
description: 'Mega Millions without multiplier: explains the prize range.'
double_play:
allOf:
- $ref: '#/components/schemas/LotteryCheckResult'
description: Result of the Double Play draw, when requested.
LotteryCheckResult:
type: object
properties:
matched_main:
type: integer
description: How many main numbers matched.
matched_bonus:
type: integer
description: How many bonus numbers matched.
tier:
type:
- string
- 'null'
description: Prize tier, e.g. 3+1.
prize:
oneOf:
- type: number
- type: string
description: Prize amount, or "jackpot".
LotteryNextDrawJackpot:
type:
- object
- 'null'
description: Premium only. Estimated jackpot and cash value of the next draw. On the free plan it reads `This field is for premium subscribers only.`
properties:
currency:
type: string
description: ISO 4217 currency code of the jackpot.
amount:
type: integer
description: Estimated advertised jackpot amount.
cash_value:
type: integer
description: Estimated cash value of the jackpot.
estimated:
type: boolean
description: Whether the amount is an estimate.
LotteryDraw:
type: object
properties:
game:
type: string
example: powerball
description: Game slug, e.g. powerball.
game_name:
type: string
example: Powerball
description: Display name of the game.
country:
type: string
example: US
description: ISO 3166-1 alpha-2 country code.
draw_date:
type: string
format: date
example: '2026-10-05'
description: Draw date in the operator's local time zone (YYYY-MM-DD).
session:
type: string
description: 'Only for games with several named draws a day: e.g. midday or evening.'
draw_number:
type: integer
description: The operator's draw number. Games that draw every few minutes (keno and similar) are identified by it.
draw_time:
type: string
format: date-time
example: '2026-10-05T22:59:00-04:00'
description: Scheduled draw time in ISO 8601 with the operator's UTC offset.
main_numbers:
type: array
items:
type: integer
example:
- 16
- 23
- 32
- 36
- 54
description: 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:
type: array
items:
type: integer
example:
- 9
description: 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:
type: string
example: Powerball
description: Name of the bonus ball, when the game has one.
multiplier:
type: integer
example: 2
description: Drawn multiplier (e.g. Power Play), when the game draws one.
multiplier_name:
type: string
example: Power Play
description: Name of the multiplier.
secondary_draws:
type: array
items:
$ref: '#/components/schemas/LotterySecondaryDraw'
description: Extra draws on the same ticket, e.g. Powerball Double Play or Illinois Lotto's Lotto Million 1 and Lotto Million 2.
extras:
type: object
description: 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.
additionalProperties: true
properties: {}
jackpot:
$ref: '#/components/schemas/LotteryJackpot'
next_draw:
type: object
description: Date and time of the next draw, and its estimated jackpot.
properties:
draw_date:
type: string
format: date
description: Date of the next draw (YYYY-MM-DD).
draw_time:
type: string
format: date-time
description: Scheduled time of the next draw in ISO 8601 with the operator's UTC offset.
jackpot:
$ref: '#/components/schemas/LotteryNextDrawJackpot'
rules_version:
type:
- string
- 'null'
example: '2015-10-07'
description: 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:
type: integer
example: 1
description: Starts at 1 and increases if the operator corrects the draw.
message:
type: string
description: 'Only on the free plan: explains the 60-minute delay and the premium fields.'
LotteryHistoricalResponse:
type: array
items:
$ref: '#/components/schemas/LotteryDraw'
description: Past draws for a game, newest first (same fields as /v1/lottery).
LotterySecondaryDraw:
type: object
properties:
name:
type: string
description: Name of the extra draw, e.g. Double Play, Lotto Million 1 or Lotto Million 2.
main_numbers:
type: array
items:
type: integer
description: Winning numbers of the extra draw.
bonus_numbers:
type: array
items:
type: integer
description: Bonus ball(s) of the extra draw.
LotteryJackpot:
type:
- object
- 'null'
description: 'Jackpot for this draw: currency, amount (advertised), cash_value, estimated and won.'
properties:
currency:
type: string
description: ISO 4217 currency code of the jackpot.
amount:
type: integer
description: Advertised jackpot amount.
cash_value:
type: integer
description: Premium only. Cash value of this draw's jackpot. On the free plan it reads `This field is for premium subscribers only.`
estimated:
type: boolean
description: Whether the amount is an estimate.
won:
type: boolean
description: Whether the jackpot was won in this draw.
LotteryJackpotEntry:
type: object
properties:
game:
type: string
example: powerball
description: Game slug.
game_name:
type: string
example: Powerball
description: Display name of the game.
country:
type: string
example: US
description: ISO 3166-1 alpha-2 country code.
draw_date:
type: string
format: date
example: '2026-10-07'
description: Date the jackpot will be drawn (YYYY-MM-DD).
draw_time:
type: string
format: date-time
example: '2026-10-07T22:59:00-04:00'
description: Scheduled draw time in ISO 8601 with the operator's UTC offset.
currency:
type: string
example: USD
description: ISO 4217 currency code of the jackpot.
amount:
type: integer
example: 485000000
description: Advertised jackpot.
cash_value:
type:
- integer
- 'null'
example: 199800000
description: Cash value of the jackpot.
estimated:
type: boolean
example: true
description: Whether the amount is an estimate.
last_draw_date:
type: string
format: date
example: '2026-10-05'
description: Date of the draw that set this estimate (YYYY-MM-DD).
LotteryNumberFormat:
type:
- object
- 'null'
properties:
count:
type: integer
description: How many numbers are drawn.
min:
type: integer
description: Lowest possible number.
max:
type: integer
description: Highest possible number.
unique:
type: boolean
description: Whether each number can be drawn only once.
same_pool:
type: boolean
description: 'Bonus only: whether the bonus number is drawn from the same pool as the main numbers.'
LotteryJackpotsResponse:
type: array
items:
$ref: '#/components/schemas/LotteryJackpotEntry'
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-Api-Key
externalDocs:
description: API Ninjas documentation
url: https://api-ninjas.com/api