{
  "openapi": "3.1.0",
  "info": {
    "title": "Park Graph Intelligence API",
    "version": "2.0.0",
    "description": "Parking market intelligence — rates, demand forecasts, and AI agent analytics. Requires an API key with the `intelligence` scope.",
    "contact": {
      "name": "Park Graph",
      "url": "https://parkgraph.com/developers/intelligence-api"
    }
  },
  "servers": [
    {
      "url": "https://parkgraph.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v2/intelligence/market-rate": {
      "get": {
        "operationId": "getMarketRate",
        "summary": "Get market rate data for a location",
        "description": "Returns average hourly/daily rates, rate ranges, demand scores, and competitor counts within a radius of the given coordinates.",
        "parameters": [
          {
            "name": "lat",
            "in": "query",
            "required": true,
            "schema": { "type": "number", "minimum": -90, "maximum": 90 },
            "description": "Latitude of the center point"
          },
          {
            "name": "lng",
            "in": "query",
            "required": true,
            "schema": { "type": "number", "minimum": -180, "maximum": 180 },
            "description": "Longitude of the center point"
          },
          {
            "name": "radius_km",
            "in": "query",
            "required": false,
            "schema": { "type": "number", "minimum": 0.1, "maximum": 50, "default": 5 },
            "description": "Search radius in kilometers (default: 5)"
          }
        ],
        "responses": {
          "200": {
            "description": "Market rate data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "location": {
                          "type": "object",
                          "properties": {
                            "lat": { "type": "number" },
                            "lng": { "type": "number" },
                            "radius_km": { "type": "number" }
                          }
                        },
                        "market_rate": {
                          "type": "object",
                          "properties": {
                            "avg_hourly_cents": { "type": "integer" },
                            "avg_daily_cents": { "type": "integer" },
                            "min_hourly_cents": { "type": "integer" },
                            "max_hourly_cents": { "type": "integer" },
                            "currency": { "type": "string" }
                          }
                        },
                        "demand_score": { "type": "integer", "minimum": 0, "maximum": 100 },
                        "competitor_count": { "type": "integer" },
                        "sample_size": { "type": "integer" },
                        "period": { "type": "string" }
                      }
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ValidationError" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v2/intelligence/demand-forecast": {
      "get": {
        "operationId": "getDemandForecast",
        "summary": "Get demand forecast for a location and date",
        "description": "Returns predicted demand scores, expected occupancy, expected events, and dynamic pricing recommendations.",
        "parameters": [
          {
            "name": "lat",
            "in": "query",
            "required": true,
            "schema": { "type": "number", "minimum": -90, "maximum": 90 }
          },
          {
            "name": "lng",
            "in": "query",
            "required": true,
            "schema": { "type": "number", "minimum": -180, "maximum": 180 }
          },
          {
            "name": "date",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "format": "date" },
            "description": "Forecast date in YYYY-MM-DD format"
          },
          {
            "name": "radius_km",
            "in": "query",
            "required": false,
            "schema": { "type": "number", "minimum": 0.1, "maximum": 50, "default": 5 }
          }
        ],
        "responses": {
          "200": {
            "description": "Demand forecast data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "location": {
                          "type": "object",
                          "properties": {
                            "lat": { "type": "number" },
                            "lng": { "type": "number" },
                            "radius_km": { "type": "number" }
                          }
                        },
                        "forecast_date": { "type": "string", "format": "date" },
                        "day_of_week": { "type": "string" },
                        "is_weekend": { "type": "boolean" },
                        "predicted_demand_score": { "type": "integer", "minimum": 0, "maximum": 100 },
                        "expected_sessions": { "type": "integer" },
                        "expected_peak_occupancy": { "type": "integer" },
                        "expected_revenue_cents": { "type": "integer" },
                        "expected_events": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "name": { "type": "string" },
                              "type": { "type": "string" },
                              "impact": { "type": "string", "enum": ["low", "medium", "high"] }
                            }
                          }
                        },
                        "price_recommendation": {
                          "type": "object",
                          "properties": {
                            "recommended_rate_cents": { "type": "integer" },
                            "multiplier": { "type": "number" },
                            "rationale": { "type": "string" }
                          }
                        },
                        "nearby_lots": { "type": "integer" }
                      }
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ValidationError" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v2/intelligence/agent-demand": {
      "get": {
        "operationId": "getAgentDemand",
        "summary": "Get AI agent demand data for a city",
        "description": "Returns AI agent query volumes, platform breakdowns, conversion rates, peak times, top search locations, and coverage data.",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "City name to query"
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "State abbreviation for disambiguation"
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "minimum": 1, "maximum": 90, "default": 30 },
            "description": "Lookback period in days (default: 30)"
          }
        ],
        "responses": {
          "200": {
            "description": "Agent demand data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "city": { "type": "string" },
                        "state": { "type": "string", "nullable": true },
                        "period_days": { "type": "integer" },
                        "total_agent_queries": { "type": "integer" },
                        "search_queries": { "type": "integer" },
                        "conversions": { "type": "integer" },
                        "conversion_rate_pct": { "type": "number" },
                        "platform_breakdown": {
                          "type": "object",
                          "additionalProperties": { "type": "integer" }
                        },
                        "peak_day": { "type": "string" },
                        "peak_day_queries": { "type": "integer" },
                        "peak_times": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "hour": { "type": "integer" },
                              "label": { "type": "string" },
                              "query_count": { "type": "integer" }
                            }
                          }
                        },
                        "top_search_dates": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "date": { "type": "string", "format": "date" },
                              "query_count": { "type": "integer" }
                            }
                          }
                        },
                        "top_search_locations": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "location": { "type": "string" },
                              "query_count": { "type": "integer" },
                              "lat": { "type": "number" },
                              "lng": { "type": "number" }
                            }
                          }
                        },
                        "coverage_level": { "type": "string", "enum": ["none", "minimal", "partial", "full"] },
                        "lot_count": { "type": "integer" }
                      }
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ValidationError" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key with `intelligence` scope. Pass as `Authorization: Bearer pk_live_...`"
      }
    },
    "schemas": {
      "Meta": {
        "type": "object",
        "properties": {
          "endpoint": { "type": "string" },
          "cost_cents": { "type": "integer" },
          "timestamp": { "type": "string", "format": "date-time" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" }
            }
          }
        }
      }
    },
    "responses": {
      "ValidationError": {
        "description": "Invalid request parameters",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid API key, or missing intelligence scope",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded (100 queries/minute per key)",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      }
    }
  }
}