Skip to main content
POST
Flight search

Authorizations

x-api-key
string
header
required

Body

application/json

Flight search request: a one-way or round-trip itinerary search.

origins
string[]
required

Departure airports; any of them may be used.

Required array length: 1 - 7 elements

IATA airport or metro code, e.g. SFO or NYC.

Pattern: ^[A-Z]{3}$
destinations
string[]
required

Arrival airports; any of them may be used.

Required array length: 1 - 7 elements

IATA airport or metro code, e.g. SFO or NYC.

Pattern: ^[A-Z]{3}$
departure_date
string<date>
required

Outbound date, YYYY-MM-DD.

return_date
string<date> | null

Return date, YYYY-MM-DD. Makes the search a round trip, with both legs on one airline.

adults
integer
default:1
Required range: 1 <= x <= 9
children
integer
default:0
Required range: 0 <= x <= 8
infants_in_seat
integer
default:0
Required range: 0 <= x <= 8
infants_on_lap
integer
default:0
Required range: 0 <= x <= 8
cabin
enum<string>
default:economy
Available options:
economy,
premium_economy,
business,
first
max_stops
integer | null

0 for nonstop only; at most 2.

Required range: 0 <= x <= 2
max_price
integer | null

Highest total price for all travelers, in currency; for a round trip, the round-trip total.

Required range: x > 0
currency
string
default:USD

ISO 4217 currency of max_price and of result prices.

Pattern: ^[A-Z]{3}$
Examples:

"USD"

"EUR"

"JPY"

max_duration_minutes
integer | null

Longest total travel time per direction.

Required range: x > 0
include_airlines
string[]

Only these airlines.

Maximum array length: 10

IATA airline code, e.g. UA.

Pattern: ^[A-Z0-9]{2}$
exclude_airlines
string[]

Never these airlines. Not combinable with include_airlines.

Maximum array length: 10

IATA airline code, e.g. UA.

Pattern: ^[A-Z0-9]{2}$
departure_hours
HourWindow · object | null

Allowed local departure hours for the outbound flight.

arrival_hours
HourWindow · object | null

Allowed local arrival hours for the outbound flight, on any date: an overnight flight is checked by its arrival hour.

return_hours
HourWindow · object | null

Allowed local departure hours for the return flight. Needs return_date.

return_arrival_hours
HourWindow · object | null

Allowed local arrival hours for the return flight, on any date. Needs return_date.

sort
enum<string>
default:best

best (default) balances price, duration and stops. For a round trip it also picks the return on the outbound's airline: price the cheapest, duration the shortest, the others the fewest stops within 10% of the cheapest. For the cheapest trip on any airlines, as separate tickets, search each direction one way.

Available options:
best,
price,
duration,
departure_time,
arrival_time
advanced_settings
AdvancedFlightSearchSettings · object | null

Result count.

mode
enum<string> | null

advanced (default): live fares.

Available options:
advanced
session_id
string | null

Session identifier that groups related calls made as part of a larger task. Echoed back in the response when nonempty; generated by the server if omitted, null, or empty.

Maximum string length: 1000
client_model
string | null

The model generating this request and consuming the results.

Response

Successful Response

Flight search response.

search_id
string
required

Search ID. Example: search_cad0a6d2dec046bd95ae900527d880e7

session_id
string
required

Session identifier, echoed back from the request when nonempty; otherwise generated by the server.

results
FlightSearchResult · object[]
required

Itineraries, best first by the requested sort.

warnings
Warning · object[] | null

Warnings for the search request, if any.

usage
UsageItem · object[] | null

Usage metrics for the search request.