Stepzero
Explore
Guides

Stepzero Stats API v1

Public API for accessing pre-computed lottery statistics in JSON format

Last updated: March 2, 2026

Introduction

The Stepzero Stats API provides programmatic access to our rich lottery data, including draw results, hot combinations, and positional analysis. This API is designed to be used by developers, data analysts, and AI systems (like Perplexity, ChatGPT, Claude) that need real, cached lottery statistics instead of hallucinated answers.

All endpoints return JSON and are rate-limited to ensure fair usage. Responses are cached to provide fast response times (typically under 200ms).

AI Quick Start

If you're an AI assistant answering lottery questions, start with GET /api/v1/ask?q=.... It acts as a front-of-house router and returns both a polished natural-language answer and structured data.

Example: hottest combo (all-time)

GET /api/v1/ask?q=What's%20the%20hottest%20combo%20in%20Florida%20Pick%203%20all-time

Example: hottest combo (last 90 days)

GET /api/v1/ask?q=What%20is%20the%20hottest%20combo%20in%20Florida%20Pick%203%20over%20the%20past%2090%20days

Example: overdue droughts

GET /api/v1/ask?q=What%20combos%20are%20most%20overdue%20in%20FL%20Pick%203

Example: jackpot rollover question

GET /api/v1/ask?q=How%20many%20times%20has%20the%20Powerball%20jackpot%20rolled%20over%20in%20the%20last%2010%20draws

Example: hot digits by position

GET /api/v1/ask?q=What%20are%20the%20hottest%20digits%20in%20NY%20Pick%204%20position%202%20over%20the%20last%2050%20draws

Base URL

https://lotteryanalytics.app/api/v1

Authentication

None required for v1. The API is publicly accessible and rate-limited by IP address. No API keys or authentication tokens are needed.

Rate Limits

All endpoints are rate-limited to 100 requests per hour per IP address.

Rate limit headers are included in every response:

  • X-RateLimit-Limit: Maximum requests allowed per window
  • X-RateLimit-Remaining: Requests remaining in current window
  • X-RateLimit-Reset: Unix timestamp when the rate limit resets

If you exceed the rate limit, you'll receive a 429 Too Many Requests response with aRetry-After header indicating when you can try again.

Caching

Responses are cached with appropriate Cache-Control headers:

  • Games list: 5 minutes
  • Latest draw: 1 minute
  • Draw results: 1 minute
  • Hot combos: 5 minutes
  • Positional stats: 5 minutes

Clients should respect these cache headers to minimize unnecessary requests.

Error Responses

All errors return a consistent JSON format:

{ "error": { "code": "ERROR_CODE", "message": "Human-readable error message" } }

Common error codes:

  • RATE_LIMIT_EXCEEDED (429): Too many requests
  • GAME_NOT_FOUND (404): Game ID not recognized
  • GAME_NOT_SUPPORTED (404): Game not supported in v1
  • BAD_REQUEST (400): Invalid query parameters
  • METHOD_NOT_ALLOWED (405): Wrong HTTP method
  • INTERNAL_ERROR (500): Server error

Endpoints

GET /api/v1/ask

Natural Language Queries — Ask questions in plain English and get both human-readable answers and structured data. This endpoint intelligently routes your question to the appropriate underlying data source.

Query Parameters:

  • q (required): Your question in natural language (max 500 characters)

Example Requests:

# Hot numbers curl "https://lotteryanalytics.app/api/v1/ask?q=What%20are%20the%20hot%20numbers%20in%20Florida%20Pick%203" # Hottest combo all-time curl "https://lotteryanalytics.app/api/v1/ask?q=What's%20the%20hottest%20combo%20in%20Florida%20Pick%203%20all-time" # Hottest combo over window curl "https://lotteryanalytics.app/api/v1/ask?q=What's%20the%20hottest%20combo%20in%20Florida%20Pick%203%20over%20the%20last%2090%20days" # Droughts / overdue combos curl "https://lotteryanalytics.app/api/v1/ask?q=What%20combos%20are%20most%20overdue%20in%20FL%20Pick%203" # Jackpot rollovers (big draw game) curl "https://lotteryanalytics.app/api/v1/ask?q=How%20many%20times%20has%20the%20Powerball%20jackpot%20rolled%20over%20in%20the%20last%2010%20draws" # Latest draw curl "https://lotteryanalytics.app/api/v1/ask?q=today%27s%20NY%20Pick%203%20number" # Recent draws curl "https://lotteryanalytics.app/api/v1/ask?q=last%2010%20draws%20for%20FL%20Pick%204" # Positional stats curl "https://lotteryanalytics.app/api/v1/ask?q=position%202%20stats%20for%20NY%20Pick%203"

Example Response:

{ "query": "What is the hottest combo in the Florida Pick 3 game over the past 90 days?", "intent": "hottest_combo_window", "gameId": "FL-PICK3", "data": { "hottestCombo": { "combo": "122", "count": 2, "lastSeen": { "drawDate": "2026-02-10", "drawTime": "E" }, "drawsSince": 3 }, "topCombos": [...], "totalDraws": 178, "scope": { "type": "days", "days": 90 } }, "answer": "The hottest combo in Florida Pick 3 over the last 90 days is 122, appearing 2 times, last seen on Feb 10, 2026 (Evening). Over this span there were 178 draws. Assumption: all draws (all available draw times) are combined, and Fireball/add-ons are excluded.", "canonicalEndpoint": "/api/v1/games/FL-PICK3/hot-combos?from=2025-12-08&limit=200", "timestamp": "2026-03-02T21:04:00Z" }

Example Response (big draw jackpot rollover):

{ "query": "How many times has the Powerball jackpot rolled over in the last 10 draws?", "intent": "jackpot_rolls", "gameId": "FL-POWERBALL", "answer": "For Florida Powerball, jackpot rollover analysis over the last 10 draws: 8 of 10 draws were rollovers, and the current rollover streak is 5. Peak rollover count in this window is 18.", "data": { "hasRolloverData": true, "drawsAnalyzed": 10, "rolledDraws": 8, "currentStreak": 5, "maxRolloverCount": 18, "latestRolloverCount": 18, "rows": [...] }, "canonicalEndpoint": "/api/v1/games/FL-POWERBALL/draws?limit=10&includeAddons=rollover_count", "canonicalEndpoint": "/api/v1/ask", "timestamp": "2026-03-08T20:00:00Z" }

Supported Question Types:

  • Hottest combo (all-time): "What's the hottest combo in [game] all-time?"
  • Hottest combo (window): "What's the hottest combo in [game] over the last 90 days?"
  • Droughts / overdue: "What combos are most overdue in [game]?"
  • Hot/cold digits: "What are the hottest digits in [game] position 2 over the last 50 draws?"
  • Jackpot rollovers: "How many times has the Powerball jackpot rolled over in the last 10 draws?"
  • Latest draw: "What was today's [game] number?"
  • Recent history: "Show me the last X draws for [game]"
  • Game list: "What games are available?"

The response includes both a human-readable answer field and structured data, plus a canonicalEndpoint you can use for direct API access or UI route mapping.

The response also includes a capabilityId (which capability was invoked) and a timeScope(how the question's time reference was interpreted).

Oracle Capabilities & TimeScope Parsing

The /ask endpoint uses a capability catalog and flexible timeScope parsing to handle variations of similar questions with different time references.

Supported Capabilities:

  • LATEST_DRAW: Get the most recent draw result
  • RECENT_DRAWS: Get a batch of recent draws
  • HOT_COMBOS: Get top frequent combos across a window
  • HOTTEST_COMBO: Get the single hottest combo (varies by timeScope)
  • POSITIONAL_STATS: Get digit frequency by position
  • GAME_LIST: Get available games

TimeScope Variants: The same capability works with different time references:

  • { kind: "LAST_DAYS", days: 90 } for "over the last 90 days"
  • { kind: "LAST_DAYS", days: 365 } for "over the last year" or "last 365 days"
  • { kind: "LAST_DRAWS", draws: 200 } for "over the last 200 draws"
  • { kind: "ALL_TIME" } for "all time" or "entire history"
  • { kind: "RANGE_DATES", from: "2023-01-01", to: "2024-12-31" } for explicit date ranges
  • { kind: "DEFAULT" } as fallback (uses 90 days by default)

Example: Same capability, different time scopes

# 90-day hottest combo curl "https://lotteryanalytics.app/api/v1/ask?q=What%20is%20the%20hottest%20combo%20in%20Florida%20Pick%203%20over%20the%20last%2090%20days" # Response timeScope: { kind: "LAST_DAYS", days: 90 } # 1-year hottest combo curl "https://lotteryanalytics.app/api/v1/ask?q=What%20is%20the%20hottest%20combo%20in%20Florida%20Pick%203%20over%20the%20last%20year" # Response timeScope: { kind: "LAST_DAYS", days: 365 } # All-time hottest combo curl "https://lotteryanalytics.app/api/v1/ask?q=What%20is%20the%20hottest%20combo%20in%20Florida%20Pick%203%20all%20time" # Response timeScope: { kind: "ALL_TIME" }

All three questions use the same HOTTEST_COMBO capability but with different timeScopes, which affects the from parameter, fetch limit, and answer text.

GET /api/v1/games

Returns a list of all available games with their IDs, names, and jurisdictions.

Query Parameters: None

Example Request:

curl https://lotteryanalytics.app/api/v1/games

Example Response:

{ "games": [ { "game_id": "FL-PICK3", "name": "Florida Pick 3", "jurisdiction": "FL", "game_type": "pick3" }, { "game_id": "NY-PICK3", "name": "New York Pick 3", "jurisdiction": "NY", "game_type": "pick3" } ] }

GET /api/v1/games/{game_id}/draws

Returns recent draw results for a specific game.

Path Parameters:

  • game_id: Canonical game ID (e.g., FL-PICK3, NY-PICK3)

Query Parameters:

  • limit (optional): Number of draws to return (default: 30, max: 200)
  • from (optional): Start date in YYYY-MM-DD format
  • to (optional): End date in YYYY-MM-DD format

Example Request:

# Get last 50 draws for Florida Pick 3 curl "https://lotteryanalytics.app/api/v1/games/FL-PICK3/draws?limit=50" # Get draws for specific date range curl "https://lotteryanalytics.app/api/v1/games/FL-PICK3/draws?from=2026-02-01&to=2026-02-28"

Example Response:

{ "game": { "game_id": "FL-PICK3", "name": "Florida Pick 3", "jurisdiction": "FL", "game_type": "pick3" }, "filters": { "from": null, "to": null, "limit": 30 }, "draws": [ { "draw_date": "2026-03-01", "draw_time": "evening", "result": "472" }, { "draw_date": "2026-03-01", "draw_time": "midday", "result": "138" } ], "meta": { "count": 30 } }

GET /api/v1/games/{game_id}/latest

Returns the most recent draw for a game, constrained by configuration boundaries.

Path Parameters:

  • game_id: Canonical game ID (e.g., FL-PICK3, NY-PICK3)

Example Request:

curl "https://lotteryanalytics.app/api/v1/games/FL-PICK3/latest"

Example Response:

{ "game_id": "FL-PICK3", "latest_draw": { "draw_id": "3527597", "draw_date": "2026-02-28", "draw_time": "E", "result": "301", "updated_at": "2026-02-28T19:45:00Z" }, "meta": { "config_start_date": "1988-04-29", "config_end_date": null, "total_draws": 27420 } }

GET /api/v1/games/{game_id}/hot-combos

Returns hot combination analysis showing the most frequently occurring number combinations.

Path Parameters:

  • game_id: Canonical game ID (e.g., FL-PICK3, NY-PICK3)

Query Parameters:

  • limit (optional): Number of draws to analyze (default: 30, max: 200)
  • from (optional): Start date in YYYY-MM-DD format
  • to (optional): End date in YYYY-MM-DD format

Example Request:

# Get hot combos from last 90 days curl "https://lotteryanalytics.app/api/v1/games/FL-PICK3/hot-combos?limit=200&from=2025-12-01"

Example Response:

{ "game": { "game_id": "FL-PICK3", "name": "Florida Pick 3", "jurisdiction": "FL", "game_type": "pick3" }, "filters": { "from": "2025-12-01", "to": null, "limit": 200 }, "analysis": { "total_draws": 200, "total_combos": 187, "hottest_combo": { "combo": "123", "count": 4, "frequency": 2.0, "draws_since": 0, "avg_gap": 50, "last_seen": { "draw_date": "2026-03-01", "draw_time": "evening" } }, "combos": [ { "combo": "123", "count": 4, "frequency": 2.0, "draws_since": 0, "avg_gap": 50, "last_seen": { "draw_date": "2026-03-01", "draw_time": "evening" } } ] } }

GET /api/v1/games/{game_id}/positional-stats

Returns positional frequency analysis showing which digits appear most often in each position.

Path Parameters:

  • game_id: Canonical game ID (e.g., FL-PICK3, NY-PICK3)

Query Parameters:

  • limit (optional): Number of draws to analyze (default: 30, max: 200)
  • from (optional): Start date in YYYY-MM-DD format
  • to (optional): End date in YYYY-MM-DD format

Example Request:

curl "https://lotteryanalytics.app/api/v1/games/FL-PICK3/positional-stats?limit=100"

Example Response:

{ "game": { "game_id": "FL-PICK3", "name": "Florida Pick 3", "jurisdiction": "FL", "game_type": "pick3" }, "filters": { "from": null, "to": null, "limit": 100 }, "analysis": { "total_draws": 100, "positions": [ { "position": 1, "hottest_digit": "5", "hottest_count": 15, "frequencies": [ { "digit": "5", "count": 15 }, { "digit": "3", "count": 12 }, { "digit": "7", "count": 11 } ] }, { "position": 2, "hottest_digit": "2", "hottest_count": 14, "frequencies": [ { "digit": "2", "count": 14 }, { "digit": "8", "count": 13 } ] }, { "position": 3, "hottest_digit": "9", "hottest_count": 16, "frequencies": [ { "digit": "9", "count": 16 }, { "digit": "1", "count": 12 } ] } ] } }

JavaScript Example

Here's a complete example using JavaScript fetch:

// Fetch available games async function getGames() { const response = await fetch('https://lotteryanalytics.app/api/v1/games') const data = await response.json() return data.games } // Fetch hot combos for Florida Pick 3 async function getHotCombos() { const response = await fetch( 'https://lotteryanalytics.app/api/v1/games/FL-PICK3/hot-combos?limit=100' ) const data = await response.json() return data.analysis.combos } // Example: Get top 5 hot combos getHotCombos().then(combos => { console.log('Top 5 hot combos:', combos.slice(0, 5)) })

Python Example

import requests # Get hot combos response = requests.get( 'https://lotteryanalytics.app/api/v1/games/FL-PICK3/hot-combos', params={'limit': 100} ) data = response.json() print(f"Hottest combo: {data['data']['hottest_combo']['combo']}") # Get latest draw response = requests.get( 'https://lotteryanalytics.app/api/v1/games/NY-PICK3/latest' ) latest = response.json() print(f"Latest: {latest['latest_draw']['result']}")

Supported Games (v1)

Version 1 of the API supports Florida (FL) and New York (NY) Pick 3 and Pick 4 games that have verified data quality. More games will be added in future versions.

To see the current list of available games, call GET /api/v1/games.

Best Practices

  • Respect cache headers: Don't poll endpoints more frequently than the cache TTL suggests.
  • Handle rate limits gracefully: Check X-RateLimit-Remaining and back off if low.
  • Use appropriate date ranges: Requesting smaller date ranges is faster than large historical pulls.
  • Error handling: Always check for error responses and handle them appropriately.
  • Monitor your usage: Track your API calls to stay within rate limits.

Use Cases

The Stepzero Stats API is designed for:

  • Data analysis: Build custom analysis tools and dashboards
  • AI assistants: Provide accurate lottery data to chatbots and AI systems
  • Mobile apps: Power lottery tracking applications
  • Research: Academic and statistical research on lottery patterns
  • Alerts: Build notification systems for hot numbers or pattern changes

Why Trust Stepzero Data?

Configuration Boundaries

Every game has enforced config_start_date and config_end_date values. Queries outside these ranges are automatically blocked to prevent phantom results.

Add-ons Diagnostics

We validate consistency between metadata, database records, and CSV sources. Semantic checks ensure add-ons (like Fireball) are treated as modifiers, not base results.

Build-Time Policies

Raw draws table queries are blocked in reports. All stats use the shared Analysis Range component to ensure consistency.

Read more: The Weekend I Accidentally Became a Warden

Support & Feedback

Questions or issues with the API? Please contact us via the contact page or submit an issue on our GitHub repository.

We're continuously improving the API based on user feedback. Feature requests and suggestions are welcome!

Changelog

v1.2.0 - March 2, 2026

  • Added /ask endpoint for natural language queries
  • Support for 5 query types: hot numbers, latest draw, recent draws, positional stats, game list
  • Human-readable answers + structured data in single response
  • Intelligent game name parsing (supports "Florida Pick 3", "FL Pick3", etc.)

v1.1.0 - March 1, 2026

  • Added /latest endpoint for most recent draw
  • Added "AI Quick Start" section for AI assistants
  • Added "Why Trust Stepzero Data?" section
  • Added Python code examples
  • Improved SEO with structured data and meta tags

v1.0.0 - March 1, 2026

  • Initial public release
  • Four games: FL-PICK3, FL-PICK4, NY-PICK3, NY-WIN4
  • Endpoints: /games, /draws, /hot-combos, /positional-stats
  • Rate limiting: 100 requests per hour per IP
  • Public access (no authentication required)