Response Format

All fare search responses follow the same structure. This page walks through each part so you know exactly what to expect.

Top-level fields

Every fare response includes the route and date you searched, plus an array of matching itineraries:

Parameter	Type	Required	Description
origin	string	Yes	The resolved 3-letter IATA departure code.
destination	string	Yes	The resolved 3-letter IATA arrival code.
departure_date	string	Yes	Departure date in YYYY-MM-DD format.
return_date	string	No	Return date for round-trip responses.
itineraries	array	Yes	List of matching itineraries (may be empty).

Itinerary object

Each itinerary represents a complete travel option. Here's a connecting one-way flight with two segments:

Single itinerary

{
  "price": {
    "amount": 542,
    "currency": "USD"
  },
  "outbound": {
    "carrier": "United Airlines",
    "duration_minutes": 475,
    "segments": [
      {
        "marketing_carrier_code": "UA",
        "flight_number": "1234",
        "operating_carrier_name": "United Airlines",
        "departure_airport": "SFO",
        "departure_time_local": "2026-07-02T06:00:00",
        "departure_timezone": "America/Los_Angeles",
        "departure_time_utc": "2026-07-02T13:00:00Z",
        "arrival_airport": "ORD",
        "arrival_time_local": "2026-07-02T12:15:00",
        "arrival_timezone": "America/Chicago",
        "arrival_time_utc": "2026-07-02T17:15:00Z",
        "duration_minutes": 255,
        "aircraft": "Boeing 737 MAX 9"
      },
      {
        "marketing_carrier_code": "UA",
        "flight_number": "5678",
        "operating_carrier_name": "United Airlines",
        "departure_airport": "ORD",
        "departure_time_local": "2026-07-02T13:30:00",
        "departure_timezone": "America/Chicago",
        "departure_time_utc": "2026-07-02T18:30:00Z",
        "arrival_airport": "JFK",
        "arrival_time_local": "2026-07-02T16:55:00",
        "arrival_timezone": "America/New_York",
        "arrival_time_utc": "2026-07-02T20:55:00Z",
        "duration_minutes": 145,
        "aircraft": "Airbus A320"
      }
    ]
  },
  "cabin_class": "economy",
  "ignav_id": "a1b2c3d4e5f6789012345678abcdef01"
}

Price

The price object always has an amount (number) and currency (3-letter ISO code). The currency is usually determined by the market you pass in the request. If a search price needs booking-link verification, the numeric amount and currency reflect the verified display price.

Legs

Every itinerary includes an outbound leg. Round-trip itineraries may also include an inbound leg.

Each leg contains airline display carrier, elapsed duration_minutes, and segments. Carrier names are display strings and may be localized. If you need a stable airline code, use each segment's marketing_carrier_code.

Optional itinerary fields are omitted when unavailable.

Parameter	Type	Required	Description
carrier	string	No	Airline display name for this leg when available.
duration_minutes	integer	No	Elapsed leg travel time in minutes, including layovers when present.
segments	array	Yes	Array of flight segments for this leg (see below).

Segments

Each leg's segments array contains one entry per flight segment. A nonstop itinerary leg has one segment; a connection has two or more. Each segment includes:

Parameter	Type	Required	Description
marketing_carrier_code	string \| null	Yes	2-letter code of the airline selling the ticket.
flight_number	string \| null	Yes	Flight number (e.g. "1234").
operating_carrier_name	string \| null	Yes	Name of the airline operating the aircraft.
departure_airport	string	Yes	3-letter IATA code.
departure_time_local	string	Yes	Local departure time in YYYY-MM-DDTHH:MM:SS format.
departure_timezone	string \| null	Yes	IANA timezone name for the departure airport.
departure_time_utc	string \| null	Yes	Departure timestamp converted to UTC.
arrival_airport	string	Yes	3-letter IATA code.
arrival_time_local	string	Yes	Local arrival time in YYYY-MM-DDTHH:MM:SS format.
arrival_timezone	string \| null	Yes	IANA timezone name for the arrival airport.
arrival_time_utc	string \| null	Yes	Arrival timestamp converted to UTC.
duration_minutes	integer	Yes	Flight duration in minutes.
aircraft	string \| null	Yes	Aircraft type, e.g. "Boeing 737 MAX 9".

departure_time_local and arrival_time_local remain airport-local wall times. Each segment also includes the corresponding IANA timezone and a UTC timestamp so browser clients do not have to infer the conversion.

Do not derive elapsed travel time by subtracting the local wall-clock fields. Use segment duration_minutes, leg duration_minutes, or the UTC timestamps instead.

Baggage

When available, the bags object shows how many carry_on and checked bags are included in the fare. Either field may be omitted when the information is unavailable.

ignav_id

Every itinerary includes an ignav_id — a unique string that identifies this exact itinerary. Pass it to the booking links endpoint to get direct booking URLs.

Round-trip additions

Round-trip itineraries include an optional inbound leg object with the same fields as outbound.

Booking links response

The booking links endpoint returns the matched itinerary plus grouped booking options:

Booking links response

{
  "itinerary": {
    "price": {
      "amount": 488,
      "currency": "USD"
    },
    "outbound": {
      "carrier": "American Airlines",
      "duration_minutes": 330,
      "segments": [
        {
          "marketing_carrier_code": "AA",
          "flight_number": "100",
          "operating_carrier_name": "American Airlines",
          "departure_airport": "SFO",
          "departure_time_local": "2026-07-02T08:00:00",
          "departure_timezone": "America/Los_Angeles",
          "departure_time_utc": "2026-07-02T15:00:00Z",
          "arrival_airport": "JFK",
          "arrival_time_local": "2026-07-02T16:30:00",
          "arrival_timezone": "America/New_York",
          "arrival_time_utc": "2026-07-02T20:30:00Z",
          "duration_minutes": 330,
          "aircraft": "Boeing 777"
        }
      ]
    },
    "cabin_class": "economy"
  },
  "booking_options": [
    {
      "legs": [
        "outbound"
      ],
      "links": [
        {
          "provider_name": "American Airlines",
          "provider_type": "airline",
          "fare_name": "Main Cabin",
          "price": {
            "amount": 488,
            "currency": "USD"
          },
          "url": "aa.com/booking/..."
        },
        {
          "provider_name": "Expedia",
          "provider_type": "third_party",
          "price": {
            "amount": 502,
            "currency": "USD"
          },
          "url": "expedia.com/flights/..."
        }
      ]
    }
  ]
}

Each booking option has a legs array plus a links array. Each link includes provider_name, provider_type, optional fare_name and price, and a url that takes the user directly to a booking page with the flight pre-selected.

Related docs

Ready to get started?

Create a free account to get your API key, or try the playground — no signup required.

Get API key Try the Playground