We’ve gathered answers to all your most important questions related to API.
- What is the API and what is it for?
- Which of your services are presented in the API?
- How an access to the API may be gained?
- Where the API can be used?
- You have several API types, what is the difference between them?
- What are the restrictions on queries to the API?
- How a signature (md5 – signature) can be formed for a query to the flight search API?
- How a signature (md5 – signature) can be formed for a query to the hotels search API?
- How can the departure and destination airports be defined?
- Where can I find the IATA airport code for sending the API query?
- Why do I get fewer tickets, than in your search?
- How long are the results stored in the airline tickets search API?
- Explain in a few words, how does the airline tickets search API works on a real time basis?
- What does the auto-complete mean and how can it be implemented at searching the hotels?
- How the auto-complete can be implemented at work with the airline tickets search API?
- How a user’s location may be worked out?
- How the departure and destination cities are defined from the response from airline tickets 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 can access to the API be gained?
To get access to the data API, price map API, price calendar API, and static data on the hotels, you need to:
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 2 to 7 days depending on the type of query.
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 it. 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 for the websites to use the API?
The data access API may be used if a partner agreement is observed. To gain access to the airline tickets and hotel 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 "Book" 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 "Book" button should be 9%. Conversion of the "Book" 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 ID (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.com&locale=en&marker=WriteHereYourPartnerID(marker)&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.
You can find your partner ID in the bottom left corner of your Travelpayouts account.
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 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.com:en:WriteHereYourPartnerID(marker):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 API token is available in your Travelpayouts account in the Aviasales tools in the API section.
Using the derived string:
“WriteHereYourToken:beta.test.com:en:WriteHereYourPartnerID(marker):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.
Attention! Signature is case-sensitive.
How a signature (md5 – signature) can be formed for a query to the hotels search API?
Let our query be as follows:
Then we have the following query parameters:
- iata=HKT;
- checkIn=2022-12-10;
- checkOut=2022-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=2022-12-10;
- checkOut=2022-12-13;
- childrenCount=1;
- currency=USD;
- customerIP=192.168.1.1;
- iata=HKT;
- marker=WriteHereYourPartnerID(marker)r;
- 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 partner ID (they can be found in the Travelpayouts account) before them:
WriteHereYourToken:WriteHereYourPartnerID(marker):2:2022–12–10:2022–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.
Attention! Signature is case-sensitive.
To create a query, it is necessary to take the query parameters, add the partner’s security token and partner ID to them, and fix using & into the search string:
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.
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 the airline tickets search API works on a real-time basis.
The reasoning is as follows:
- You send a request with the parameters, described in the documentation, to http://api.travelpayouts.com/v1/flight_search.
- You receive a response containing a search_id.
- Using this search_id, you send a new request to http://api.travelpayouts.com/v1/flight_search_results?uuid=%search_id%
- You continue sending the request from item 3 until you receive an array with only the parameter – search_id.
- 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:
- 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
Read more in the documentation.
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. You can find more information here.