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 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 affiliate programm and submit your request on support@travelpayouts.com with next 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 url of your project, design prototypes, description of your project and how our API will be used. 
  4. Ajax-requests to the API doesn't work because the access token is passed unencrypted. You need to 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 API will be used);
  • user_ip - user's ip address;
  • locale - the 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)". IATA code is shown by uppercase letters (for example: "Paris, France (PAR)");
    • destination - destination IATA or string "City, Country (IATA)". IATA code is shown by uppercase letters (for example: "Berlin, Germany (BER)");
    • date - departure date yyyy-mm-dd (for example: "2015-09-08").
  • signature -  the Query Signature is constructed from token, marker and all the values ​​of the query parameters sorted alphabetically and separated by colon. How to create signature look here.

To get "Round trip" tickets you should add a JSON into the body of 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 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 - unique identifier for the search query it's used to search results;
  • geoip_city - geoip of city where the request was made;
  • trip_class - class of trip;
  • affiliate - affiliate ID;
  • marker - the unique identifier of the Affiliate;
  • user_ip - user's ip address;
  • gates_count - the total number of agencies;
  • segments - 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 attention! You should use currency rates to convert prices of flights to the currency that you need (because the response contains the flight price in Russian rubles).

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

Getting search results

In the body of the response there is the parameter search_id, you should insert it into the URL:

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

And 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 wil get JSON array where each element is a response from a definite agency.

You should be repeating 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 you should add a JSON into the body of 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 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 there is the parameter search_id, you should insert it into the URL:

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

And 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 wil get JSON array where each element is a response from a definite agency.

You should be repeating 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 first landed. For example London - Paris - Berlin - London.

To get "Open jaw" tickets you should add a JSON into the body of 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 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 there is the parameter search_id, you should insert it into the URL:

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

And 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 wil get JSON array where each element is a response from a definite agency.

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

Example of answer

Pay attention! Link to search results is relevant 15 minutes. After this time you need to 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 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 misspelled, they are filtered out by the system);
    • count - number of tickets uploaded from agency;
    • duration - processing time of request;
    • id - id agency;
    • error - error information;
      • tos - content of error.
  • uuid - request id;
  • city_distance - the distance between the city 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 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 the airline's website;
    • id - identification number of airlines;
    • site_name - the name of the airline's website;
    • alliance_name - alliance of airline;
    • average_rate - average rating;
    • rates - number of ratings;
    • deeplink_id - id links to airline's website;
    • name - name of airlines.
  • 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;
      • delay - duration of stop between to 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 of the flights cost:
      • price - trip price in the original currency (type listed in the field currency);
      • currency - currency type;
      • unified_price - price of flight in basic currency (russian ruble);
      • url - code to generate links for buyers (as forming the link see below).

Please attention! You should use currency rates to convert prices of flights to the currency that 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 give an additional information about the flights, aircrafts and on-board services. The 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/ — the thread contains information from a specific airline company (where AF - the IATA designator code):
    • jets — information about the airline company’s aircrafts:
      • 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 — the unique aircraft id (service parameter);
      • powerType — availability of AV receptacle in a seat;
      • airline — the IATA designator code;
      • laptopPower — availability of a notebook receptacle.
    • ageOfPlanes — the average age of an airline company’s aircrafts;
    • alliance — the alliance, joined by an airline company;
    • economyLegroom — the average distance between the seats in the Economy class (inches);
    • freeStandardCarryOn — availability of a free space for hand-luggage;
    • infantsLapCost — the age, from which a child is not considered as an infant;
    • minorsNotTravelAloneFrom — opportunity for the minors to travel alone;
    • iata — the 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 one;
      • carryOn — text information about the hand-luggage transportation rules;
      • airline — the IATA designator code;
      • sportMusical — the rules for transportation of large sized musical and sport instruments.
    • frequentFlyerPrograms — loyalty program for clients;
    • aircrafts — the number of aircrafts, 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 — the airline company’s on-board menu types;
    • checkin — ways of registration, provided by an airline company:
      • mobileCheckIn — opportunity of registration using a mobile app;
      • seatOnlineCheckIn — seat selection at registration;
      • onlineCheckInwithBag — online luggage registration;
      • airline — the IATA designator code;
      • onlineCheckIn — the rules for online registration;
      • requirementOnlineCheckIn — the rules for online registration;
      • airportCheckIn — the rules for registration in an airport;
      • timeBoardingGate — time for boarding before the departure;
    • minorsNotTravelAloneTo — the age of minors, from which they may travel without grown-ups;
    • pet — information about transportation of animals by an airline company:
      • cargo — transportation in the luggage;
      • baggage — the rules for transportation in the luggage;
      • restriction — restrictions;
      • documentation — required documents;
      • book — booking;
      • airline — the IATA designator code;
      • method — the 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 the minors:
      • age — the age, for which this tariff may be applied;
      • airline — the IATA designator code;
      • booking — information about the booking;
      • aboutService — information about the servicing;
      • flightRestriction — information about the restrictions;
      • fee — the tariff fee.
    • infant — information about the tariff for the infants:
      • payInternational — information about the tariff;
      • exitRow — restrictions for selection of a seat near the emergency door;
      • childTurnTwo — the tariff rules for transfer flights;
      • reserveSeat — information about the seats for the infants;
      • payInfant — payment information;
      • airline — the IATA designator code;
      • baggage — the luggage in a ticket for an infant;
      • childRestraintDevices — information about transportation of the luggage, required for an infant (baby carriage, carrying bag, etc.);
      • infantAmenitites — information about the 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 click "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 ticket booking agencies you should:

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

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

2. As a result you 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 to the booking give to your a visitors link from parameter "url".

The time of "life" of such links is 15 minutes, after which the need to search again for the current prices and generating 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 citys or airports in the searching you should use the 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 is specified as a text; locale - the display language.

Пример ответа

[{
   "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

The flights 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 logo can be anything.

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

Have more questions? Submit a request