Hotels data API

URL request 

All API requests begin like this: http://engine.hotellook.com/api/v2/ 

The authorization is based on affilliate token.

API methods

Hotel search by name or location

Search for a specific location or name places of a hotel (city, island).

Attention! If you send a request without a token, the number of queries will be limited. The values of restrictions are passed in the response header:

  • X-Ratelimit-Interval - limit interval in seconds;
  • X-Ratelimit-Remaining - how many requests left of this limit;
  • X-Ratelimit-Limit - the value limit.

Request parameters

Required parameters are highlighted in bold.

  • query – main parameter, it is set:
    • as a text;
    • by longitude and latitude (also displays the nearest objects).
  • lang – display language. It can take any iso-language code (ru, es, fr, de, ...); if the database doesn’t include a translation for the requested language, it returns the English name of the object. By default, lang="en".
  • lookFor – objects displayed in the results:
    • city;
    • hotel;
    • both (city&hotel).
  • limit – limitation of output results from 1 to 100, default - 10.
  • convertCase – automatically change the keyboard layout (actual for Russian users, for example, when requesting "vjcrdf" will be found "москва"). Values - 1 or 0. Default - 1. 

Sample request

 /api/v2/lookup.json?query=moscow&lang=ru&lookFor=both&limit=1

Sample response

{
    "results": {
    "locations": [
    {
       "cityName": "Москва",
       "fullName": "Москва, Россия",
       "countryCode": "RU",
       "countryName": "Россия",
       "iata": [
            "BKA",
            "DME",
            "SVO",
            "VKO",
            "MOW"
        ],
        "id": "12153",
        "hotelsCount": "930",
       "location": {
        "lat": "55.752222200",
        "lon": "37.615555600"
        },
        "_score": 3.2695
    }
    ],
    "hotels": [
    {
        "label": "Отель Novotel Moscow City",
        "locationName": "Москва, Россия",
        "locationId": "12153",
        "id": "1074388",
        "fullName": "Отель Novotel Moscow City, Москва, Россия",
        "location": {
        "lat": "55.747160",
        "lon": "37.539302"
        }
    }
    ]
    },
  "status": "ok"
}

Response parameters

The block "locations" includes:

  • cityName;
  • fullName – name of city and country;
  • countryCode;
  • countryName;
  • iata – IATA airport code in this city, there may be several;
  • id – location id in the database;
  • hotelsCount – number of hotels in this location;
  • location:
    • lat – latitude of location;
    • lon – longitude of location.
  • score – internal parameter, used for sorting.

The block "hotels" includes:

  • label – name of hotel;
  • locationName – location of hotel;
  • locationId – location id in the database;
  • Id – hotel id in the database;
  • fullName – full name of the hotel and the location of it;
  • location:
    • lat – latitude of hotel;
    • lon – longitude of hotel.

Searching a hotel or location by coordinates

Search for a specific location or hotel (city, island) by coordinates.

Attention! If you send a request without a token, the number of queries will be limited. The values of restrictions are passed in the response header:

  • X-Ratelimit-Interval - limit interval in seconds;
  • X-Ratelimit-Remaining - how many requests left of this limit;
  • X-Ratelimit-Limit - the value limit.

Request parameters

Required parameters are highlighted in bold.

  • query – main parameter, it is set:
    • as a text;
    • by the longitude and latitude (also displays the nearest objects).
  • lang – display language. It can take any iso-language code (ru, es, fr, de, ...) - if the database doesn’t include a translation for the requested language, it returns the English name of the object. By default lang="en".
  • lookFor – objects displayed in the results:
    • city;
    • hotel;
    • both (city&hotel).
  • limit – limitation of output results from 1 to 100, default - 10.
  • convertCase – automatically change the keyboard layout (actual for Russian users, for example, when requesting "vjcrdf" will be found "москва"). Values - 1 or 0. Default - 1. 

Sample request

/api/v2/lookup.json?query=55.0291,82.9059&lang=ru&lookFor=both&limit=1

Sample response

{
    "results": {
    "locations": [
    {
        "id": "12167",
        "type": "City",
        "countryIso": "RU",
        "name": "Новосибирск",
        "state": "",
        "fullname": "Новосибирск, Россия",
        "geo": {
            "lat": "55.028705000",
            "lon": "82.906898000"
        }
    }
    ],
    "hotels": [
    {
        "id": "380923",
        "name": "AZIMUT Отель Сибирь",
        "locationId": "12167",
        "location": {
            "lat": "55.029140",
            "lon": "82.905990"
            }
        }
    ]
    },
    "status": "ok"
}

Response parameters

The block "locations" includes:

  •  id – id of locations in the database.
  • type – type of locations (city, isle).
  • countryIso – country code.
  • name – name of locations.
  • state – code of state.
  • fullname – full name of the location with the name of the country.
  • geo:
    • lat – latitude of location.
    • lon – longitude of location.

The block "hotels" includes:

  • Id – id of hotel in the database.
  • name – name of hotel.
  • locationId – location id in the database.
  • location:
    • lat – latitude of hotel.
    • lon – longitude of hotel.

Displays the cost of living in hotels

The request is used to get the price of hotel rooms from the cache for the period. It doesn't contain information about room availability.

Attention! If you send a request without a token, the number of queries will be limited. The values of restrictions are passed in the response header:

  • X-Ratelimit-Interval - limit interval in seconds;
  • X-Ratelimit-Remaining - how many requests left of this limit;
  • X-Ratelimit-Limit - the value limit. 

Sample request

/api/v2/cache.json?location=Saint-Petersburg&hotelId=277083&checkIn=2017-09-13&checkOut=2017-09-18&currency=rub&limit=1

Request parameters

  • location - location name (IATA code can be used location);
  • checkIn - date of check-in;
  • checkOut - date of check-out;
  • locationId - id of location (can be used instead of the location);
  • hotelId - id of the hotel;
  • hotel - name of the hotel (when entering the name necessarily indicate the location or locationId;
  • adults - number of guests (by default, 2);
  • children - number of children (2 to 18 years);
  • infants - number of infants (0 to 2 years);
  • limit - number of hotels. If this parameter is used in a query without specifying a precise ID or name of the hotel, the following applies:
    • limit = 4 (default) - will return for one hotel each category (Stars);
    • limit = 5 - return two five-stars hotel and one of the other categories;
    • limit = 6 - two 5 and 4-star hotel and the other one;
    • limit = 7 - two 5, 4 and 3-star hotels and one comfortable;
    • limit = 8 - all of two. And so on, with the growth parameters in turn increasing the number of hotels in every star. If the specified star hotels are no more, the issue will begin to fall and hotels 1 0 star by the same rule.
  • customerIp - parameter to specify the user IP if the request is not sent directly, but through a proxy server.

Sample response

{
"location":{
"country":"Russia",
"geo":{
"lon":37.617508,
"lat":55.752041
},
"state":null,
"name":"Moscow"
},
"priceAvg":60897.74,
"pricePercentile":{
"3":28863.56,
"10":28863.56,
"35":47805.27,
"50":59531.09,
"75":65435,
"99":120128.17
},
"hotelName":"Mercure Arbat Moscow",
"stars":4,
"locationId":12153,
"hotelId":333561,
"priceFrom":28863.56
}

Response parameters

The response contains:

  • stars - number of the hotel's stars;
  • locationId - location id of this hotel;
  • priceFrom - minimum price per stay in a hotel room for the period;
  • priceAvg - average price per stay in a hotel room for the period;
  • pricePercentile - segmentation price for proportions (e.g., record type "50": 59531.09 means that 50% of the price is in the range of 59531.09 to rub);
  • hotelName - name of hotel;
  • location - information about the location of the hotel:
    • geo - coordinates of the hotel;
    • name - name of location (city);
    • state - state in which the city is located;
    • country - a country of hotel.
  • hotelId - id of hotel.

List of hotels in the archive

Use the link http://yasen.hotellook.com/tp/v1/hotels?language=en to download a list of all hotels for the specified locale.

The language parameter can take the values:

  • ru (Russian);
  • en (English);
  • th (Thai);
  • de (German);
  • es (Spanish);
  • fr (French);
  • it (Italian);
  • pl (Polish).

The file with a list of hotels includes the following data:

  • id - unique id of the hotel;
  • name - name of the hotel;
  • location_name - name of the place location of the hotel;
  • location_id - a unique id location of the hotel;
  • location_iata - IATA code for the location of the hotel;
  • country_name - name of the country in which the hotel is located;
  • photos_count - number of photos of the hotel in the database.

The hotels file is updated once a week in the morning (GMT) on Saturday.

Note! To download the list of hotels you do not need access to the search hotels API.

Hotels Selections

The request recovers the list of specific hotels according to the ID of a location. A collection is formed according to the specified period. If the period is not specified, a collection shall be formed from the hotels found for the last three days.

Example of request

http://yasen.hotellook.com/tp/public/widget_location_dump.json?currency=rub&language=ru&limit=5&id=12209&type=popularity&check_in=2017-02-02&check_out=2017-02-17&token=PasteYourTokenHere

The request parameters

  • check_in — date of check-in;
  • check_out — date of check-out;
  • currency — currency of response;
  • language — language of reaponse (pt, en, fr, de, id, it, pl, es, th, ru);
  • limit — limitation of output results from 1 to 100, default - 10;
  • type — type of hotels from request /tp/public/available_selections.json;
  • id — id of the city.

Example of response

{
  "popularity":[
  {
    "hotel_id":713859,
    "distance":6.68,
    "name":"President Hotel",
    "stars":4,
    "rating":87,
    "property_type":"hotel",
    "hotel_type":[
        "Solo Hotel"
    ],
    "last_price_info":{
        "price":39707,
        "old_price":42761,
        "discount":7,
        "insertion_time":1485464441,
        "nights":15,
        "search_params":{
            "adults":2,
            "children":{},
            "checkIn":"2017-02-02",
            "checkOut":"2017-02-17"
        },
        "price_pn":2647,
        "old_price_pn":2851
    },
    "has_wifi":true
    }
]}

The response parameters

  • hotel_id – unique hotels’ ID;
  • distance – distance from the city’s center;
  • name – hotel’s name;
  • stars – number of stars;
  • rating – hotel’s rating, assigned by its visitors;
  • property_type – type of a hotel:
  • hotel_type – description of a hotel’s type;
  • last_price_info – information about the last found price of a hotel (if any)
    • price – price of accommodation during the whole period with a discount;
    • old_price - price of accommodation without a discount;
    • discount – amount of a discount;
    • insertion_time – time, when the collection was found;
    • nights – number of nights.
  • search_params – search parameters
  • price_pn – price of a night in a hotel room with a discount;
  • old_price_pn - price of a night in a hotel room without a discount;
  • has_wifi – availability of Wi-Fi.

The types of hotel collections

The request recovers the list of all available separate collections. This type is used to search for hotels with a discount.

Example of request

http://yasen.hotellook.com/tp/public/available_selections.json?id=12209&token=PasteYourTokenHere

Example of response

[
"center",
"tophotels",
"highprice",
"3-stars",
"4-stars",
"5-stars",
"restaurant",
"pets",
"pool",
"cheaphotel_ufa",
"luxury_ufa",
"price",
"rating",
"distance",
"popularity",
"2stars",
"3stars",
"4stars",
"5stars"
]

The response parameters

  • center – hotels, located in the center of a city;
  • tophotels – best hotels:
  • highprice – most expensive hotels;
  • 3-stars, 4-stars, 5-stars – automatic searching of the hotels, having 3, 4 or 5 stars;
  • restaurant – availability of the own restaurant;
  • pets – opportunity to live with the pets;
  • pool – availability of the own pool;
  • cheaphotel – cheapest hotels
  • luxury – luxury hotels
  • price – manually formed collections by the price;
  • rating – hotels with the highest rating
  • distance – distance from an airport
  • popularity – type of a hotel
  • 2stars, 3stars, 4stars, 5stars - manually formed collections with the corresponding number of stars.

Statistical data

Requests as a result of which the partner receives information about the countries, cities and hotels.

Attention! The default number of requests is limited to 60 per minute. If you need to process more requests, send a letter to support@travelpayouts.com.

Request "Country"

Request parameters

  • token - your affiliate token.

Sample request

http://engine.hotellook.com/api/v2/static/countries.json?token=PasteYourTokenHere

Sample response

[{
   "id": "9",
   "code": "DZ",
   "name": {
      "EN": [{
         "isVariation": "0",
         "name": "Algeria"
      }],
      "RU": [{
         "isVariation": "0",
         "name": "\u0410\u043b\u0436\u0438\u0440"
      }]
   }
},
{
   "id": "10",
   "code": "AO",
   "name": {
      "EN": [{
         "isVariation": "0",
         "name": "Angola"
      }],
      "RU": [{
         "isVariation": "0",
         "name": "\u0410\u043d\u0433\u043e\u043b\u0430"
      }]
   }
}]

Response parameters

The response contains: 

  • Id – id of country.
  • code – code of country.
  • The block EN:
    • isVariation – primary or secondary title. 1 - secondary, 0 - primary.
    • name – country name in English.
  • The block RU:
    • isVariation – primary or secondary title.
    • name – country name in Russian.

Request "Citys"

Request parameters

  • token - your affiliate token.

Sample request

http://engine.hotellook.com/api/v2/static/locations.json?token=PasteYourTokenHere

Sample response

[{
   "id": "373",
   "code": "",
   "countryId": "77",
   "latitude": "15.501950000",
   "longitude": "73.910090000",
   "name": {
      "EN": [{
         "isVariation": "0",
         "name": "Goa"
      }],
      "RU": [{
         "isVariation": "0",
         "name": "\u0413\u043e\u0430"
      }]
   }
}]

Response parameters

The response contains:

  • Id – id of city.
  • code – iata-code of city.
  • countryId – id of country.
  • latitude – latitude of city.
  • longitude – longitude of city.
  • The block DE:
    • isVariation - primary or secondary title. 1 - secondary, 0 - primary.
    • name – city name in German.
  • The block EN:
    • isVariation - primary or secondary title.
    • name – city name in English.
  •  The block RU:
    • isVariation – primary or secondary title.
    • name – city name in Russian.

Request "Amenities"

Request parameters

  • token - your affiliate token.

Sample request

http://engine.hotellook.com/api/v2/static/amenities.json?token=PasteYourTokenHere

Sample response

[{
   "id": "2",
   "name": "Hairdryer",
   "groupName": "Room"
},
{
   "id": "3",
   "name": "Safe",
   "groupName": "Room"
},
{
   "id": "4",
   "name": "TV",
   "groupName": "Room"
}]

Response parameters

The response contains:

  • Id – id of amenities in the database.
  • name – name of amenities.
  • groupName - location of amenities.

Request 'Hotels list'

Request parameters

  • locationId – id of location.
  • token - your affiliate token.

Sample request

http://engine.hotellook.com/api/v2/static/hotels.json?locationId=895&token=PasteYourTokenHere

Sample response

{
"hotels":[{
   "photos":[
      {
         "width":320,
         "url":"http:\/\/photo.hotellook.com\/image_v2\/limit\/h678963_0\/320\/240.auto",
         "height":240
      }
   ],
   "checkIn":null,
   "cntSuites":null,
   "distance":9.7,
   "address":{
      "en":"6th Mile Post gonnoruwa road bandagiriya,"
   },
   "cntRooms":null,
   "photoCount":6,
   "name":{
      "zh":"\u73ed\u9054\u57fa\u91cc\u9109\u6751\u98ef\u5e97",
      "th":"\u0e1a\u0e31\u0e19\u0e14\u0e32\u0e01\u0e34\u0e23\u0e35 \u0e27\u0e34\u0e25\u0e40\u0e25\u0e08",
      "en":"Bandagiri Village"
   },
   "cityId":895,
   "checkOut":null,
   "cntFloors":null,
   "rating":0,
   "yearRenovated":null,
   "stars":0,
   "yearOpened":null,
   "propertyType":0,
   "facilities":[
      131,
      56,
      50,
      14,
      40,
      13,
      11
   ],
   "link":"\/lk\/weerawila-895\/bandagiri_village-678963.html",
   "popularity":600,
   "location":{
      "lat":6.23485,
      "lon":81.14245
   },
   "shortFacilities":[
      "air conditioning",
      "parking",
      "laundry",
      "wi-fi in public areas",
      "fitness"
   ],
   "pricefrom":70,
   "photosByRoomType":{
      "1":10,
      "25":10
   },
   "id":678963,
   "poi_distance":{
      "70650":52747,
      "71334":10762,
      "70643":94961,
      "70649":94654
   }
   }],
"gen_timestamp":1480288607.1637635231,
"pois":[
   {
   "confirmed":true,
   "rating":0,
   "location":{
      "lat":5.990833,
      "lon":80.733333
   },
   "name":"Dickwella Airport",
   "geom":{
      "type":"Point",
      "coordinates":[
         80.733333,
         5.990833
      ]
   },
   "category":"airport",
   "id":70650
   }
   ]
}

Response parameters

The response contains:

  • id – id of hotel in database hotellook.
  • cityId – id of city.
  • stars – number of stars.
  • pricefrom – average minimum cost of the period, in USD
  • rating – rating visitors.
  • popularity – popularity of hotel.
  • propertyType – type of hotel (hostel, motel, villa, etc.).
  • checkOut – check out time.
  • checkIn – check in time.
  • distance – distance to the center.
  • photoCount – number of photos.
  • photos
    • url – link to the photo.
    • width – width of photo.
    • height – height of photo.
  • facilities – id amenities in the database.
  • shortFacilities – availability of the amenities from the list: 'restaurant', 'parking', 'non-smoking', 'pets', 'tv', 'laundry', 'conditioning', 'internet', 'pool', 'fitness'.
  • photosByRoomType - photos of rooms types. The key - id of the room type, the value - number of photos.
  • location
    • lat – latitude of hotel.
    • lon – longitude of hotel.
  • name – hotel name.
  • address – hotel address.
  • link – link to this page of hotel. 
  • poi_distance - distance to the important places (shown in the list of places id array pois and distance in meters).
  • pois - an array of the important places:
    • confirmed - confirmed place;
    • rating - place ranking;
    • location - location;
    • name - the name of the place;
    • geom - coordinates of the point;
    • category - the place category;
    • id - id of place in the base.

Request "Types of rooms"

Request parameters

  • language - language of reaponse (pt, en, fr, de, id, it, pl, es, th, ru).
  • token - your affiliate token.

Sample request

http://engine.hotellook.com/api/v2/static/roomTypes.json?language=en&token=PasteYourTokenHere

Sample response

{
   "8":"Apartment",
   "18":"Bungalow",
   "15":"Business",
   "73":"Business apartment",
   "86":"Business deluxe",
   ...
}

Request "Types of hotels"

Request parameters

  • language - language of reaponse (pt, en, fr, de, id, it, pl, es, th, ru).
  • token - your affiliate token.

Sample request

http://engine.hotellook.com/api/v2/static/hotelTypes.json?language=en&token=PasteYourTokenHere

Sample response

{
   "1":"Hotel",
   "6":"Guest House",
   "4":"Apartment \/ Condominium",
   "3":"Bed & Breakfast",
   "7":"Hostel",
   "8":"Resort",
   "5":"Motel",
   "10":"Vacation Rental",
   "2":"Apartment Hotel",
   "12":"Villa",
   "11":"Lodge",
   "9":"Agriturismo \/ Farm Stay",
   "0":"Other"
}

Request "Hotel photos"

Request parameters

  • h+Id – h + hotel's id.
  • photoId – number of the hotel's photo.
  • photosize – size of the photo (width/height).

Sample request

https://photo.hotellook.com/image_v2/limit/hId_photoId/photosize.jpg.

Examples of links to the hotel's photos with Id 503387 size 48*48 and 640*480:

https://photo.hotellook.com/image_v2/limit/h503387_1/48.jpg

https://photo.hotellook.com/image_v2/limit/h503387_1/640/480.jpg

Another way to get the photo of the hotel - use the link type:

https://photo.hotellook.com/image_v2/limit/h418520_1/800/520.auto

where

  • 418520 - hotel id;
  • 1 - photo number;
  • 800 - width;
  • 520 - height;
  • .auto - means that our system detects whether a user’s browser can accept the Webp image format. If yes, the server will send the image in Webp format (smaller size). If no, the image will be in JPEG format.

Request "Hotel's room photos (in a sprite)"

To get a sprite with photos of rooms, use code like:

https://photo.hotellook.com/rooms/sprite/hhotel-id_group-id/first_width/photos_count-1/rest_photos_width.auto

Request Options

  • h + hotel-Id - letter h + Hotel identifier (from static/hotels.json).
  • group-id - ID room type (from static/hotels.json and internalTypeId of the search for an answer).
  • first_width - width of the first photo in the sprite.
  • photos_count-1 - number of photos of the room type minus one (from the static/hotels.json). For example, if the answer is that photographs of this type have four pieces, it indicates three instead of this parameter.
  • rest_photos_width - width of the rest of the photos in the sprite.
  • auto - our system checks whether a user's browser can accommodate the WebP image format. If yes, the server will provide a WebP image format. If not, the image will be in JPEG format.

Sample request

https://photo.hotellook.com/rooms/sprite/h4_1/100/3/50.auto

https://photo.hotellook.com/rooms/sprite/h4_12/100/3/50.auto

To get a sprite with rectangular photographs, along with the need to specify the width of the height of the photos:

https://photo.hotellook.com/rooms/sprite/h4_12/100x50/3/50x25.auto

To get a picture of the room, given the size, use code like:

https://photo.hotellook.com/rooms/crop/h<hotel_id>_<group_id>_<photo_idx>/<width>/<height>.auto

This photo will be scaled and cropped to the specified size.

To get a photo that is no longer a given size or type, use the code:

https://photo.hotellook.com/rooms/limit/h<hotel_id>_<group_id>_<photo_idx>/<width>/<height>.auto

Parameters similar to those described in the request above, except for photo_idx - an index image in the list (first index pictures - 0).

https://photo.hotellook.com/rooms/limit/h4_12_1/200/200.auto

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 is denied;
  • errorCode 4 – search is not over yet

Was this article helpful?

Have more questions? Submit a request