Hotel search API

Requirements for Hotels 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 “Book” button next to each hotels option.
  2. The conversion rate for searches via the Book link must be 9% or more. The conversion rate from the Book button to actual purchases must be at least 5%.
  3. We'll also need to see the URL of your project, your design prototypes, a description of your project, and how our API will be used. 

Read more about how to get access to the Hotel search API in the article Requirements for Hotels API access.

Hotels search API description

With API for hotel search, an affiliate can create his or her own search of hotels. Access to the hotel search API is free, limited, and available on an individual basis on request from the affiliate.

To access the search API hotels, submit your request to support@travelpayouts.com with the following information:

  • Why aren’t the standard methods of integration (search forms, White Label, API access to data, WordPress plugin) suitable for you?
  • Please describe the algorithm you plan to use with our API.
  • How do you plan to ask a user for the input (dates and location)?
  • How do you plan to display accommodation options?
  • Please provide interface designs or prototypes, so that we can understand how visitors will interact with your project.

Attention, please! Hotels data from Booking.com is missing in the API of hotels. The reason for this is the policy of the company to work through the API and White Label.

Search architecture

Search by hotel IATA-code or cityId (ID location), or hotelId (ID hotel). All options or just one can be specified. If you specify hotelId and cityId, only hotelId will be used. If you specify iata and cityId, iata will be used.

When using this hotel search engine, it is possible to access its results not immediately, but after a period of time not exceeding 15 minutes. Handling is on the request ID searchId.

Attention! The default number of requests is limited to 200 requests per hour for one IP address. If you need to process more requests, send a note to support@travelpayouts.com.

Request parameters

Required parameters are highlighted in bold.

  • cityId – the location ID (the query static/locations.json).
  • hotelId – the hotel ID (the query static/hotels.json).
  • iata – iata code of city.

Note. The request must have at least one of the required parameters iata, cityId, or hotelId.

  • checkIn – check-in date format: yyyy–MM–dd.
  • checkOut – check-out date format: yyyy–MM–dd.
  • adultsCount – number of adults.
  • customerIP – IP of the user who initiated the request.
  • childrenCount – the number of children; possible values - from 0 to 3. Default - 0.
  • childAge1, childAge2, childAge3 – ages of children (if childrenCount greater than 0). The default age is 1 year (max = 17).
  • lang – the language of the search result. Stated together with the region.
    • en_US;
    • en_GB;
    • ru_RU;
    • de_DE;
    • en_AU;
    • en_CA;
    • en_IE;
    • es_ES;
    • fr_FR;
    • it_IT;
    • pl_PL;
    • th_TH.
  • currency:
    • Australian dollar (AUD)
    • Azerbaijani manat (AZN)
    • Belarusian ruble (BYN)
    • Canadian dollar (CAD)
    • Swiss franc (CHF)
    • Chinese yuan (CNY)
    • Egyptian pound (EGP)
    • Euro (EUR)
    • Pound Sterling (GBP)
    • Hong Kong dollar (HKD)
    • Indonesian rupee (IDR)
    • Indian rupee (INR)
    • Norwegian krone (KOK)
    • Kazakhstani tenge (KZT)
    • New Zealand dollar (NZD)
    • Philippine Peso (PHP)
    • Pakistani Rupee (PKR)
    • Russian ruble (RUB)
    • Singapore dollar (SGD)
    • Thai Baht (THB)
    • Ukrainian hryvnia (UAH)
    • US dollar (USD)
    • South African rand (ZAR)
  • waitForResult – wait for the completion of all searches for partners, possible values 0 or 1.
    • 1 – the connection is open before all the data from the partners. The result is returned to the user query and its searchId.
    • 0 – the connection will be terminated immediately and returned to the user searchId (default).

Sample query

http://engine.hotellook.com/api/v2/search/start.json?iata=HKT&checkIn=2021-08-10&checkOut=2021-08-13&adultsCount=2&customerIP=100.168.1.1&childrenCount=1&childAge1=10&lang=ru&currency=USD&waitForResult=0&marker=PasteYourMarkerHere&signature=a475100374414df97a9c6c7d7731b3c6

where signature is md5 of string: "YourToken:YourMarker:adultsCount:checkIn:checkOut:childAge1:childrenCount:currency:customerIP:iata:lang:waitForResult". More information about signatures is available here.
Attention! Signature is case-sensitive.

Sample response

{
   "searchId": "5201179",
   "status": "ok"
}

Request for search result

After receiving the searchId, you need to send a request to get the search results. In the request, you can pass additional sorting and filtering options. The request is sent to http://engine.hotellook.com/api/v2/search/getResult.json.

Please note that you need to create another md5-signature for this request with the following string: "YourToken:YourMarker:limit:offset:roomsCount:searchId:sortAsc:sortBy"

  • searchId – search Id
  • limit – maximum number of hotels, from 0 to infinity, where 0 - no limit. The default is 0
  • offset – to set a number of hotels to skip from 0 to infinity, where 0 - no hotel skipped. The default is 0
  • sortBy – how to sort:
    • popularity – by popularity
    • price – by price
    • name – by name
    • guestScore – by User Rating
    • stars – by the number of stars

Default – popularity

  • sortAsc – how to sort the values
    • 1 – ascending
    • 0 – descending

Default – 1

  • roomsCount – the maximum number of rooms that are returned in each hotel, from 0 to infinity, where 0 - no limit. The default is 0.

Sample request

http://engine.hotellook.com/api/v2/search/getResult.json?searchId=4034914&limit=10&sortBy=price&sortAsc=1&roomsCount=0&offset=0&marker=PasteYourMarkerHere&signature=364c38baee5cf11b382297bfd4338ce6

Sample response

When you are trying to get a search result, at the end of search you get the error "errorCode: 4". This means the results are not yet ready. The search is not interrupted; you should repeat the request later.

{
   "status":"ok",
   "result":[{
      "fullUrl":"http://search.hotellook.com/?language=ru&marker=16886&hotelId=362691",
      "maxPricePerNight":46,
      "maxPrice":138,
      "photoCount":50,
      "guestScore":63,
      "address":"23/8 Soi Hub-Aik, Phuket Road, Muang District",
      "minPriceTotal":40,
      "id":362691,
      "price":13,
      "name":"Rome Place Hotel",
      "url":"/search/?marker=16886&hotelId=362691",
      "popularity":47,
      "location":{
         "lon":98.39146,
         "lat":7.878922
      },
      "stars":3,
      "distance":10.6,
      "amenities":[],
      "rooms":[{
         "bookingURL":"/r/?language=ru&checkIn=2015-06-10¤cy=USD&children=5&host=v2%3A16886&marker=16886&transparent=1&roomId=0&adults=2&locationId=30553&checkOut=2015-06-13&gateId=43&hotelId=362691",
         "options":{
            "available":5,
            "deposit":true,
            "refundable":false,
            "breakfast":false
         },
         "type":"",
         "tax":0,
         "desc":"Double or Twin STANDARD",
         "fullBookingURL":"http://search.hotellook.com/r?language=ru&checkIn=2015-06-10&cy=USD&children=5&host=v2%3A16886&marker=16886&transparent=1&roomId=0&adults=2&locationId=30553&checkOut=2015-06-13&gateId=43&hotelId=362691",
         "agencyName":"Travel.ru",
         "agencyId":"43",
         "total":40,
         "price":13,
         "internalTypeId":"1"
      }],
      "rating":63
}]}

Block "result" contains:

  • fullUrl – the link to the hotel's page with the partner's marker
  • maxPrice – the highest price of the hotel rooms
  • maxPricePerNight – the maximum price per night
  • price – the average price per room
  • minPriceTotal – the minimum cost per stay
  • photoCount – the number of photos of the hotel
  • guestScore – the travelers' rating
  • id – the ID of the hotel in the database
  • name – hotel's name
  • address – the hotel's address
  • distance – the distance from the hotel to the city center
  • amenities – amenities at the hotel (descriptions of values you can find here)
  • location – the hotel's location:
    • lat – latitude of hotel
    • lon – longitude of hotel
  • stars – the number of stars the hotel
  • url – the link to the hotel website

Block "rooms" contains:

  • type, desc – the type of rooms
  • total – the rate for all time
  • price – the daily room rate
  • tax – taxes and fees
  • options – additional services:
    • breakfast - whether breakfast included in the rate or not
    • available - the number of available rooms of this type
    • deposit - payment directly on the site, if it is 0 - then pay at the hotel
    • refundable - "free cancellation"
    • cardRequired - without reservation card, if 0 - you can book without card and then pay at partners
    • smoking - can smoke in the room
    • freeWifi - whether there is free wifi in the room
    • hotelWebsite - proposal leads to the official hotel website
  • bookingURL – the link to the booking website
  • fullBookingURL - complete link to book with filled all data about users (date of check In and check out, number of adults and children, currency and etc.)
  • internalTypeId - grouping by type of rooms
  • agencyId – the id of booking agencies
  • agencyName – the name of the booking agencies
  • rating - the ranking of visitors. The parameters are calculated based on guest rating, which is compiled based on a vote.

You can get photos and other information about the hotel with the help of Hotel Data API. 

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

Queries errors

All input parameters are checked and errors are shown if they are wrong:

  • errorCode: 1 – not all required parameters are filled.
  • errorCode: 2 – at least one of the parameters does not match the format.
  • errorCode: 3 – access denied.
  • errorCode: 4 – the search is not over yet.