{
  "openapi": "3.1.0",
  "info": {
    "title": "I7CH Public Lottery Data API",
    "version": "1.0.0",
    "description": "Free, public REST API providing US lottery draw history, hot & cold digit analysis, and state lottery data for all 45 participating US states. Data covers Pick 3 and Pick 4 lottery games. Attribution required: source I7CH (https://i7ch.com) when republishing data. For higher rate limits or bulk data access, contact us at i7ch.com.",
    "contact": {
      "name": "I7CH Support",
      "url": "https://i7ch.com",
      "email": "support@i7ch.com"
    },
    "license": {
      "name": "Attribution Required",
      "url": "https://i7ch.com/terms"
    },
    "x-logo": {
      "url": "https://i7ch.com/brand-logo.png",
      "altText": "I7CH"
    }
  },
  "servers": [
    {
      "url": "https://i7ch.com",
      "description": "Production server"
    }
  ],
  "tags": [
    {
      "name": "States",
      "description": "Retrieve the list of US states with active lottery data"
    },
    {
      "name": "Hot & Cold Analysis",
      "description": "Frequency analysis identifying the most and least common digits in recent draws"
    },
    {
      "name": "Draw Results",
      "description": "Historical draw result data for Pick 3 and Pick 4 games"
    }
  ],
  "paths": {
    "/api/public/states": {
      "get": {
        "tags": ["States"],
        "summary": "List all states with lottery data",
        "description": "Returns a list of all US states and jurisdictions for which I7CH has active lottery draw data. Each entry includes the state code, state name, and links to available data endpoints.",
        "operationId": "getStates",
        "responses": {
          "200": {
            "description": "A list of US states with lottery data",
            "headers": {
              "Cache-Control": {
                "schema": { "type": "string" },
                "description": "public, max-age=3600 — responses are cached for 1 hour"
              },
              "RateLimit-Limit": {
                "schema": { "type": "integer" },
                "description": "Maximum requests allowed per rate limit window"
              },
              "RateLimit-Remaining": {
                "schema": { "type": "integer" },
                "description": "Requests remaining in current window"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatesResponse"
                },
                "example": {
                  "attribution": "I7CH (https://i7ch.com)",
                  "description": "US states with active lottery data on I7CH",
                  "totalStates": 45,
                  "states": [
                    {
                      "code": "TX",
                      "name": "Texas",
                      "endpoints": {
                        "pick3HotCold": "https://i7ch.com/api/public/tx/pick3/hot-cold",
                        "pick4HotCold": "https://i7ch.com/api/public/tx/pick4/hot-cold",
                        "pick3RecentDraws": "https://i7ch.com/api/public/tx/pick3/recent-draws",
                        "pick4RecentDraws": "https://i7ch.com/api/public/tx/pick4/recent-draws"
                      }
                    }
                  ]
                }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimitExceeded" }
        }
      }
    },
    "/api/public/{stateCode}/pick3/hot-cold": {
      "get": {
        "tags": ["Hot & Cold Analysis"],
        "summary": "Pick 3 hot and cold digit analysis",
        "description": "Returns the hottest and coldest digits for Pick 3 lottery draws in the specified state, based on frequency analysis of recent draw history. Hot digits have appeared more often than statistical average; cold digits have appeared less often. Free plan users on I7CH.com see the top 1 hot and 1 cold digit; the full set is available via this API.",
        "operationId": "getPick3HotCold",
        "parameters": [
          { "$ref": "#/components/parameters/stateCode" }
        ],
        "responses": {
          "200": {
            "description": "Pick 3 hot and cold digit analysis",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/HotColdResponse" },
                "example": {
                  "attribution": "I7CH (https://i7ch.com)",
                  "stateCode": "TX",
                  "stateName": "Texas",
                  "gameType": "pick3",
                  "analysisWindow": "last 30 draws",
                  "hot": [
                    { "digit": 7, "count": 28, "pctAboveAvg": 18 },
                    { "digit": 3, "count": 25, "pctAboveAvg": 12 }
                  ],
                  "cold": [
                    { "digit": 1, "count": 14, "pctBelowAvg": 22 },
                    { "digit": 9, "count": 16, "pctBelowAvg": 15 }
                  ],
                  "premiumAccess": "https://i7ch.com/go/premium"
                }
              }
            }
          },
          "404": { "$ref": "#/components/responses/StateNotFound" },
          "429": { "$ref": "#/components/responses/RateLimitExceeded" }
        }
      }
    },
    "/api/public/{stateCode}/pick4/hot-cold": {
      "get": {
        "tags": ["Hot & Cold Analysis"],
        "summary": "Pick 4 hot and cold digit analysis",
        "description": "Returns the hottest and coldest digits for Pick 4 lottery draws in the specified state. Identical structure to the Pick 3 endpoint. Based on frequency analysis of the last 30 Pick 4 draws.",
        "operationId": "getPick4HotCold",
        "parameters": [
          { "$ref": "#/components/parameters/stateCode" }
        ],
        "responses": {
          "200": {
            "description": "Pick 4 hot and cold digit analysis",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/HotColdResponse" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/StateNotFound" },
          "429": { "$ref": "#/components/responses/RateLimitExceeded" }
        }
      }
    },
    "/api/public/{stateCode}/pick3/recent-draws": {
      "get": {
        "tags": ["Draw Results"],
        "summary": "Recent Pick 3 draw results",
        "description": "Returns the last 30 Pick 3 lottery draw results for the specified state, including the draw date, draw time (midday/evening where available), and the winning digit combination.",
        "operationId": "getPick3RecentDraws",
        "parameters": [
          { "$ref": "#/components/parameters/stateCode" }
        ],
        "responses": {
          "200": {
            "description": "Recent Pick 3 draw results",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RecentDrawsResponse" },
                "example": {
                  "attribution": "I7CH (https://i7ch.com)",
                  "stateCode": "TX",
                  "gameType": "pick3",
                  "draws": [
                    { "date": "2026-04-15", "time": "evening", "numbers": ["7", "3", "9"] },
                    { "date": "2026-04-15", "time": "midday", "numbers": ["2", "5", "1"] },
                    { "date": "2026-04-14", "time": "evening", "numbers": ["8", "0", "4"] }
                  ]
                }
              }
            }
          },
          "404": { "$ref": "#/components/responses/StateNotFound" },
          "429": { "$ref": "#/components/responses/RateLimitExceeded" }
        }
      }
    },
    "/api/public/{stateCode}/pick4/recent-draws": {
      "get": {
        "tags": ["Draw Results"],
        "summary": "Recent Pick 4 draw results",
        "description": "Returns the last 30 Pick 4 lottery draw results for the specified state. Identical structure to the Pick 3 recent draws endpoint but for 4-digit games.",
        "operationId": "getPick4RecentDraws",
        "parameters": [
          { "$ref": "#/components/parameters/stateCode" }
        ],
        "responses": {
          "200": {
            "description": "Recent Pick 4 draw results",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RecentDrawsResponse" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/StateNotFound" },
          "429": { "$ref": "#/components/responses/RateLimitExceeded" }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "stateCode": {
        "name": "stateCode",
        "in": "path",
        "required": true,
        "description": "Two-letter US state code (case-insensitive). Examples: tx, ny, ca, fl, oh. DC is also supported.",
        "schema": {
          "type": "string",
          "minLength": 2,
          "maxLength": 2,
          "example": "tx"
        }
      }
    },
    "schemas": {
      "StatesResponse": {
        "type": "object",
        "properties": {
          "attribution": { "type": "string", "example": "I7CH (https://i7ch.com)" },
          "description": { "type": "string" },
          "totalStates": { "type": "integer" },
          "states": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": { "type": "string", "example": "TX" },
                "name": { "type": "string", "example": "Texas" },
                "endpoints": {
                  "type": "object",
                  "properties": {
                    "pick3HotCold": { "type": "string", "format": "uri" },
                    "pick4HotCold": { "type": "string", "format": "uri" },
                    "pick3RecentDraws": { "type": "string", "format": "uri" },
                    "pick4RecentDraws": { "type": "string", "format": "uri" }
                  }
                }
              }
            }
          }
        }
      },
      "HotColdDigit": {
        "type": "object",
        "properties": {
          "digit": { "type": "integer", "minimum": 0, "maximum": 9 },
          "count": { "type": "integer", "description": "Number of times digit appeared in analysis window" },
          "pctAboveAvg": { "type": "number", "description": "Percentage above statistical average (hot digits only)" },
          "pctBelowAvg": { "type": "number", "description": "Percentage below statistical average (cold digits only)" }
        }
      },
      "HotColdResponse": {
        "type": "object",
        "properties": {
          "attribution": { "type": "string" },
          "stateCode": { "type": "string" },
          "stateName": { "type": "string" },
          "gameType": { "type": "string", "enum": ["pick3", "pick4"] },
          "analysisWindow": { "type": "string", "example": "last 30 draws" },
          "hot": { "type": "array", "items": { "$ref": "#/components/schemas/HotColdDigit" } },
          "cold": { "type": "array", "items": { "$ref": "#/components/schemas/HotColdDigit" } },
          "premiumAccess": { "type": "string", "format": "uri" }
        }
      },
      "DrawResult": {
        "type": "object",
        "properties": {
          "date": { "type": "string", "format": "date", "example": "2026-04-15" },
          "time": {
            "type": "string",
            "nullable": true,
            "enum": ["midday", "evening", null],
            "description": "Draw session — midday (~12:30pm), evening (~7:30pm), or null if only one draw per day"
          },
          "numbers": {
            "type": "array",
            "items": { "type": "string" },
            "minItems": 3,
            "maxItems": 4,
            "example": ["7", "3", "9"]
          }
        }
      },
      "RecentDrawsResponse": {
        "type": "object",
        "properties": {
          "attribution": { "type": "string" },
          "stateCode": { "type": "string" },
          "gameType": { "type": "string", "enum": ["pick3", "pick4"] },
          "draws": {
            "type": "array",
            "maxItems": 30,
            "items": { "$ref": "#/components/schemas/DrawResult" }
          }
        }
      }
    },
    "responses": {
      "StateNotFound": {
        "description": "State code not recognized or no data available for this state",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": { "type": "string", "example": "State not found" }
              }
            }
          }
        }
      },
      "RateLimitExceeded": {
        "description": "Rate limit exceeded — 60 requests per minute per IP in production",
        "headers": {
          "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying" }
        },
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": { "type": "string", "example": "Rate limit exceeded. Max 60 requests per minute. For higher limits contact i7ch.com." }
              }
            }
          }
        }
      }
    }
  },
  "x-rate-limits": {
    "default": "60 requests per minute per IP address",
    "caching": "Responses are cached with Cache-Control: public, max-age=1800 (30 minutes for hot/cold, 1 hour for states list)",
    "higherLimits": "Contact https://i7ch.com for bulk data access"
  }
}