The Flight Search API lets you build flight-search pages, display search results, and create complex itineraries.

Please note that a default rate limit applies: 100 requests per hour from a single user IP address. If you need to handle more requests, contact support@travelpayouts.com. 

How to get access to Flight Search API

Overall API search logic and flow

1. Build a request specifying origin/destination and the number and type of passengers.
2. Send the request and receive a unique search ID (search_id).
3. Using the search_id, send a results request to retrieve flight details and prices.
4. Use the data to render a search results page and ticket cards.
5. When the user clicks Buy on the ticket screen, generate a link to purchase on the agency/airline website.

Authentication and Headers

Each request must include the following header:

• x-real-host — the address of your website or the ID of the mobile app where the API is used.
• x-user-ip — the user’s IP address.
• x-signature — a signature composed of the token, marker, and all request parameter values, sorted alphabetically and separated by a colon. Learn how to create the signature here.
• x-affiliate-user-id — your API token. 
• Content-Type — application/json by default.

Start search

Link to the request’s OpenAPI.

Body request parameters

• signature — a signature composed of the token, marker, and all request parameter values, sorted alphabetically and separated by a colon. For search start you need to specify signature both in the header and body of the request. Learn how to create the signature here.
• marker (string) — your Travelpayouts partner ID.
• locale (string) — the language of the search result (e.g., en-us, en-gb, de, es, fr, pl, etc.).
• currency_code (string) (optional parameter) — the currency in which the price of the ticket is returned in the response, also in this currency, customers will see the price on the agency’s website (provided that the agency supports this currency).
• market_code — the market of the data source in 2-letter format defined in ISO 3166-1. It depends on various factors, most often it is the language of the Aviasales website where users search for tickets. 
  Each search is associated with a specific market. By default, the market is determined by the place of departure (the origin parameter in the API request). If it was not possible to determine the market, then the data for the RU market would be returned).

• search_params (object)
  • trip_class (string) — flight class (Y — Economy, C — Business, F — First, W — Comfort; Uppercase required).
  • passengers — passenger information:
    • passengers.adults (integer) — number of adults (1–9)
    • passengers.children (integer) — number of children (0–6)
    • passengers.infants (integer) — number of infants under 2 years (0–6)
  • directions — array with a length ranging from 1 to 6
    • origin (string) — IATA code of the departure city (uppercase, e.g., PAR).
    • destination (string) — IATA code of the arrival city (uppercase).
    • date (string) — departure date in YYYY-MM-DD format (e.g., 2022-09-08)

Additional rules:

• directions.origin and directions.destination values cannot be equal

• The date (directions.date) of the first entry in the directions array cannot be earlier than today

• The latest date (directions.date) of the last entry in the directions array must be one calendar year from the current moment (e.g., if the search date is 2023-08-21, the  acceptable date range is [2023-08-21, 2024-08-20])

• The number of passengers.adults must be greater than the number of passengers.infants.

To start searching, add a JSON to the body of the request and send it to the *start* endpoint (you can find the Open API scheme for the endpoint here).

Response parameters

The response contains two key parameters used to retrieve the search results:

• search_id — the search request ID (then passed to the Get Search Results request).
• results_url — the URL to retrieve the search results (then used in the Get Search Results request).

Get Search Results

Method: POST

URL: To create a URL for a query to retrieve search results, use the domain from the results_url field returned by the previous step and add search/affiliate/results in the end.

The final URL should look like this:  <results_url>/search/affiliate/results

To get all data, repeat the request until you get a field is_over = true. The frequency of sending requests is not limited. 

Request parameters

Body

• search_id — the search request ID generated by the Start Search response.
• last_update_timestamp — the timestamp of the last results update (returned in the response and stored for subsequent requests to fetch only updates). For the first request, set last_update_timestamp = 0; for subsequent requests, send the value from the previous response.

Response parameters

Link to the response’s OpenAPI.

The response is returned in JSON and contains the following blocks:

• agents — information about agencies.
  • id — agency ID.
  • gate_name — gateway name.
  • label — localized name.
  • payment_methods — available payment methods.
  • airline_iatas — list of airline IATA codes.
• airlines — information about airlines.
  • iata — airline IATA code.
  • name — airline name.
  • is_lowcost — whether it’s a low-cost airline.
• boundaries — filter ranges (use these to build UI filters):
  • baggage — baggage availability (full, cabin only, no baggage).
  • agents, airlines, airports, alliances — filters by agencies, airlines, etc.
  • transfers_count — number of transfers.
  • transfers_duration — transfer duration.
  • transfers_airports — transfer airports.
  • transfers_countries — transfer countries.
  • departure_arrival_time — departure/arrival time ranges and total trip duration.
  • equipments — aircraft types.
  • has_convenient_transfers — convenient transfers.
  • has_covid_restrictions — COVID restrictions.
  • has_interlines — interline (different carriers).
  • has_long_layover_transfers — long layovers.
  • has_lowcosts — low-cost tickets.
  • has_night_transfers — night transfers.
  • has_short_layover_transfers — short layovers.
  • has_transfers_with_airport_change — airport change on transfer.
  • has_transfers_with_baggage_recheck — baggage recheck on transfer.
  • has_transfers_with_virtual_interline — virtual interline transfers.
  • has_transfers_with_visa — visa-required transfers.
  • payment_methods — payment methods.
  • change_ticket — ticket change terms.
  • return_ticket — ticket refund terms.
  • same_departure_arrival_airport — same airport for departure/arrival.
• flight_legs — array of flight legs; each describes a single flight:
  • origin — departure airport (IATA).
  • destination — arrival airport (IATA).
  • departure_unix_timestamp, arrival_unix_timestamp — Unix times.
  • local_departure_date_time, local_arrival_date_time — local times.
  • operating_carrier_designator — carrier code and flight number.
  • equipment — aircraft code and name, equipment type.
  • signature — leg signature.
  • technical_stops — list of technical stops.
• tickets — array of tickets.
  • id — ticket ID (signature).
  • segments — segment information (flights, transfers).
    • flights — indexes of legs from flight_legs.
    • transfers — transfer information:
      • night_transfer — night transfer.
      • recheck_baggage — baggage recheck.
      • airport_change — airport change.
      • short_layover — short layover.
      • visa_rules — visa requirements.
      • tags — additional tags.
  • proposals — array of agency offers for the route:
    • id — proposal ID,
    • agent_id — the offering agency,
    • price — price (currency and amount),
    • price_per_person — per-passenger price,
    • flight_terms — fare terms
      • trip_class — class type
        • Y — Economy
        • C — Business
        • F — First
        • W — Comfort
      • seats_available — remaining seats at this price (shown only if 1 ≤ seats_available ≤ 9)
      • airline_id — airline IATA code + airline name
      • carrier — airline IATA code
      • number — flight number
      • baggage — baggage info
        • count — number of bags
        • height — max bag height
        • length — max bag length
        • total_weight — total baggage weight
        • weight — max weight per bag
        • width — max bag width
      • handbags — cabin baggage info
        • count — number of cabin items
        • height — max height
        • length — max length
        • total_weight — total cabin-baggage weight
        • weight — max weight per item
        • width — max width
      • additional_tariff_info — additional fare info
        • return_before_flight — possibility of refund after the flight
        • return_after_flight — possibility of refund before the flight
        • change_before_flight — possibility of changes after the flight
        • change_after_flight — possibility of changes before the flight
        • is_charter — charter flight flag
        • merged_terms_info — merged fare info
        • seat_at_registration — seat selection at check-in
        • seat_at_purchase — seat selection at purchase
        • return_before_flight — possibility of refund after the flight
        • return_after_flight — possibility of refund before the flight
        • change_before_flight — possibility of changes after the flight
        • change_after_flight — possibility of changes before the flight
        • value — price
      • minimum_fare — minimum fare conditions and surcharges
        • baggage — from what amount/size baggage is payable
          • count, height, weight, width
        • handbags — from what amount/size cabin baggage is payable
          • count, height, weight, width
        • return_before_flight — possibility of refund after the flight
        • return_after_flight — possibility of refund before the flight
        • change_before_flight — possibility of changes after the flight
        • change_after_flight — possibility of changes before the flight
    • transfer_terms — transfer conditions.
  • signature — unique ticket signature.
• search_params — original search parameters
  • passengers — passenger counts (adults, children, infants)
  • trip_class — travel class
  • source_kind — search source
• last_update_timestamp — timestamp of the last data update.
• is_over — whether the search is finished (true/false).

Status codes

• 200 — success with new data.
• 304 — no new results.
• 400 — invalid parameters.
• 404 — request to the wrong domain.
• 429 — rate limit exceeded.
• 5xx — server error.

Building a сomplex itinerary

The route type is set via the directions parameter. This is an array of trip segments; the number of segments defines the route type:

• One way — 1 segment
• Round trip — 2 segments (outbound and return)
• Multi-city — 3+ segments in the required order

Each segment describes a flight “from point A to point B on date D”.

Segment format

{
  "origin": "IATA code or city",
  "destination": "IATA code or city",
  "date": "YYYY-MM-DD"
}

Examples

One way

"directions": [
  { "origin": "LED", "destination": "HKT", "date": "2026-02-10" }
]

Round trip

"directions": [
  { "origin": "LED", "destination": "HKT", "date": "2026-02-10" },
  { "origin": "HKT", "destination": "LED", "date": "2026-02-20" }
]

Multi-city (Open jaw request)

An open jaw is a round-trip ticket in which the traveler does not arrive in the same city of departure and/or does not depart from the same city where he/she first landed. For example, London — Paris — Berlin — London.

"directions": [
  { "origin": "LED", "destination": "DXB", "date": "2026-02-10" },
  { "origin": "DXB", "destination": "SIN", "date": "2026-02-14" },
  { "origin": "SIN", "destination": "LED", "date": "2026-02-21" }
]

Low-cost carriers in search results

Some airlines and agencies in the results do not support working with the partner marker. Sales via such companies will not generate partner rewards.

You may choose to keep these tickets in the results or filter them before displaying to users. Keep in mind: these are low-cost companies—usually offering the lowest prices. If you remove them, the search results may be less attractive to users.

List of companies that do not support the partner ID can be found here.

Airline and agency logos

Airline logos are available at: http://img.wway.io/pics/root/iata@png?exar=1&rs=fit:width:height

where

• width — the logo width
• height — the logo height
• iata — IATA code of the airline

Example: http://img.wway.io/pics/root/UN@png?exar=1&rs=fit:200:200 

Agency logos are available at: http://img.wway.io/pics/as_gates/id@png?exar=1&rs=fit:width:height

where

• width — the logo width
• height — the logo height
• id — he agency ID from the flight search API response (see the terms field)

Example: http://img.wway.io/pics/as_gates/70@png?exar=1&rs=fit:110:70 

To get a Retina version of the logo, multiple the width and height by two, for example: http://img.wway.io/pics/as_gates/70@png?exar=1&rs=fit:220:140 

How to get a link to the agency website

To get a booking link:

1. Send a request to:
   https://[results_url]/searches/[search_id]/clicks/[proposal_id] where
   • results_url — results URL from the Start Search response
   • search_id — search ID from the Start Search response
   • proposal_id — proposal ID from tickets[].proposals[].id in search results
2. Include your marker in the request header.

Sample response

{
  "gate_id": 70,
  "agent_id": 70,
  "click_id": 2603625159552466848,
  "str_click_id": "2603625159552466848",
  "url": "https://www.kupibilet.ru/booking/step0/Y20020DECLEDIST/a66dbb4a9c944b8883b1046674a7162710?agent=ghe056&country=RU&from_iss=true&marker=js4c3a3o0uqo&tag=aaa0000",
  "method": "GET",
  "params": {
    "gate_id": 70,
    "agent_id": 70,
    "click_id": 2603625159552466848
  },
  "expire_at_unix_sec": 1689958526
}

Response parameters

• gate_id — gate ID
• agent_id — agency ID
• click_id — click identifier
• str_click_id — click identifier (string)
• url — redirect URL
• method — HTTP method to use for the redirect
• params — ticket parameters
• expire_at_unix_sec — link “time to live” in Unix time

The booking link has a limited lifetime. After it expires, you must re-request the search results and generate a new url.

Possible errors

• Code 400 (Invalid arguments)
• Code 403 (Access denied)
• Code 404 (Search or proposal not found)
• Code 429 (Too many requests)
• Code 5XX (Unexpected error)