{
  "openapi": "3.0.3",
  "info": {
    "title": "RiskIndex API",
    "version": "1.0.0",
    "description": "Composite geographic risk scores for every US county and ZIP code — natural hazard, crime, road safety, income, health and environment — plus Canadian crime severity and household income. Built entirely from official US and Canadian government data. Scores are statistical percentile comparisons between areas, not predictions, and not a consumer report under the FCRA.",
    "contact": { "name": "RiskIndex", "url": "https://riskindex.dev", "email": "info@riskindex.dev" },
    "termsOfService": "https://riskindex.dev/terms"
  },
  "servers": [
    { "url": "https://api.riskindex.dev/functions/v1/risk", "description": "Production" }
  ],
  "security": [ { "ApiKeyAuth": [] } ],
  "paths": {
    "/keys": {
      "post": {
        "summary": "Create a free API key",
        "description": "Returns an rk_live_ API key for the given email. Free tier: 100 calls/month, evaluation/non-commercial. No key required to call this endpoint.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object", "required": ["email"],
            "properties": { "email": { "type": "string", "format": "email", "example": "you@example.com" } }
          } } }
        },
        "responses": {
          "201": { "description": "Key created", "content": { "application/json": { "schema": {
            "type": "object",
            "properties": {
              "api_key": { "type": "string", "example": "rk_live_..." },
              "tier": { "type": "string", "example": "free" },
              "monthly_limit": { "type": "integer", "example": 100 }
            } } } } },
          "409": { "description": "An active key already exists for this email" },
          "400": { "description": "Valid email required" }
        }
      }
    },
    "/county/{fips}": {
      "get": {
        "summary": "US county risk profile",
        "description": "Full risk profile for a US county: composite score, grade, the three components, all 18 FEMA hazards, crash and crime stats, and ~14 area indicators (income, health, environment).",
        "parameters": [ { "name": "fips", "in": "path", "required": true, "schema": { "type": "string" }, "description": "5-digit county FIPS code", "example": "06037" } ],
        "responses": {
          "200": { "description": "County profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountyProfile" } } } },
          "401": { "description": "Missing or invalid API key" },
          "404": { "description": "County not found" },
          "429": { "description": "Monthly limit reached" }
        }
      }
    },
    "/zip/{zip}": {
      "get": {
        "summary": "US ZIP code risk lookup",
        "description": "ZIP-level hazard score (weighted from census tracts) plus the profile of the primary county the ZIP falls in.",
        "parameters": [ { "name": "zip", "in": "path", "required": true, "schema": { "type": "string" }, "description": "5-digit ZIP code", "example": "90210" } ],
        "responses": {
          "200": { "description": "ZIP profile" },
          "401": { "description": "Missing or invalid API key" },
          "404": { "description": "ZIP not found (ZCTA-based)" }
        }
      }
    },
    "/canada": {
      "get": {
        "summary": "Canadian regions — crime severity + income",
        "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": ["province", "cma"] }, "description": "Filter by region type" } ],
        "responses": { "200": { "description": "List of Canadian regions with CSI and household income" } }
      }
    },
    "/canada/{geo_code}": {
      "get": {
        "summary": "One Canadian region",
        "parameters": [ { "name": "geo_code", "in": "path", "required": true, "schema": { "type": "string" }, "description": "StatCan SGC code (e.g. 35 = Ontario, 35535 = Toronto CMA)", "example": "35535" } ],
        "responses": { "200": { "description": "Region crime severity + income indicators" }, "404": { "description": "Region not found" } }
      }
    },
    "/rankings": {
      "get": {
        "summary": "Ranked US counties",
        "parameters": [
          { "name": "metric", "in": "query", "schema": { "type": "string", "enum": ["composite", "natural_hazard", "road_safety", "crime"], "default": "composite" } },
          { "name": "order", "in": "query", "schema": { "type": "string", "enum": ["asc", "desc"], "default": "desc" } },
          { "name": "state", "in": "query", "schema": { "type": "string" }, "example": "TX" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100, "default": 25 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }
        ],
        "responses": { "200": { "description": "Ranked counties" }, "400": { "description": "Invalid metric" } }
      }
    },
    "/search": {
      "get": {
        "summary": "Filtered US county search",
        "parameters": [
          { "name": "state", "in": "query", "schema": { "type": "string" } },
          { "name": "grade", "in": "query", "schema": { "type": "string", "enum": ["A", "B", "C", "D", "F"] } },
          { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "Partial county name" },
          { "name": "min_composite", "in": "query", "schema": { "type": "number" } },
          { "name": "max_composite", "in": "query", "schema": { "type": "number" } }
        ],
        "responses": { "200": { "description": "Matching counties" } }
      }
    },
    "/sources": {
      "get": { "summary": "Data source freshness log", "responses": { "200": { "description": "All 16 sources with last-refreshed dates and cadence" } } }
    },
    "/usage": {
      "get": { "summary": "Your usage this month", "responses": { "200": { "description": "Tier, monthly limit, and calls used this month" } } }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Your rk_live_ key from POST /keys" }
    },
    "schemas": {
      "CountyProfile": {
        "type": "object",
        "properties": {
          "county": { "type": "object", "properties": {
            "fips": { "type": "string" }, "county_name": { "type": "string" }, "state_abbr": { "type": "string" }, "population": { "type": "integer" }
          } },
          "risk": { "type": "object", "properties": {
            "composite": { "type": "number", "description": "0-100, higher = riskier" },
            "grade": { "type": "string", "enum": ["A", "B", "C", "D", "F"] },
            "natural_hazard": { "type": "number" }, "road_safety": { "type": "number" }, "crime": { "type": "number" }
          } },
          "indicators": { "type": "array", "items": { "type": "object", "properties": {
            "indicator": { "type": "string" }, "value": { "type": "number" }, "source": { "type": "string" }
          } } },
          "methodology": { "type": "string" },
          "disclaimer": { "type": "string" }
        }
      }
    }
  }
}