{
  "openapi": "3.0.3",
  "info": {
    "title": "ESPOT DATA API",
    "description": "REST API with real economic data from Mexico: gas prices, exchange rates, PROFECO prices, air quality, municipality scores, DENUE businesses, and ESBOT services. All data from official Mexican sources.",
    "version": "1.0.0",
    "contact": {
      "name": "ESPOT",
      "email": "hola@espot.mx",
      "url": "https://espot.mx/developers"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://espot.mx/terminos"
    }
  },
  "servers": [
    {
      "url": "https://espot.mx/api/v1",
      "description": "Production"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "esp_live_*"
      },
      "apiKeyQuery": {
        "type": "apiKey",
        "in": "query",
        "name": "api_key"
      }
    },
    "schemas": {
      "ApiResponse": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "data": {},
          "meta": {
            "type": "object",
            "properties": {
              "timestamp": { "type": "string", "format": "date-time" },
              "source": { "type": "string" },
              "endpoint": { "type": "string" },
              "count": { "type": "integer" }
            }
          }
        }
      },
      "ApiError": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean", "example": false },
          "error": { "type": "string" }
        }
      }
    }
  },
  "security": [{ "bearerAuth": [] }, { "apiKeyQuery": [] }],
  "paths": {
    "/tipo-cambio": {
      "get": {
        "summary": "Get USD/MXN exchange rate",
        "description": "Banxico FIX daily rates plus other currency pairs.",
        "responses": {
          "200": {
            "description": "Array of recent exchange rate records",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } }
          }
        }
      }
    },
    "/gasolina": {
      "get": {
        "summary": "Get gas prices by city",
        "parameters": [
          { "in": "query", "name": "municipio", "schema": { "type": "string" }, "example": "guadalajara" },
          { "in": "query", "name": "tipo", "schema": { "type": "string", "enum": ["magna", "premium", "diesel"] }, "example": "magna" },
          { "in": "query", "name": "limit", "schema": { "type": "integer", "maximum": 100 }, "example": 20 }
        ],
        "responses": {
          "200": { "description": "List of gas stations with prices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }
        }
      }
    },
    "/precios": {
      "get": {
        "summary": "Get PROFECO product prices",
        "parameters": [
          { "in": "query", "name": "ciudad", "schema": { "type": "string" } },
          { "in": "query", "name": "producto", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "List of products with prices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }
        }
      }
    },
    "/score": {
      "get": {
        "summary": "Get municipality quality-of-life score",
        "parameters": [
          { "in": "query", "name": "municipio", "schema": { "type": "string" }, "example": "zapopan" }
        ],
        "responses": {
          "200": { "description": "Municipality score and ranking", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }
        }
      }
    },
    "/negocios": {
      "get": {
        "summary": "Get businesses by city and category (DENUE)",
        "parameters": [
          { "in": "query", "name": "ciudad", "schema": { "type": "string" } },
          { "in": "query", "name": "categoria", "schema": { "type": "string" } },
          { "in": "query", "name": "limit", "schema": { "type": "integer", "maximum": 100 } }
        ],
        "responses": {
          "200": { "description": "List of registered businesses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }
        }
      }
    },
    "/aire": {
      "get": {
        "summary": "Get air quality index (IMECA)",
        "parameters": [
          { "in": "query", "name": "ciudad", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Latest air quality reading", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }
        }
      }
    },
    "/servicios": {
      "get": {
        "summary": "Get local service prices (ESBOT)",
        "description": "Plumbers, electricians, painters, etc. Unique to ESPOT · no equivalent in IMSS or INEGI.",
        "parameters": [
          { "in": "query", "name": "ciudad", "schema": { "type": "string" } },
          { "in": "query", "name": "servicio", "schema": { "type": "string" } },
          { "in": "query", "name": "limit", "schema": { "type": "integer", "maximum": 200 } }
        ],
        "responses": {
          "200": { "description": "Service prices by city", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }
        }
      }
    }
  }
}