Flights search API: Real-time and multi-city search

With the help of API, you can get the results of requests in real time and create a Multi-City search. 

By default, one partner may send no more than 200 queries per hour for one IP, using the airline tickets search API. This restriction may be changed if a situation so requires.

Аccess to the flights search API

To access the flights search API you should be registered in our travel affiliate program and submit your request on support@travelpayouts.com with the following information:

  • URL of your website;
  • Design prototypes of search result;
  • Description of your project;
  • How you will use the search API?
  • Why aren’t the standard methods of integration (search forms, White Label, API access to data) suitable for you.

Requirements for flights search API access

  1. Each search query must be initiated by the user and the results must be shown to the user in full. The results for each query must contain a “buy” button next to each flight option.
  2. The conversion rate for searches via the Buy link must be 9% or more. The conversion rate from the Buy button to actual purchases must be at least 5%.
  3. We'll also need to see the URL of your project, design prototypes, a description of your project, and how our API will be used.
  4. Ajax requests to the API don’t work because the access token is passed unencrypted. You must make requests to the API from the server.

Round trip

Request initialization

Request parameters:

  • marker - the unique identifier of the affiliate. You can find your marker in the affiliate personal account;

  • host - host's request (must be replaced by the address of your website where the API will be used);
  • user_ip - user's IP address;
  • locale - language of the search result (en, ru, de, es, fr, pl);
  • trip_class - flight class (Y – Economy, C – Business);
  • passengers - passenger Information;
    • adults - the number of adult passengers (from 1 to 9);
    • children - the number of children (from 0 to 6);
    • infants - the number of infants (from 0 to 6).
  • segments
    • origin - origin IATA or string "City, Country (IATA)". The IATA code is shown in uppercase letters (for example, "Paris, France (PAR)");
    • destination - destination IATA or string "City, Country (IATA)". The IATA code is shown in uppercase letters (for example, "Berlin, Germany (BER)");
    • date - departure date yyyy-mm-dd (for example, "2015-09-08").
  • currency - the currency in which the price of the ticket is displayed, after switching to the agency's website (provided that the agency supports this currency);
  • signature - the Query Signature is constructed from token, marker, and all the values ​​of the query parameters sorted alphabetically and separated by colon. Learn how to create a signature look here.

To get "Round trip" tickets, add a JSON to the body of the request:

{
"signature": "2c37292b67762a913455b166345ae249",
 "marker": "PutYourMarkerHere",
 "host": %your_server_host%,
   "user_ip": %user_ip%,
 "locale": "en",
   "trip_class": "Y",
 "passengers": {
    "adults": "1",
    "children": "0",
     "infants": "0"
   },
 "segments": [
   {
    "origin": "MOW",
     "destination": "LED",
   "date": "2017-05-25"
   },
   {
    "origin": "LED",
     "destination": "MOW",
     "date": "2017-06-18"
   }
   ]
} 

To get data, use the initialization code of the search:

curl -v -X POST -d '{"signature":"2d0c311eb0fe9cd84fcd1b875759c313","marker":"PutYourMarkerHere","host":"beta.aviasales.ru","user_ip":"127.0.0.1","locale":"ru","trip_class":"Y","passengers":{"adults":1,"children":0,"infants":0},"segments":[{"origin":"MOW","destination":"LED","date":"2017-05-25"},{"origin":"LED","destination":"MOW","date":"2017-06-18"}]}' -H 'Content-type:application/json' http://api.travelpayouts.com/v1/flight_search

The answer comes in JSON format. The response contains the parameters:

  • locale - the language of the search result;
  • search_id - the unique identifier for the search query used to search results;
  • geoip_city - the geoip of the city where the request was made;
  • trip_class - the class of trip;
  • affiliate - the affiliate ID;
  • marker - the unique identifier of the affiliate;
  • user_ip - the user's IP address;
  • gates_count - the total number of agencies;
  • segments - a list of the trip components:
    • date - departure date;
    • origin - origin IATA;
    • destination - destination IATA;
  • meta - technical information;
    • uuid - unique identifier of the request;
  • passengers - passenger information;
    • adults - the number of adult passengers;
    • children - the number of children;
    • infants - the number of infants;
  • host - host's request;
  • currency_rates - exchange rate;

Please note! Use currency rates to convert the prices of flights to the currency you need (because the response contains the flight price in Russian rubles).

  • geoip_country - the geoip of the country where the request was made

Getting search results

In the body of the response is the parameter search_id; insert it into the URL:

http://api.travelpayouts.com/v1/flight_search_results?uuid=%search_id%

Then send the request to the server for search results:

curl -v -H 'Accept-Encoding:gzip,deflate,sdch' http://api.travelpayouts.com/v1/flight_search_results?uuid=ebe4fa71-bc07-40df-ae4e-4b72116583da --compressed

where "ebe4fa71-bc07-40df-ae4e-4b72116583da" - this is search_id.

As a result of the search, you will get the JSON array, where each element is a response from a definite agency.

Repeat the request until you get an associative array with one element search_id. The periodicity of sending requests isn't restricted.

One way

Request initialization

To get "One way" tickets, add a JSON into the body of the request:

{
"marker": "PutYourMarkerHere",
"host": "beta.aviasales.ru",
"user_ip": "127.0.0.1",
"locale": "ru",
"trip_class": "Y",
"passengers": {
"adults": 1,
"children": 0,
"infants": 0
},
"segments": [
{
"origin": "MOW",
"destination": "LED",
"date": "2017-06-18"
}
]
}

To get data, use the initialization code of the search:

curl -v -X POST -d '{"signature":"2a3e1bda117d113569bb6f8b60dba075","marker":"PutYourMarkerHere","host":"beta.aviasales.ru","user_ip":"127.0.0.1","locale":"ru","trip_class":"Y","passengers":{"adults":1,"children":0,"infants":0},"segments":[{"origin":"MOW","destination":"LED","date":"2017-06-18"}]}' -H 'Content-type:application/json' http://api.travelpayouts.com/v1/flight_search

Getting search results

In the body of the response is the parameter search_id; insert it into the URL:

http://api.travelpayouts.com/v1/flight_search_results?uuid=%search_id%

Then send the request to the server for search results:

curl -v -H 'Accept-Encoding:gzip,deflate,sdch' http://api.travelpayouts.com/v1/flight_search_results?uuid=%search_id% --compressed

As a result of the search, you will get the JSON array where each element is a response from a definite agency.

Repeat the request until you get an associative array with one element search_id. The periodicity of sending requests isn't restricted.

Open jaw

Request initialization

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.

To get "Open jaw" tickets, add a JSON into the body of the request:

{
    "signature":"64dd4ff2f8a6f690b69d6a72429bf827",
    "marker":"PutYourMarkerHere",
    "host":"beta.aviasales.ru",
    "user_ip":"127.0.0.1",
    "locale":"ru",
    "trip_class":"Y",
    "passengers":{
       "adults":1,
       "children":0,   
       "infants":0
    },
    "segments":[
    {
       "origin":"MOW",
       "destination":"LED",
       "date":"2017-02-18"
    },
    {
       "origin":"LED",
       "destination":"BER",
       "date":"2017-02-25"
    },
    {
       "origin":"BER",
       "destination":"LON",
       "date":"2017-03-05"
    }
    ]
}

To get data, use the initialization code of the search:

curl -v -X POST -d '{"signature":"08caa94413dc805880f835ba9d8ba98f","marker":"PutYourMarkerHere","host":"beta.aviasales.ru","user_ip":"127.0.0.1","locale":"ru","trip_class":"Y","passengers":{"adults":1,"children":0,"infants":0},"segments":[{"origin":"MOW","destination":"LED","date":"2017-06-18"},{"origin":"LED","destination":"BER","date":"2017-06-25"},{"origin":"BER","destination":"LON","date":"2017-07-05"}]}' -H 'Content-type:application/json' http://api.travelpayouts.com/v1/flight_search

Getting search results

In the body of the response is the parameter search_id; insert it into the URL:

http://api.travelpayouts.com/v1/flight_search_results?uuid=%search_id%

Then send the request to the server for search results:

curl -v -H 'Accept-Encoding:gzip,deflate,sdch' http://api.travelpayouts.com/v1/flight_search_results?uuid=%search_id% --compressed

As a result of the search, you will get the JSON array where each element is a response from a definite agency.

Repeat the request until you get an associative array with one element search_id. The periodicity of sending requests isn't restricted.

Example of answer

Attention! The link to the search results is relevant for 15 minutes. After this time, you must send a search query again.

[{
    "segments":[
    {
        "destination_country":"RU",
        "original_destination":"LED",
        "origin":"MOW",
        "origin_country":"RU",
        "original_origin":"MOW",
        "date":"2017-05-25",
        "destination":"LED"
    },
    {
        "destination_country":"RU",
        "original_destination":"MOW",
        "origin":"LED",
        "origin_country":"RU",
        "original_origin":"LED",
        "date":"2017-06-18",
        "destination":"MOW"
    }],
    "banner_info":{
    },
        "internal":false,
        "airports":{
            "LED":{
                "name":"Пулково",
                "time_zone":"Europe/Moscow",
                "country":"Россия",
                "rates":"259",
                "city":"Санкт-Петербург"
            },
            "DME":{
                "name":"Домодедово",
                "time_zone":"Europe/Moscow",
                "country":"Россия",
                "rates":"392",
                "city":"Москва"
            },
            "SVO":{
                "rates":"307",
                "country":"Россия",
                "name":"Шереметьево",
                "average_rate":"3.63",
                "city":"Москва",
                "time_zone":"Europe/Moscow"
            },
            "VKO":{
                "name":"Внуково",
                "time_zone":"Europe/Moscow",
                "country":"Россия",
                "rates":"211",
                "city":"Москва"
            }},
            "gates_info":{
                "20":{
                    "average_rate":4.43,
                    "rates":2967,
                    "currency_code":"rub",
                    "is_airline":false,
                    "productivity":16.9991,
                    "label":"OneTwoTrip",
                    "airline_iatas":{
                    },
                    "payment_methods":[
                        "card"
                    ],
                    "mobile_version":false
                    }},
                    "city_distance":634,
                    "meta":{
                        "uuid":"c9c6de8c-3fb4-404e-b88c-e9e0a605f183",
                        "gates":[
                        {
                            "duration":22.402996063232422,
                            "id":20,
                            "count":1456,
                            "good_count":1456
                        }]},
                    "airlines":{
                        "SU":{
                            "average_rate":"4.01",
                            "rates":"2362",
                            "alliance_name":"SkyTeam",
                            "name":"Аэрофлот",
                            "id":10
                        },
                        "UN":{
                            "average_rate":"3.98",
                            "rates":"2639",
                            "alliance_name":null,
                            "name":"Трансаэро",
                            "id":492
                        },
                        "S7":{
                            "average_rate":"3.95",
                            "rates":"2430",
                            "alliance_name":"OneWorld",
                            "name":"S7",
                            "id":444
                        },
                        "UT":{
                            "rates":"1843",
                            "alliance_name":null,
                            "name":"ЮТэйр",
                            "id":507
                        },
                        "U6":{
                            "average_rate":"3.62",
                            "rates":"1158",
                            "alliance_name":null,
                            "name":"Уральские авиалинии",
                            "id":503
                        }},
                    "filters_boundary":{
                        "arrival_datetime_0":{
                            "min":1418869200,
                            "max":1418950500
                        },
                        "arrival_datetime_1":{
                            "min":1419486600,
                            "max":1419554400
                        },
                        "flights_duration":{
                            "min":70,
                            "max":120
                        },
                        "stops_count":{
                            "0":4431
                        },
                        "departure_time_1":{
                            "min":"04:30",
                            "max":"22:55"
                        },
                        "departure_time_0":{
                            "min":"00:50",
                            "max":"23:30"
                        },
                        "departure_minutes_0":{
                            "min":50,
                            "max":1410
                        },
                        "departure_minutes_1":{
                            "min":270,
                            "max":1375
                        },
                        "price":{
                            "min":4431,
                            "max":8689
                        }},
                    "flight_numbers":[
                    [
                        "SU30",
                        "SU32"
                    ],
                    [
                        "SU31",
                        "SU33"
                    ]],
                    "affiliate_has_sales":false,
                    "proposals":[
                        {
                            "terms":{
                               "20":{
                                    "url":2000000,
                                    "unified_price":5867,
                                   "price":5867,
                                    "currency":"rub"
                            }},
                            "sign":"7573ea707c2ff84b243241961412ed34",
                            "segment":[
                            {
                                "flight":[
                                {
                                    "arrival":"LED",
                                    "aircraft":"AIRBUS A320",
                                    "local_departure_timestamp":1434588600,
                                    "operating_carrier":"UT",
                                    "duration":85,
                                    "local_arrival_timestamp":1432549200,
                                    "departure_date":"2015-05-25",
                                    "departure_time":"11:00",
                                    "arrival_date":"2015-05-25",
                                    "arrival_time":"12:25",
                                    "delay":0,
                                    "departure":"VKO",
                                    "number":369
                            }]},
                     {
                            "flight":[
                            {
                                "arrival":"DME",
                                "aircraft":"AIRBUS A320",
                                "local_departure_timestamp":1434588600,
                                "operating_carrier":"SU",
                                "duration":90,
                                "local_arrival_timestamp":1432549200,
                                "departure_date":"2015-06-18",
                                "departure_time":"10:05",
                                "arrival_date":"2015-06-18",
                                "arrival_time":"11:35",
                                "delay":0,
                                "departure":"LED",
                                "number":6131
                        }]}]},
                   }]}],
            "validating_carrier": "SU"
        }],
    "_ga":null,
    "signature":"4bb635b9353a1e933907d41841e23414",
    "search_id":"c9c6de8c-3fb4-404e-b88c-e9e0a605f183"
    },
    {
    "search_id":"c9c6de8c-3fb4-404e-b88c-e9e0a605f183"
}]

Full response example: response-example.json

The response includes the data:

  • search_id - unique identifier for the search query;
  • flight_numbers - numbers of the flight;
  • gates - information about phases of gates in the search process;
    • good_count - number of relevant tickets (if the agency has returned the ticket for the wrong dates or they are misspelled, they are filtered out by the system);
    • count - number of tickets uploaded from the agency;
    • duration - processing time of request;
    • id - ID agency;
    • error - error information;
      • tos - content of error.
    • uuid - request ID;
    • city_distance - distance between the cities of origin and destination;
    • gates_info - information about the agent (Ticket Seller):
      • currency_code - payment currency code;
      • is_airline - is an airline;
      • average_rate - average rating of agencies;
      • rates - rating agency (count voters);
      • mobile_version - having a mobile version of the site;
      • productivity - productivity;
      • airline_iatas - IATA airline code, if the gate sells tickets;
      • payment_methods - payment methods;
      • label - agency name.
    • signature - signature of request;
    • segments - array data of flights:
      • destination_country - code of the country of destination;
      • original_destination - code of the city of destination;
      • origin - origin IATA;
      • destination - destination IATA;
      • date - departure date.
    • flight_numbers - flight numbers;
    • airlines - information about the airlines:
      • deeplink_site_name - address of the airline's website;
      • id - identification number of the airline;
      • site_name - name of the airline's website;
      • alliance_name - alliance of the airline;
      • average_rate - average rating;
      • rates - number of ratings;
      • deeplink_id - ID links to airline's website;
      • name - name of airline.
    • proposals - an array of variants;
      • segment
      • flight - flight details:
        • departure - departure IATA code;
        • duration - flight duration in minutes;
        • departure_date - departure date (UNIX-time);
        • departure_time - departure time (UNIX-time);
        • local_departure_timestamp - local departure time in UNIX format;
        • arrival_time - arrival time (UNIX-time);
        • local_arrival_timestamp - local arrival time in UNIX format;
        • number - flight number. To generate a full flight number, use the number and operating_carrier parameters;
        • delay - duration of stop between flights (in minutes);
        • operating_carrier - IATA code of airline that performs the carriage;
        • arrival_date - arrival date;
        • aircraft - type of aircraft;
        • arrival - IATA code of arrival.
      • terms - information about the flight’s cost:
        • price - trip price in original currency (type listed in the field currency);
        • currency - currency type;
        • flights_baggage - the number of pieces of baggage and its weight. 
          • "" - there is no information about baggage;
          • false - baggage is not included in a price;
          • {int}PC{int} - number of bags by %somevalue% kilogram. For example, 2PC23 - means two baggage pieces of 23 kg.
          • {int} - number of bags does not matter, the total weight is limited.
        • unified_price - price of flight in basic currency (Russian ruble);
        • url - code to generate links for buyers (as forming the link; see below).

Attention! Use currency rates to convert the prices of flights to the currency you need (because the response contains the flight price in Russian rubles).

  • sign - unique id of the ticket, to integrate information from different agencies in one ticket;
  • airports - information about airports;
  • IATA - IATA code;
    • city - city where airport is located;
    • average_rate - average rating of airport;
    • rates - number of ratings;
    • country - country where airport is located;
    • name - airport name;
    • time_zone - time zone of airport.
  • filters_boundary - array data for filtering:
    • stops_duration - time between flights (maximum and minimum);
    • flights_duration - flights duration (maximum and minimum);
    • arrival_datetime_0 - arrival datetime (maximum and minimum);
    • price - price of flights (maximum and minimum);
    • departure_time_0 - departure time (maximum and minimum);
    • stops_count - stops count.

Additional Information in the Response

Some airline companies and agencies provide additional information about flights, aircraft, and on-board services. These fields and their content are described below. You may use this information on your websites or ignore it — the main information about the tickets is given above.

  • banner_info — service information provided by an airline company;
  • airlines/AF/— information from a specific airline company (where AF is the IATA designator code):
    • jets — information about the airline company’s aircraft:
      • seatType — seat type in an aircraft (Angle Lie Flat, Flat Bed — special seat, can be transformed into a bed, etc.; Standard — standard seat);
      • typeClass — class type (Business class, Economy class);
      • seatWidth — seat width (inches);
      • aircraft — aircraft type;
      • seatPitch — distance between the seats (inches);
      • videoType — video type (Overhead TV — on a seat, located in front, On-Demand TV — common TV, headphones are given on demand, None — unavailable);
      • wifi — Wi-Fi on-board;
      • id — unique aircraft ID (service parameter);
      • powerType — availability of an AV receptacle in a seat;
      • airline — IATA designator code;
      • laptopPower — availability of a notebook receptacle.
    • ageOfPlanes — average age of an airline company’s aircraft;
    • alliance — alliance joined by an airline company;
    • economyLegroom — average distance between the seats in economy class (inches);
    • freeStandardCarryOn — availability of free space for hand luggage;
    • infantsLapCost — age from which a child is not considered an infant;
    • minorsNotTravelAloneFrom — opportunity for minors to travel alone;
    • iata — IATA designator code;
    • checkedBaggagePrice1st — luggage registration cost;
    • baggage — information about the luggage on a flight;
      • excess — text information about restrictions for luggage transportation;
      • checked — text information about the prepaid luggage weight and size, and the necessity to make an additional payment if the size exceeds the standard;
      • carryOn — text information about hand-luggage transportation rules;
      • airline — IATA designator code;
      • sportMusical — rules for transporting large musical instruments and sport equipment.
    • frequentFlyerPrograms — loyalty program for clients;
    • aircrafts — the number of aircraft owned by an airline company;
    • carryOnStandard — presence of a hand-luggage transportation standard;
    • lowcost — is/not a low-cost airline company;
    • freeCheckedBag — opportunity for luggage transportation for free within the extent permissible.
    • meals — airline company’s on-board types of menus;
    • checkin — ways to register provided by an airline company:
      • mobileCheckIn — opportunity of registration using a mobile app;
      • seatOnlineCheckIn — seat selection at registration;
      • onlineCheckInwithBag — online luggage registration;
      • airline — IATA designator code;
      • onlineCheckIn — rules for online registration;
      • requirementOnlineCheckIn — rules for online registration;
      • airportCheckIn — rules for registration in an airport;
      • timeBoardingGate — time for boarding before departure;
    • minorsNotTravelAloneTo — age from which minors may travel without grown-ups;
    • pet — information about transportation of animals by an airline company:
      • cargo — transportation in luggage;
      • baggage — rules for transportation in luggage;
      • restriction — restrictions;
      • documentation — required documents;
      • book — booking;
      • airline — IATA designator code;
      • method — type of transportation;
      • cabin — information about transportation in a cabin;
      • kennel — additional requirements;
      • fee — information about the fee for transportation of animals;
    • minor— information about the fee for minors:
      • age — age from which this tariff may be applied;
      • airline — IATA designator code;
      • booking — information about the booking;
      • aboutService — information about the servicing;
      • flightRestriction — information about restrictions;
      • fee — tariff fee.
    • infant — information about the tariff for infants:
      • payInternational — information about the tariff;
      • exitRow — restrictions for selection of a seat near the emergency door;
      • childTurnTwo — tariff rules for transfer flights;
      • reserveSeat — information about seats for infants;
      • payInfant — payment information;
      • airline — IATA designator code;
      • baggage — luggage in a ticket for an infant;
      • childRestraintDevices — information about transportation of luggage required for an infant (baby carriage, carrying bag, etc.);
      • infantAmenitites — information about additional services rendered on-board for an infant;
      • payDomestic — additional fee.

How to get a link to the agency website

Attention! The reference to the agency's website must be received only when the user clicks the "Buy" button. Automatic collection of all links from the answer is prohibited. Violation of this rule will disable the API search for the partner.

To get a link to the site of the ticket booking agencies:

1. Send a request to the following address: http://api.travelpayouts.com/v1/flight_searches/%search_id%/clicks/%terms.url%.json

where search_id is the ID from the answer of the request, terms.url - URL parameter from the response.

2. You will receive a response like this:

{
"params": {},
    "method": "GET",
    "url": "https://www.svyaznoy.travel/?utm_source=aviasales.ru&utm_medium=cpa&utm_campaign=meta_avia#MOW0906/BKK1506/A1/C0/I0/S0/22316/EK-132;EK-374/EK-373;EK-131&marker=7uh46i0v2",
    "gate_id": 62,
    "click_id": 22135952358110
}

To move on to the booking, give your visitors a link from the parameter "url".

The “lifetime” of such links is 15 minutes, after which you will need to search again for the current prices and generate a new reference to the transition.

In our example, this is a link of the form:

https://www.svyaznoy.travel/?utm_source=aviasales.ru&utm_medium=cpa&utm_campaign=meta_avia#MOW0906/BKK1506/A1/C0/I0/S0/22316/EK-132;EK-374/EK-373;EK-131&marker=7uh46i0v2

How to make the autocomplete of airports and cities

To make the autocomplete of cities or airports in the search, use a query of the following form:

www.JetRadar.com/autocomplete/places?q=term&locale=en,

www.JetRadar.com/autocomplete/places?q=term&locale=th

or

www.JetRadar.co.th/autocomplete/places?q=term

where term - the main parameter specified as text; locale - the display language.

Example of API answer

[{
   "name":"Sydney, NS, Australia",
   "index_strings":[
      "sydney",
      "сидней",
      "ซิดนีย์",
      "sidney",
      "悉尼",
      "kingsford smith international",
      "kingsford smith",
      "sydney kingsford smith",
      "кингсфорд смит",
      "สนามบินซิดนีย์",
      "悉尼机场"
   ],
   "iata":"SYD",
   "airport_name":"Kingsford Smith",
   "coordinates":[
      -33.932922,
      151.1799
   ],
   "searches_count":469531,
   "location":{
      "lat":-33.932922,
      "lon":151.1799
   },
   "city_iata":"SYD",
   "country_iata":"AU"
},
{
   "name":"Sidney, MT, United States",
   "index_strings":[
      "sidney",
      "сидней",
      "ซิดนีย์",
      "悉尼",
      "richland municipalcipal",
      "richland municipal",
      "สนามบินซิดนีย์",
      "sindey richland havalimanı",
      "悉尼里奇兰机场"
      ],
   "iata":"SDY",
   "airport_name":"Richland Municipalcipal",
   "coordinates":[
      47.706944,
      -104.19194
   ],
   "searches_count":2282,
   "location":{
      "lat":47.706944,
      "lon":-104.19194
   },
   "city_iata":"SDY",
   "country_iata":"US"
}]

Logos of airlines

Flight logos are available here: http://pics.avs.io/width/height/iata.png

where, width - the width of the logo, height - the height of the logo, iata - IATA airline code. The size of the logo can be anything.

For example: http://pics.avs.io/200/200/UN.png.

Was this article helpful?

Have more questions? Submit a request