{
  "openapi": "3.1.0",
  "info": {
    "title": "Transfers DV Public Transportation API",
    "version": "1.0.0",
    "description": "Read-only discovery and quotation for pre-booked ground transportation from Cancun International Airport (CUN). These GET operations never create a reservation, collect personal data or process payment. A returned quote is current when checked but does not lock fare or availability."
  },
  "servers": [{ "url": "https://www.transfersdv.com" }],
  "paths": {
    "/public/destinations": {
      "get": {
        "operationId": "listDestinations",
        "summary": "List Cancun and Riviera Maya service areas",
        "description": "Returns bilingual zone names, destination guides, hotel directories and quote links, including the mainland scope of ferry connections.",
        "responses": {
          "200": { "description": "Public destinations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestinationCatalog" } } } },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/public/quote": {
      "get": {
        "operationId": "getTransportationQuote",
        "summary": "Get current transportation options and totals",
        "description": "Validates the route, dates and total party size, then returns current vehicle options in the language's currency. Adults, children and infants all count toward capacity. The first family is Premium Airport Taxi. booking_url continues the selected family on the human checkout without selecting a fare or creating a reservation.",
        "parameters": [
          { "name": "trip", "in": "query", "required": true, "schema": { "type": "string", "enum": ["arrival", "departure", "round-trip"] } },
          { "name": "airport", "in": "query", "required": true, "schema": { "type": "string", "const": "CUN" } },
          { "name": "to", "in": "query", "required": true, "description": "Use a destination token returned by /public/destinations or the hotel directory.", "schema": { "type": "string", "maxLength": 207 } },
          { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } },
          { "name": "return_date", "in": "query", "required": false, "description": "Required and later than date for round-trip.", "schema": { "type": "string", "format": "date" } },
          { "name": "adults", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 2 } },
          { "name": "children", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 50, "default": 0 } },
          { "name": "infants", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 50, "default": 0 } },
          { "name": "locale", "in": "query", "required": true, "schema": { "type": "string", "enum": ["en", "es"] } },
          { "name": "currency", "in": "query", "required": false, "description": "Normalized by locale: English uses USD and Spanish uses MXN.", "schema": { "type": "string", "enum": ["USD", "MXN"] } },
          { "name": "preferred_vehicle_id", "in": "query", "required": false, "schema": { "type": "string", "enum": ["private", "taxi", "luxury", "group"] } },
          { "name": "landing_path", "in": "query", "required": false, "description": "First-party page where the quote began.", "schema": { "type": "string", "pattern": "^/(?!/)" } }
        ],
        "responses": {
          "200": { "description": "A ready quote or actionable validation errors. reservation_created and final_price_confirmed are always false.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" } } } },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    }
  },
  "components": {
    "responses": {
      "RateLimited": { "description": "Public request limit reached", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Unavailable": { "description": "Current catalog temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": { "error": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after": { "type": "integer" } },
        "required": ["error"]
      },
      "DestinationCatalog": {
        "type": "object",
        "properties": {
          "destinations": { "type": "array", "items": { "type": "object" } },
          "zones": { "type": "array", "items": { "$ref": "#/components/schemas/Zone" } },
          "ferry_connections": { "type": "array", "items": { "type": "object" } },
          "captured_at": { "type": "string" }
        },
        "required": ["destinations", "zones", "ferry_connections", "captured_at"]
      },
      "Zone": {
        "type": "object",
        "properties": {
          "id": { "type": "string" }, "zone_id": { "type": "integer" }, "airport": { "const": "CUN" },
          "names": { "type": "object", "additionalProperties": { "type": "string" } },
          "guide_urls": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } },
          "quote_urls": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } },
          "hotel_directory_urls": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } }
        },
        "required": ["id", "zone_id", "airport", "names", "guide_urls", "quote_urls", "hotel_directory_urls"]
      },
      "QuoteResponse": {
        "type": "object",
        "properties": {
          "inputs": { "type": "object" },
          "errors": { "type": "object", "additionalProperties": { "type": "string" } },
          "quote_ready": { "type": "boolean" },
          "party_size": { "type": "integer" },
          "destination": { "type": ["object", "null"] },
          "offers": { "type": "array", "items": { "$ref": "#/components/schemas/QuoteOffer" } },
          "checked_at": { "type": "string" },
          "notice": { "type": "string" },
          "reservation_created": { "type": "boolean", "const": false },
          "final_price_confirmed": { "type": "boolean", "const": false }
        },
        "required": ["inputs", "errors", "quote_ready", "party_size", "destination", "offers", "reservation_created", "final_price_confirmed"]
      },
      "QuoteOffer": {
        "type": "object",
        "properties": {
          "option_key": { "type": "string" },
          "family": { "type": "string", "enum": ["taxi", "private", "luxury", "group"] },
          "name": { "type": "string", "examples": ["Premium Airport Taxi"] },
          "tier": { "type": "string", "enum": ["standard", "premium"] },
          "eligible": { "type": "boolean", "description": "Whether the combined adults + children + infants fit this option." },
          "total": { "$ref": "#/components/schemas/Money" },
          "capacity": { "type": "object", "properties": { "passengers": { "type": "integer" }, "bags": { "type": "integer" } }, "required": ["passengers", "bags"] },
          "benefits": { "type": "array", "items": { "type": "string" } },
          "booking_url": { "type": "string", "format": "uri" }
        },
        "required": ["option_key", "family", "name", "tier", "eligible", "total", "capacity", "benefits", "booking_url"]
      },
      "Money": {
        "type": "object",
        "properties": {
          "amount": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{2}$" },
          "currency": { "type": "string", "enum": ["USD", "MXN"] },
          "basis": { "const": "per_vehicle" }
        },
        "required": ["amount", "currency", "basis"]
      }
    }
  }
}