{
  "openapi": "3.1.0",
  "info": {
    "title": "Orb Vector Geodetic Flight & Aviation Telemetry API",
    "description": "Public zero-auth aviation intelligence API & Remote MCP Server returning WGS84 Great Circle distances, Rhumb Line navigation headings, airspace overflight countries, solar terminator window-seat recommendations, fuel/CO2 emissions, reciprocal return timing, and global airport hub profiles across 7,906 IATA airports.",
    "version": "1.2.0",
    "contact": {
      "name": "Orb Vector",
      "url": "https://orbvector.com"
    }
  },
  "servers": [
    {
      "url": "https://orbvector.com",
      "description": "Production Cloudflare Global Edge Network"
    }
  ],
  "paths": {
    "/route/{origin}-{dest}/data.json": {
      "get": {
        "operationId": "getRouteTelemetry",
        "summary": "Get comprehensive flight route geodetic, overflight, window-seat, emissions, and corridor telemetry",
        "description": "Computes Great Circle vs. Rhumb Line geometry, airspace overflight countries & water bodies, solar window seat analysis across 4 departure presets (or live/selected preset), fuel/CO2 emissions, reciprocal return flight delta, nearby alternative hubs, and canonical 3D globe citation links.",
        "parameters": [
          {
            "name": "origin",
            "in": "path",
            "required": true,
            "description": "3-letter IATA origin airport code (e.g., SIN, JFK)",
            "schema": { "type": "string", "pattern": "^[A-Za-z]{3}$" }
          },
          {
            "name": "dest",
            "in": "path",
            "required": true,
            "description": "3-letter IATA destination airport code (e.g., JFK, LHR)",
            "schema": { "type": "string", "pattern": "^[A-Za-z]{3}$" }
          },
          {
            "name": "departure",
            "in": "query",
            "required": false,
            "description": "Optional departure window for active solar terminator window-seat calculation",
            "schema": {
              "type": "string",
              "enum": ["live", "morning", "afternoon", "evening", "night"]
            }
          },
          {
            "name": "aircraft",
            "in": "query",
            "required": false,
            "description": "Optional aircraft profile ID or short name (e.g., boeing-747-8, boeing-777-200lr, airbus-a320neo, concorde)",
            "schema": { "type": "string" }
          },
          {
            "name": "cabin",
            "in": "query",
            "required": false,
            "description": "Optional cabin class for per-passenger CO2 scaling",
            "schema": {
              "type": "string",
              "enum": ["economy", "premium", "business", "first"],
              "default": "economy"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Enriched v1.2 route telemetry JSON payload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RouteTelemetryV12"
                }
              }
            }
          },
          "404": {
            "description": "One or both IATA codes are unknown or identical"
          },
          "429": {
            "description": "Uncached compute burst limit exceeded (includes Retry-After header)"
          }
        }
      }
    },
    "/airport/{iata}/data.json": {
      "get": {
        "operationId": "getAirportProfile",
        "summary": "Get global airport hub coordinates, operational briefing, antipode, and connected routes",
        "parameters": [
          {
            "name": "iata",
            "in": "path",
            "required": true,
            "description": "3-letter IATA airport code (e.g., LHR, SIN, DXB)",
            "schema": { "type": "string", "pattern": "^[A-Za-z]{3}$" }
          }
        ],
        "responses": {
          "200": {
            "description": "Airport hub JSON telemetry payload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AirportTelemetry"
                }
              }
            }
          },
          "404": {
            "description": "Airport IATA code not found"
          }
        }
      }
    },
    "/mcp": {
      "get": {
        "operationId": "getMcpCapabilities",
        "summary": "Retrieve Remote MCP server capability card",
        "responses": {
          "200": {
            "description": "Remote MCP server metadata & tool summary"
          }
        }
      },
      "post": {
        "operationId": "mcpRpc",
        "summary": "Execute stateless MCP JSON-RPC 2.0 methods (initialize, tools/list, tools/call)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/McpJsonRpcRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC 2.0 response payload"
          },
          "202": {
            "description": "Accepted JSON-RPC notification"
          }
        }
      }
    },
    "/status.json": {
      "get": {
        "operationId": "getStatus",
        "summary": "Health and readiness status of the Orb Vector API",
        "responses": {
          "200": {
            "description": "Service is operational"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "RouteTelemetryV12": {
        "type": "object",
        "required": ["schemaVersion", "route", "origin", "destination", "geodesic", "loxodrome", "urls"],
        "properties": {
          "schemaVersion": { "type": "string", "example": "1.2" },
          "route": { "type": "string", "example": "SIN-JFK" },
          "origin": { "$ref": "#/components/schemas/AirportSummary" },
          "destination": { "$ref": "#/components/schemas/AirportSummary" },
          "geodesic": {
            "type": "object",
            "properties": {
              "distanceKm": { "type": "number" },
              "distanceNauticalMiles": { "type": "number" },
              "distanceStatuteMiles": { "type": "number" },
              "initialBearingDegrees": { "type": "number" },
              "initialCompassDirection": { "type": "string" },
              "estimatedFlightDuration": { "type": "string" },
              "aircraftId": { "type": "string" },
              "aircraftName": { "type": "string" },
              "cruiseSpeedKph": { "type": "number" }
            }
          },
          "loxodrome": {
            "type": "object",
            "properties": {
              "rhumbDistanceKm": { "type": "number" },
              "divergenceKm": { "type": "number" },
              "divergencePercent": { "type": "number" }
            }
          },
          "overflight": {
            "type": "object",
            "properties": {
              "corridorClassification": { "type": "string" },
              "peakLatitudeDeg": { "type": "number" },
              "peakLatitudeDisplay": { "type": "string" },
              "countries": { "type": "array", "items": { "type": "object" } },
              "waterBodies": { "type": "array", "items": { "type": "object" } },
              "landmarks": { "type": "array", "items": { "type": "object" } },
              "summary": { "type": "string" }
            }
          },
          "windowSeat": { "type": "object" },
          "emissions": { "type": "object" },
          "reverseRoute": { "type": "object" },
          "nearbyCorridors": { "type": "array", "items": { "type": "object" } },
          "attribution": {
            "type": "object",
            "properties": {
              "creditName": { "type": "string", "example": "Orb Vector" },
              "canonicalUrl": { "type": "string", "example": "https://orbvector.com/route/SIN-JFK" },
              "markdownLink": { "type": "string" },
              "citationInstruction": { "type": "string" }
            }
          },
          "urls": {
            "type": "object",
            "properties": {
              "canonical": { "type": "string" },
              "page": { "type": "string" },
              "data": { "type": "string" },
              "reversePage": { "type": "string" },
              "reverseData": { "type": "string" }
            }
          }
        }
      },
      "AirportSummary": {
        "type": "object",
        "properties": {
          "iata": { "type": "string" },
          "icao": { "type": "string" },
          "name": { "type": "string" },
          "city": { "type": "string" },
          "country": { "type": "string" },
          "lat": { "type": "number" },
          "lon": { "type": "number" }
        }
      },
      "AirportTelemetry": {
        "type": "object",
        "properties": {
          "schemaVersion": { "type": "string", "example": "1.1" },
          "airport": { "$ref": "#/components/schemas/AirportSummary" },
          "curatedProfile": { "type": ["object", "null"] },
          "connectedRoutesCount": { "type": "integer" },
          "connectedRoutes": { "type": "array", "items": { "type": "object" } },
          "urls": { "type": "object" }
        }
      },
      "McpJsonRpcRequest": {
        "type": "object",
        "required": ["jsonrpc", "method"],
        "properties": {
          "jsonrpc": { "type": "string", "enum": ["2.0"] },
          "id": { "type": ["string", "integer", "null"] },
          "method": {
            "type": "string",
            "enum": ["initialize", "notifications/initialized", "ping", "tools/list", "tools/call"]
          },
          "params": { "type": "object" }
        }
      }
    }
  }
}