RoundtripRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/flightpowers-com/json-schema/flightpowers-com-roundtrip-request-schema.json",
  "title": "RoundtripRequest",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/flightpowers-com-openapi.json#/components/schemas/RoundtripRequest",
  "type": "object",
  "required": [
    "from_airport",
    "to_airport",
    "departure_date",
    "return_date"
  ],
  "properties": {
    "from_airport": {
      "type": "string",
      "description": "Origin IATA code."
    },
    "to_airport": {
      "type": "string",
      "description": "Destination IATA code."
    },
    "departure_date": {
      "type": "string",
      "format": "date",
      "description": "Outbound date, YYYY-MM-DD."
    },
    "return_date": {
      "type": "string",
      "format": "date",
      "description": "Return date, YYYY-MM-DD."
    },
    "max_departure_stops": {
      "type": "integer",
      "description": "Max stops on the outbound leg."
    },
    "max_return_stops": {
      "type": "integer",
      "description": "Max stops on the return leg."
    },
    "departure_airline_codes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Only these airlines on the outbound leg."
    },
    "return_airline_codes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Only these airlines on the return leg."
    },
    "departure_exclude_airline_codes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Exclude these airlines on the outbound leg."
    },
    "return_exclude_airline_codes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Exclude these airlines on the return leg."
    },
    "departure_departure_time_min": {
      "type": "integer",
      "minimum": 0,
      "maximum": 23,
      "description": "Outbound leg: earliest departure hour."
    },
    "departure_departure_time_max": {
      "type": "integer",
      "minimum": 0,
      "maximum": 23,
      "description": "Outbound leg: latest departure hour."
    },
    "departure_arrival_time_min": {
      "type": "integer",
      "minimum": 0,
      "maximum": 23,
      "description": "Outbound leg: earliest arrival hour."
    },
    "departure_arrival_time_max": {
      "type": "integer",
      "minimum": 0,
      "maximum": 23,
      "description": "Outbound leg: latest arrival hour."
    },
    "return_departure_time_min": {
      "type": "integer",
      "minimum": 0,
      "maximum": 23,
      "description": "Return leg: earliest departure hour."
    },
    "return_departure_time_max": {
      "type": "integer",
      "minimum": 0,
      "maximum": 23,
      "description": "Return leg: latest departure hour."
    },
    "return_arrival_time_min": {
      "type": "integer",
      "minimum": 0,
      "maximum": 23,
      "description": "Return leg: earliest arrival hour."
    },
    "return_arrival_time_max": {
      "type": "integer",
      "minimum": 0,
      "maximum": 23,
      "description": "Return leg: latest arrival hour."
    },
    "sort_type": {
      "type": "string",
      "enum": [
        "Overall",
        "Price",
        "Duration"
      ],
      "default": "Overall",
      "description": "Result ordering."
    },
    "currency": {
      "type": "string",
      "default": "USD",
      "description": "ISO currency code for prices, e.g. `USD`, `EUR`."
    },
    "max_price": {
      "type": "integer",
      "description": "Only return itineraries at or below this price."
    },
    "seat_type": {
      "type": "integer",
      "enum": [
        1,
        2,
        3,
        4
      ],
      "description": "Cabin: 1 = Economy, 2 = Premium economy, 3 = Business, 4 = First."
    },
    "passengers": {
      "type": "array",
      "items": {
        "type": "integer",
        "enum": [
          1,
          2,
          3,
          4
        ]
      },
      "description": "One integer per passenger: 1 = adult, 2 = child, 3 = infant on lap, 4 = infant in seat. Default: one adult."
    },
    "limit": {
      "type": "integer",
      "default": 10,
      "description": "Maximum number of results to return."
    },
    "returns_per_outbound": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5,
      "default": 2,
      "description": "How many return flights to pair with each outbound flight, 1 to 5. Defaults to 2. The paired itineraries are ranked together and `limit` still caps how many come back. `limit` also sets how many outbound flights are searched (one return lookup each), so a higher `limit` is slower. With the default `limit`, 5 means the 10 results are the best of up to 50 pairings instead of 20. Not applied to results that come from the fallback source (`X-Search-Fallback: used` without `X-Search-Notes: upstream_no_render`). Must be a whole number from 1 to 5 (null is rejected)."
    },
    "use_fallback": {
      "type": "boolean",
      "description": "A secondary flight-data source the API can escalate to when the live Google Flights search does not come back with results. Last resort, not part of the normal path: a search that succeeds never touches it. Send `false` to switch the escalation off for a request. Responses that do use it can take longer."
    },
    "strict": {
      "type": "boolean",
      "default": false,
      "description": "Opt-in. Return HTTP 503 with a `search_incomplete` error body instead of an empty array when the search did not complete (X-Search-Status `degraded`)."
    },
    "use_ext_proxy": {
      "type": "boolean",
      "default": true,
      "description": "When true, requests may be routed through an external residential proxy to reduce blocks from Google. Set false to force a direct request (lower latency, more block risk)."
    }
  }
}