{
  "openapi": "3.1.0",
  "info": {
    "title": "UmrahTransit Public Quote API",
    "description": "Read-only fixed pricing for private transfers, hourly chauffeur service, and full-day driver hire across Saudi Arabia. Operated by Fakhama Groups LLC (trading as UmrahTransit), a TGA-licensed private ground transportation provider. All prices are in Saudi Riyals (SAR), fixed per vehicle (not per person). No authentication required. Rate limit: 60 requests per minute per IP.",
    "version": "1.0.0",
    "contact": {
      "name": "UmrahTransit",
      "url": "https://umrahtransit.com/ai",
      "email": "bookings@umrahtransit.com"
    }
  },
  "servers": [{ "url": "https://umrahtransit.com" }],
  "paths": {
    "/api/quote": {
      "get": {
        "operationId": "getQuote",
        "summary": "Get a fixed price quote",
        "description": "Returns fixed per-vehicle prices. Call without parameters to receive a discovery document listing all route IDs, cities, packages, and vehicle IDs.",
        "parameters": [
          {
            "name": "service",
            "in": "query",
            "description": "Which service to quote. Omit for the discovery document.",
            "schema": { "type": "string", "enum": ["route", "hourly", "day-trip"] }
          },
          {
            "name": "route",
            "in": "query",
            "description": "Route ID (required when service=route), e.g. jeddah-airport-makkah, makkah-madinah, madinah-airport. Full list in the discovery document.",
            "schema": { "type": "string" }
          },
          {
            "name": "date",
            "in": "query",
            "description": "Optional travel date (YYYY-MM-DD) for service=route. Applies seasonal Ramadan/Hajj pricing automatically.",
            "schema": { "type": "string", "format": "date" }
          },
          {
            "name": "city",
            "in": "query",
            "description": "City (required when service=hourly or service=day-trip): makkah, madinah, jeddah, or taif.",
            "schema": { "type": "string", "enum": ["makkah", "madinah", "jeddah", "taif"] }
          },
          {
            "name": "hours",
            "in": "query",
            "description": "Booking hours for service=hourly. Minimums are enforced (4h city, 6h intercity).",
            "schema": { "type": "integer", "minimum": 1 }
          },
          {
            "name": "intercity",
            "in": "query",
            "description": "Set true for intercity hourly rates (6h minimum).",
            "schema": { "type": "boolean" }
          },
          {
            "name": "package",
            "in": "query",
            "description": "Day-trip package (required when service=day-trip): 6h (half day), 12h (full day), or 24h.",
            "schema": { "type": "string", "enum": ["6h", "12h", "24h"] }
          },
          {
            "name": "days",
            "in": "query",
            "description": "Number of days for service=day-trip with package=24h (1-30). Multi-day discounts apply automatically: 10% off 7+ days, 15% off 14+, 20% off 21+.",
            "schema": { "type": "integer", "minimum": 1, "maximum": 30 }
          },
          {
            "name": "vehicle",
            "in": "query",
            "description": "Optional vehicle ID filter, e.g. toyota-camry-2025, hyundai-staria, gmc-yukon-xl. Full list in the discovery document.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Quote or discovery document",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "service": { "type": "string" },
                    "currency": { "type": "string", "example": "SAR" },
                    "quotes": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string", "description": "Vehicle ID" },
                          "name": { "type": "string" },
                          "category": { "type": "string" },
                          "passengers": { "type": "integer" },
                          "luggage": { "type": "integer" },
                          "price": { "type": "number", "description": "Total fixed price in SAR per vehicle" },
                          "bookingUrl": { "type": "string" }
                        }
                      }
                    },
                    "page": { "type": "string", "description": "Human-readable page for this service" },
                    "notes": { "type": "object", "description": "Pricing, payment, cancellation, and booking policies" }
                  }
                }
              }
            }
          },
          "400": { "description": "Invalid parameters (response includes valid options)" },
          "429": { "description": "Rate limit exceeded (60 requests/minute)" }
        }
      }
    }
  }
}