{
  "openapi": "3.0.3",
  "info": {
    "title": "BizIntel API",
    "version": "1.0.0",
    "description": "Business and demographic data sourced from the U.S. Census Bureau (County Business Patterns and American Community Survey 5-Year Estimates), queryable by ZIP code, county, state, and NAICS industry code."
  },
  "servers": [{ "url": "https://bizintelapi.com/api/v1" }, { "url": "/api/v1" }],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key issued from the dashboard, e.g. bi_live_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    },
    "parameters": {
      "zip": {
        "name": "zip",
        "in": "query",
        "schema": { "type": "string", "pattern": "^\\d{5}$" },
        "description": "5-digit ZIP code. One of zip, state, or county is required."
      },
      "state": {
        "name": "state",
        "in": "query",
        "schema": { "type": "string", "minLength": 2, "maxLength": 2 },
        "description": "2-letter state FIPS or postal code."
      },
      "county": {
        "name": "county",
        "in": "query",
        "schema": { "type": "string", "pattern": "^\\d{5}$" },
        "description": "5-digit county FIPS code (state + county)."
      },
      "naics": {
        "name": "naics",
        "in": "query",
        "schema": { "type": "string", "pattern": "^\\d{2,6}$" },
        "description": "NAICS industry code, 2-6 digits."
      },
      "year": {
        "name": "year",
        "in": "query",
        "schema": { "type": "integer" },
        "description": "Reference year for the data."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "UNAUTHORIZED",
                  "FORBIDDEN",
                  "QUOTA_EXCEEDED",
                  "RATE_LIMITED",
                  "NOT_FOUND",
                  "VALIDATION_ERROR",
                  "INTERNAL_ERROR"
                ]
              },
              "message": { "type": "string" },
              "details": {}
            }
          }
        }
      }
    }
  },
  "security": [{ "ApiKeyAuth": [] }],
  "paths": {
    "/health": {
      "get": {
        "summary": "Liveness check",
        "security": [],
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/locations/{zip}": {
      "get": {
        "summary": "Look up a ZIP code's geography record",
        "parameters": [{ "name": "zip", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "Geography found" },
          "404": {
            "description": "Not found",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    },
    "/industries/{naics}": {
      "get": {
        "summary": "Look up a NAICS industry code",
        "parameters": [{ "name": "naics", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "Industry found" },
          "404": {
            "description": "Not found",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    },
    "/business-statistics": {
      "get": {
        "summary": "Establishment counts, employment, and payroll by geography and industry",
        "parameters": [
          { "$ref": "#/components/parameters/zip" },
          { "$ref": "#/components/parameters/state" },
          { "$ref": "#/components/parameters/county" },
          { "$ref": "#/components/parameters/naics" },
          { "$ref": "#/components/parameters/year" }
        ],
        "responses": {
          "200": { "description": "Business statistics" },
          "400": {
            "description": "Validation error",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          },
          "403": {
            "description": "Monthly quota exceeded",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    },
    "/demographics": {
      "get": {
        "summary": "Population, households, income, and labor-force statistics by geography",
        "parameters": [
          { "$ref": "#/components/parameters/zip" },
          { "$ref": "#/components/parameters/state" },
          { "$ref": "#/components/parameters/county" },
          { "$ref": "#/components/parameters/year" }
        ],
        "responses": {
          "200": { "description": "Demographic statistics" },
          "400": {
            "description": "Validation error",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    },
    "/business-intelligence": {
      "get": {
        "summary": "Combined business + demographic snapshot for a single location",
        "parameters": [
          { "$ref": "#/components/parameters/zip" },
          { "$ref": "#/components/parameters/state" },
          { "$ref": "#/components/parameters/county" },
          { "$ref": "#/components/parameters/naics" },
          { "$ref": "#/components/parameters/year" }
        ],
        "responses": {
          "200": { "description": "Combined business intelligence snapshot" },
          "400": {
            "description": "Validation error",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    }
  }
}