FAQ about API

What is the API and what is it for?

The API makes it possible to send queries to our server and receive useful information about tickets and hotels. Partners can receive the following data:

  • Information about the cheapest tickets to a selected destination;
  • Information about airports and airline companies;
  • Lists of the most popular flight routes from a selected city;
  • Detailed information about a hotel or suite;
  • Information about special offers from the airline companies and a host of other things.

Which of your services are presented in the API?

With the help of the API, partners gain access to the following services:

  • Information about special offers;
  • Prices data;
  • Flights search API;
  • Hotels search.

How an access to the API may be gained?

Partners gain access to the data API, price mpa API, price calendar API and static data on the hotels immediately after registration in the partner program. In addition, if a partner’s project meets the requirements, he or she gains access to the flights search API and hotels API.

Where the API can be used?

The API is recommended for indicating the following information on website pages:

  • Static data on cities, airports, airline companies;
  • Cost of airline tickets and suits in hotels;
  • Information about the development of one’s own search engine for airline tickets and hotels;
  • Information about the development of a mobile application for airline ticket searches.

You have several API types, what is the difference between them?

The data access API (obtained after registration) provides partners with access to our cache, containing the history of queries from all users for the last 48 hours.

The real-time search for airline tickets and hotels search enables partners to receive actual information from the agencies and airline companies through our server.

What are the restrictions on queries to the API?

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 requires. The data access API does not have such restrictions. While using the data API, it is recommended to cache the results onsite for 24 hours; this will reduce the number of queries to our servers and increase the download speed of the partner’s website pages.

Are there any requirements to the websites for using the API?

The data access API may be used if a partner agreement is observed. To gain access to the airline tickets and hotels search, one should send the following information to support@travelpayouts.com:

Every search query must be initiated by a user. A query result must be comprehensively shown to a user and have a “Buy” button next to each flight variant.

The models/design of a future or existing project, in which the airline tickets search function will be implemented, shall be presented together with a project description itself and information about how our API will be used.

*The minimum conversion ratio of searches into the clicks using the “Buy” button should be 9%. Conversion of the “Buy” button clicks into purchases – not lower than 5%.

* – is not accepted for projects during promotions and partner marathons.

How a signature (md5 – signature) can be formed for a query to the airline tickets search API?

A signature is an encoded query key formed from the query parameters, partner marker and a security token. Several actions shall be carried out to form a signature.

Let our query be as follows:

{
 "marker": "%marker%",
 "host": "%server_host%",
 "user_ip": "%user_ip_address%",
 "locale": "ru",
 "trip_class": "Y",
 "passengers": {
 "adults": "1",
 "children": "0",
 "infants": "0"
 },
 "segments": [
 {
 "origin": "MOW",
 "destination": "LED",
 "date": "2015-11-25"
 },
 {
 "origin": "LED",
 "destination": "MOW",
 "date": "2015-12-18" 
}]}

Alphabetically sort the parameters from the query:
host=beta.test.ru&locale=ru&marker=WriteHereYourMarker&adults=1&children=0&infants=0&date=2015–11–25&destination=LED&origin=MOW&date=2015–12-18&destination=MOW&origin
=LED&trip_class=Y&user_ip=127.0.0.1.

Your affiliate marker is available in the private office.

Note that data nesting is taken into account at sorting. If an element contains an array (for example, segments) or a list of parameters (for example, passengers), the content of this element shall be sorted separately and be entered into the corresponding general list’s field.

The content shall not be sorted with the top-level parameters.

The parameters within an array are sorted according to the order of sequence of the curved brackets { }. 

After assortment, congregate a line containing only the parameter values (the order of sequence is the same as in item 1):

beta.aviasales.ru:ru:WriteHereYourMarker:1:0:0:2015–11–25:LED:MOW:2015–11–18:MOW:LED:Y:127.0.0.1.

The colons are used to separate the values.

Add the value of your partner security token into the string prefix from item 2. 

The affiliate token is available in the private office in the section "Developers".

Using the derived string:

WriteHereYourToken:beta.test.ru:ru:WriteHereYourMarker:1:0:0:2015–11–25:LED:MOW:2015–12–18:MOW:LED:Y:127.0.0.1” from the md-5 signature.

The obtained result (0203ccb0c37534cc9d0835ac3bb3cfec) shall be the query signature.

How a signature (md5 – signature) can be formed for a query to the hotels search API?

Let our query be as follows:

http://engine.hotellook.com/api/v2/search/start.json?iata=HKT&checkIn=2015-12-10&checkOut=2015-12-13&adultsCount=2&customerIP=192.168.1.1&childrenCount=1&lang=ru&currency=USD&timeout=20&waitForResult=0

Then we have the following query parameters:

  • iata=HKT;
  • checkIn=2015-12-10;
  • checkOut=2015-12-13;
  • adultsCount=2;
  • customerIP=192.168.1.1;
  • childrenCount=1;
  • lang=ru;
  • currency=USD;
  • timeout=20;
  • waitForResult=0.

Let’s sort them alphabetically:

  • adultsCount=2;
  • checkIn=2015-12-10;
  • checkOut=2015-12-13;
  • childrenCount=1;
  • currency=USD;
  • customerIP=192.168.1.1;
  • iata=HKT;
  • marker=WriteHereYourMarker;
  • lang=ru;
  • timeout=20;
  • waitForResult=0.

After that, let’s fix the values of the assorted parameters using the colons and add the partner security token and marker (they can be found in each partner’s personal account) before them:

WriteHereYourToken:WriteHereYourMarker:2:2015–12–10:2015–12–13:1:USD:192.168.1.1:HKT:ru:20:0

This string is used for signature creation. As a result, we have the following: 9961b6ecb56d45935667141b79cfbc28.

To create a query, it is necessary to take the query parameters, add the partner’s security token and marker to them and fix using & into the search string:

http://engine.hotellook.com/api/v2/search/start.json?iata=HKT&checkIn=2015-12-10&checkOut=2015-12-13&adultsCount=2&customerIP=192.168.1.1&childrenCount=1&lang=ru&currency=USD&timeout=20&waitForResult=0&marker=16886&signature=878c8cdd72222323d925dd8e8a37c6b1

How can the departure and destination airports be defined?

It will be necessary to take the data from the two blocks to determine whether an airport is the place of destination or departure in the response from the flights search API. The first block – the “airports” – contains the IATA code of the city where each airport is situated. The second block– the “flight” – contains the arrival and departure parameters, which are the IATA codes of the destination or departure cities. It will be possible to define an airport type by comparing these values.

Where can I find the IATA airport code for sending the API query?

The IATA airport codes list can be downloaded here.

Why do I get fewer tickets, than in your search?

When you use the real-time airline tickets search API, you receive an answer from the same agencies and airline companies as from our website. In most cases, the reason for fewer responses is a short pause between query sending and result generation. It takes at least 30 seconds to receive a response from all agencies; otherwise, such a response may not contain all data.

How long are the results stored in the airline tickets search API?

Results with the flights variants are stored for about 15 minutes; then they are deleted from the server.

Explain in a few words, how does the airline tickets search API works on a real time basis?

The reasoning is as follows:

  1. You send a query with the parameters, described in the documentation, to http://api.travelpayouts.com/v1/flight_search.
  2. You receive a response containing a search_id.
  3. Using this search_id, you send a new response to http://api.travelpayouts.com/v1/flight_search_results?uuid=%search_id%
  4. You continue sending the response from item 3 until you receive an array with only the parameter – search_id.
  5. You process the data received

What languages do the airline tickets and airports search API support?

Our tickets search API supports the following languages:

  • Russian (ru);
  • English (en);
  • French (fr);
  • Spanish (sp);
  • German (de);
  • Italian (it).

This means you can create a website or mobile application for any country speaking any language above.

What does the auto-complete mean and how can it be implemented at searching the hotels?

The auto-complete function is when a user enters a query into the search string and the system shows the coincidence found.

The auto-complete function for hotels search is realized using the following query:

http://engine.hotellook.com/api/v2/lookup.json?query=moscow&lang=ru&lookFor=hotel&limit=1

where: the “query” – the main parameter, is set as the text, the auto-complete function shall be applied according to the text; “lang” – output language; “limit” – limitation of the results shown, from 1 to 100, default value – 10; “convertCase” – automatic changing of the keyboard layout (essential for Russian-speaking users; for example, at the “vjcrdf” query, the results for “Москва” shall be found). Values – 1 or 0, default value – 1. Read more in the documentation.

How the auto-complete can be implemented at work with the airline tickets search API?

Use the following query type to use the auto-complete function when searching a city or airport:

http://autocomplete.travelpayouts.com/jravia?locale=en&with_countries=false&q=Lond&callback=function,

  • q - the main parameter is specified as text;
  • locale - the output language;
  • with_countries - used if auto-complete created for the country (false - the response does not contain information about the country, true - the response contains information about the country);
  • callback - function name in which the response is returned.

Example of response

[
  {
    "_id":"4eda5f858792904be4001433",
    "coordinates":{
      "lon":37.617633,
      "lat":55.755786
    },
    "city_fullname":"Москва, Россия",
    "city_code":"MOW",
    "name":null,
    "_type":"city",
    "_score":67.74186,
    "city_name":"Москва",
    "title":"Москва",
    "country_code":"RU",
    "country_name":"Россия",
    "code":"MOW"
  },
  {
    "_id":"4eda61628792904be4003b20",
    "coordinates":{
      "lon":43.149445,
      "lat":36.3075
    },
    "city_fullname":"Мосул, Ирак",
    "city_code":"OSM",
    "name":"Мосул",
    "_type":"airport",
    "_score":26.681381,
    "city_name":"Мосул",
    "title":"Мосул",
    "country_code":"IQ",
    "country_name":"Ирак",
    "code":"OSM"
}]

How a user’s location may be worked out?

The query below:

http://www.travelpayouts.com/whereami?locale=en&callback=useriata&ip=62.105.128.0

restores the IATA code and a city name nearest to a user.

How the departure and destination cities are defined from the response from airline tickets API?

Each response contains the parameters: original_destination and original_origin. These are the values of the departure and destination cities.

For example, we have created a query for a flight: Murmansk – Barnaul – Murmansk and received a response with the flight variants.

Let’s consider one roundtrip flight from such a response:

{
"proposals":[
    {
    "sign":"ce23f75099cc3756c1396362061e379b",
    "max_stops":2,
    "carriers":[
        "SU"
    ],
    "min_stop_duration":110,
    "terms":{
        "183":{
            "currency":"rub",
            "price":"28855",
            "unified_price":28855,
            "url":18300000
        }
    },
    "segment":[
        {
        "flight":[
            {
                "departure_time":"11:25",
                "departure_timestamp":1432542300,
                "departure":"MMK",
                "local_departure_timestamp":1432553100,
                "duration":125,
                "operating_carrier":"SU",
                "arrival":"LED",
                "number":6342,
                "delay":0,
                "arrival_time":"13:30",
                "aircraft":"319",
                "departure_date":"2015-05-25",
                "arrival_date":"2015-05-25",
                "arrival_timestamp":1432549800,
                "local_arrival_timestamp":1432560600
            },
            {
                "departure_time":"18:45",
                "departure_timestamp":1432568700,
                "departure":"LED",
                "local_departure_timestamp":1432579500,
                "duration":75,
                "operating_carrier":"SU",
                "arrival":"SVO",
                "number":39,
                "delay":315,
                "arrival_time":"20:00",
                "aircraft":"320",
                "departure_date":"2015-05-25",
                "arrival_date":"2015-05-25",
                "arrival_timestamp":1432573200,
                "local_arrival_timestamp":1432584000
            },
            {
                "departure_time":"21:50",
                "departure_timestamp":1432579800,
                "departure":"SVO",
                "local_departure_timestamp":1432590600,
                "duration":250,
                "operating_carrier":"SU",
                "arrival":"BAX",
                "number":1430,
                "delay":110,
                "arrival_time":"05:00",
                "aircraft":"321",
                "departure_date":"2015-05-25",
                "arrival_date":"2015-05-26",
                "arrival_timestamp":1432594800,
                "local_arrival_timestamp":1432616400
            }
            ]
        },
        {
        "flight":[
            {
                "departure_time":"09:00",
                "departure_timestamp":1434596400,
                "departure":"BAX",
                "local_departure_timestamp":1434618000,
                "duration":260,
                "operating_carrier":"SU",
                "arrival":"SVO",
                "number":1433,
                "delay":0,
                "arrival_time":"10:20",
                "aircraft":"320",
                "departure_date":"2015-06-18",
                "arrival_date":"2015-06-18",
                "arrival_timestamp":1434612000,
                "local_arrival_timestamp":1434622800
            },
            {
                "departure_time":"15:05",
                "departure_timestamp":1434629100,
                "departure":"SVO",
                "local_departure_timestamp":1434639900,
                "duration":155,
                "operating_carrier":"SU",
                "arrival":"MMK",
                "number":1324,
                "delay":285,
                "arrival_time":"17:40",
                "aircraft":"SU9",
                "departure_date":"2015-06-18",
                "arrival_date":"2015-06-18",
                "arrival_timestamp":1434638400,
                "local_arrival_timestamp":1434649200
            }
        ]
        }
    ],
    "is_direct":false,
    "total_duration":1575,
    "segment_durations":[
        875,
        700
    ],
    "stops_airports":[
        "LED",
        "SVO",
        "BAX",
        "SVO",
        "MMK"
    ],
    "segments_time":[
        [
            1432542300,
            1432594800
        ],
        [
            1434596400,
            1434638400
        ]
    ],
    "segments_airports":[
        [
            "MMK",
            "BAX"
        ],
        [
            "BAX",
            "MMK"
        ]
    ],
    "validating_carrier":"SU",
    "max_stop_duration":315
    }]
}

The response contains the “max_stops” parameter – it shows the maximum number of transfers in this case.

The “segment” array contains information about the flights in the “flight” arrays.

The first “flight” array – the flight to the destination city, the second one – the flight to the departure city (backward). Every array with the flight contains the “departure” and “arrival” parameters – these are the IATA codes of the departure and destination airports.

From our example, we can see that the following information is being found:

  • Flight to the destination city: “Murmansk (MMK) – St. Petersburg (LED) – Moscow (SVO) – Barnaul (BAX)”;
  • Flight to the departure city (backward): “Barnaul (BAX) – Moscow (SVO) – Murmansk (MMK)”.

Thus, according to the response received, we can define the departure and destination cities.

The response contains the “segments_airports” parameter as well; this parameter contains the IATA codes of the departure and destination airports without transfer airports.

Was this article helpful?

Have more questions? Submit a request