accommodations

Endpoints and sections specific to the accommodations travel vertical: hotels, apartments, etc.

Get a property's availability

This endpoint returns detailed product availability, price and charges of the accommodation matching a given search criteria. By default, only product availability and price is returned. To receive extended information use the extras parameter. Is is mandatory to pass the input parameters: accommodation, booker, checkin, checkout and guest.

SecurityHTTP: BearerAuth
Request
header Parameters
X-Affiliate-Id
required
integer

Affiliate identifier

Request Body schema: application/json
accommodation
required
integer >= 1

A signed integer number that uniquely identifies an accommodation property. The full list can be obtained by calling accommodations/details.

required
object

The booker's information.

checkin
required
string <date>

The checkin date. Must be within 500 days in the future and in the format yyyy-mm-dd.

checkout
required
string <date>

The checkout date. Must be later than {checkin}. Must be between 1 and 90 days after {checkin}. Must be within 500 days in the future and in the format yyyy-mm-dd.

currency
string^[A-Z]{3}$

A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.

extras
Array of strings

Input parameter to request for additional information about this product.

Items Value: "extra_charges"
required
object

The guest details for the request.

object

Payment input information to filter results.

products
Array of strings
post
/accommodations/availability
Request samples
application/json
{
"accommodation": 10004,
"booker": {
"country": "nl",
"platform": "desktop"
},
"checkin": "!START_DATE!",
"checkout": "!END_DATE!",
"extras": [
"extra_charges"
],
"guests": {
"number_of_adults": 2,
"number_of_rooms": 1
}
}
Responses

200

Successful response.

Response Schema: application/json
request_id
string

Uniquely identifies the request. Please provide this identifier when contacting support.

object
Response samples
application/json
{
"request_id": "01fr9ez700exycb98w90w5r9sh",
"data": {
"id": 10004,
"currency": "EUR",
"deep_link_url": "booking://hotel/10004?affiliate_id=!AFFILIATE_ID!&checkin=!START_DATE!&checkout=!END_DATE!",


"url": "https://www.booking.com/hotel/nl/toren.html?aid=!AFFILIATE_ID!&checkin=!START_DATE!&checkout=!END_DATE!&no_rooms=1&group_adults=2"
}
}

List properties' availabilities

This endpoint returns detailed product availability, price and charges of a list of accommodations. By default, only product availability and price is returned. To receive extended information use the extras parameter. Is is mandatory to pass the input parameters: accommodations, booker, checkin, checkout and guests.

SecurityHTTP: BearerAuth
Request
header Parameters
X-Affiliate-Id
required
integer

Affiliate identifier

Request Body schema: application/json
accommodations
required
Array of integers <= 50 items
required
object

The booker's information.

checkin
required
string <date>

The checkin date. Must be within 500 days in the future and in the format yyyy-mm-dd.

checkout
required
string <date>

The checkout date. Must be later than {checkin}. Must be between 1 and 90 days after {checkin}. Must be within 500 days in the future and in the format yyyy-mm-dd.

currency
string^[A-Z]{3}$

A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.

extras
Array of strings

Input parameter to request for additional information about this product.

Items Value: "extra_charges"
object

The filters to apply in this availability request.

required
object

The guest details for the request.

post
/accommodations/bulk-availability
Request samples
application/json
{
"accommodations": [
10004
],
"booker": {
"country": "nl",
"platform": "desktop"
},
"checkin": "!START_DATE!",
"checkout": "!END_DATE!",
"extras": [
"extra_charges"
],
"filters": {
"meal_plan": "breakfast_included",
"cancellation_type": "free_cancellation"
},
"guests": {
"number_of_adults": 2,
"number_of_rooms": 1
}
}
Responses

200

Successful response.

Response Schema: application/json
request_id
string

Uniquely identifies the request. Please provide this identifier when contacting support.

Array of objects
Response samples
application/json
{
"request_id": "01fr9ez700exycb98w90w5r9sh",
"data": [

]
}

List accommodation chains

A chain-branded accommodation is one that is associated with a larger corporation group, and as such, operates under a recognized brand. The information returned can be used to filter accommodation searches based on particular chains or brands. An example of a chain is "Radisson Hotel Group". To get the full list call the endpoint passing an empty body. The codes returned are what is used as input and output for other endpoints.

SecurityHTTP: BearerAuth
Request
header Parameters
X-Affiliate-Id
required
integer

Affiliate identifier

post
/accommodations/chains
Responses

200

Successful response.

Response Schema: application/json
request_id
string

Uniquely identifies the request. Please provide this identifier when contacting support.

Array of objects
Response samples
application/json
{
"request_id": "01fr9ez700exycb98w90w5r9sh",
"data": [

"..."
]
}

List accommodation constants

This endpoint enumerates the internal codes and names, in the selected languages, for relevant accommodation specific types. These accommodation specific types include the list of facilities that may be available at a property like "Elevator" or "Swimmingpool Outdoor". For example, the following parameters will return the full list in English (US) and French: {"languages":"en-us","fr"}. To get the full list call the endpoint passing an empty body. The codes returned are what is used as input and output for other endpoints in the accommodations namespace.

SecurityHTTP: BearerAuth
Request
header Parameters
X-Affiliate-Id
required
integer

Affiliate identifier

Request Body schema: application/json
constants
Array of strings

Allows to filter the results only for specific sections.

Items Enum: "accommodation_facilities" "accommodation_themes" "accommodation_types" "bed_types" "charge_types" "facility_types" "review_scores" "room_facilities" "room_types"
languages
Array of strings
Default: ["en-gb"]
post
/accommodations/constants
Request samples
application/json
{
"languages": [
"en-gb",
"zh-cn"
]
}
Responses

200

Successful response.

Response Schema: application/json
request_id
string

Uniquely identifies the request. Please provide this identifier when contacting support.

object
Response samples
application/json
{
"request_id": "01fr9ez700exycb98w90w5r9sh",
"data": {









}
}

List accommodation details

This endpoint returns detailed information on all accommodation properties matching a given search criteria. By default, only basic information is returned. To receive extended information use the extras parameter. Is is mandatory to pass one of the input parameters: accommodations, airport, city, country or region.

SecurityHTTP: BearerAuth
Request
header Parameters
X-Affiliate-Id
required
integer

Affiliate identifier

Request Body schema: application/json
accommodation_facilities
Array of integers
accommodation_types
Array of integers
accommodations
Array of integers <= 100 items
airport
string^[A-Z]{3}$

A three-letter code that uniquely identifies an airport as defined by the International Air Transport Association (IATA). The full list can be obtained by calling common/locations/airports.

beta_features
Array of strings

Input parameter to request the beta features to be used. It should be passed as a JSON array with one or more items.

Items Value: "beta_accommodations_details_use_facilities_301"
brands
Array of integers
city
integer

A signed integer number that uniquely identifies a city. The full list can be obtained by calling common/locations/cities.

country
string^[a-z]{2}$

A two-letter code that uniquely identifies a country. This code is defined by the ISO 3166-1 alpha-2 standard (ISO2) as described here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2. The full list can be obtained by calling common/locations/countries.

extras
Array of strings

Input parameter to request for additional information about the accommodation property. It should be passed as a JSON array with one or more items.

Items Enum: "description" "facilities" "payment" "photos" "policies" "rooms"
languages
Array of strings
page
string

Pagination token used to retrieve the next page of results. Obtained from next_page.

object

Payment input information to filter results.

region
integer >= 1

A signed integer number that uniquely identifies a geographical region. Regions usually define official administrative areas within a country, but may also include multiple countries and in some cases un-official but popular designations for geographical areas. An example of a region that crosses multiple countries is the Alps in Europe. The full list can be obtained by calling common/locations/regions.

rows
integer multiple of 10 [ 10 .. 1000 ]
Default: 100

The maximum number of results to return.

post
/accommodations/details
Request samples
application/json
{
"accommodations": [
10004
],
"extras": [
"description",
"facilities",
"payment",
"photos",
"policies",
"rooms"
],
"languages": [
"en-gb",
"zh-cn"
]
}
Responses

200

Successful response.

Response Schema: application/json
request_id
string

Uniquely identifies the request. Please provide this identifier when contacting support.

Array of objects
next_page
string or null

Indicates that more results are available. Use this pagination token to retrieve the next page of results (via parameter page).

Response samples
application/json
{
"request_id": "01fr9ez700exycb98w90w5r9sh",
"data": [

]
}

List new and updated accommodation

This endpoint returns all accommodations that have closed, opened or changed relevant content since the given timestamp up to a limit of around 5000 ids. It is recommended to cache accommodation information locally in order to speed up responses. Use this endpoint in combination with accommodations/details to maintain the local cache up-to-date. The number of accommodation ids returned may vary since some may be removed due to blacklisting, while all changes from the last second will be included even if already beyond the 5000 ids threshold. Multiple changes to the same accommodation are grouped by intervals of 30 minutes in order to reduce the number of records.

SecurityHTTP: BearerAuth
Request
header Parameters
X-Affiliate-Id
required
integer

Affiliate identifier

Request Body schema: application/json
last_change
required
string <date-time>

The timestamp in ISO-8601 format from which changes to accommodations are returned (inclusive). Only UTC time zone is supported. We support changes for last 24 hours. Format: YYYY-MM-DDTHH:mm:ss+00:00

post
/accommodations/details/changes
Request samples
application/json
{
"last_change": "!START_DATE!T12:00:00+00:00"
}
Responses

200

Successful response.

Response Schema: application/json
request_id
string

Uniquely identifies the request. Please provide this identifier when contacting support.

object
Response samples
application/json
{
"request_id": "01fr9ez700exycb98w90w5r9sh",
"data": {

"from": "!START_DATE!T12:00:00+00:00",
"next": "!START_DATE!T12:24:42+00:00",
"total_changes": 5125
}
}

List accommodation reviews

This endpoint returns reviews for the specified accommodations. The reviews returned can be filtered. This endpoint implements pagination of the results. By specifying rows parameter, you can limit reviews for each accommodation.

SecurityHTTP: BearerAuth
Request
header Parameters
X-Affiliate-Id
required
integer

Affiliate identifier

Request Body schema: application/json
accommodations
required
Array of integers <= 100 items
languages
Array of strings

Limits reviews to those written in this language.

last_change
string <date>

Limits the reviews to those changed after the given date. Format: YYYY-MM-DD.

page
string

Pagination token used to retrieve the next page of results. Obtained from next_page.

object
rows
integer multiple of 10 [ 10 .. 100 ]
Default: 100

The maximum number of results to return.

object
post
/accommodations/reviews
Request samples
application/json
{
"accommodations": [
10004
],
"languages": [
"en-gb"
]
}
Responses

200

Successful response.

Response Schema: application/json
request_id
string

Uniquely identifies the request. Please provide this identifier when contacting support.

Array of objects
next_page
string or null

Indicates that more results are available. Use this pagination token to retrieve the next page of results (via parameter page).

Response samples
application/json
{
"request_id": "01fr9ez700exycb98w90w5r9sh",
"data": [

],
"next_page": "..."
}

List accommodation review scores

This endpoint returns score distribution and score breakdown for the specified accommodations. The scores information can be filtered by reviewer parameters and languages.

SecurityHTTP: BearerAuth
Request
header Parameters
X-Affiliate-Id
required
integer

Affiliate identifier

Request Body schema: application/json
accommodations
required
Array of integers <= 100 items
languages
Array of strings

Limits reviews to those written in this language.

object
post
/accommodations/reviews/scores
Request samples
application/json
{
"accommodations": [
10004
],
"languages": [
"en-gb"
]
}
Responses

200

Successful response.

Response Schema: application/json
request_id
string

Uniquely identifies the request. Please provide this identifier when contacting support.

Array of objects
Response samples
application/json
{
"request_id": "01fr9ez700exycb98w90w5r9sh",
"data": [

]
}

List available accommodation

This endpoint returns the cheapest available product for each hotel matching the search criteria.

SecurityHTTP: BearerAuth
Request
header Parameters
X-Affiliate-Id
required
integer

Affiliate identifier

Request Body schema: application/json
24_hour_reception
boolean

Filter the result based if the front desk reception is available 24/7. When specified true, the result will filter the products where front desk is available 24/7.

accommodation_facilities
Array of integers
accommodation_types
Array of integers
accommodations
Array of integers <= 100 items
airport
string^[A-Z]{3}$

A three-letter code that uniquely identifies an airport as defined by the International Air Transport Association (IATA). The full list can be obtained by calling common/locations/airports.

required
object

The booker's information.

brands
Array of integers
cancellation_type
string

Filters the result for the cancellation type specified. Possible values are free_cancellation & non_refundable. If cancellation_type is free_cancellation, the result will contain all the products with free_cancellation.

Enum: "free_cancellation" "non_refundable"
checkin
required
string <date>

The checkin date. Must be within 500 days in the future and in the format yyyy-mm-dd.

checkout
required
string <date>

The checkout date. Must be later than {checkin}. Must be between 1 and 90 days after {checkin}. Must be within 500 days in the future and in the format yyyy-mm-dd.

city
integer

A signed integer number that uniquely identifies a city. The full list can be obtained by calling common/locations/cities.

object

Limit the result list to the specified coordinates.

country
string^[a-z]{2}$

A two-letter code that uniquely identifies a country. This code is defined by the ISO 3166-1 alpha-2 standard (ISO2) as described here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2. The full list can be obtained by calling common/locations/countries.

currency
string^[A-Z]{3}$

A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.

district
integer >= 1

A signed integer number that uniquely identifies a district. Typically, districts define known areas within a city. The full list can be obtained by calling common/locations/districts.

dormitories
string
Default: "include"

This parameter specifies if the results should include dormitory beds or rooms. The default behaviour will include the dormitory beds or rooms with other results. When this flag is set to 'only', the response will only include dormitory beds or rooms. When this flag is set to 'exclude', the response will exclude dormitory beds or rooms. When this flag is set to 'include', the response will include dormitory beds or rooms with other results.

Enum: "include" "exclude" "only"
extras
Array of strings

Input parameter to request for additional information about the products.

Items Enum: "extra_charges" "products"
required
object

The guest details for the request.

landmark
integer >= 1

A signed integer number that uniquely identifies a relevant geographical landmark, like a monument or a natural attraction. The full list can be obtained by calling common/locations/landmarks.

meal_plan
string

Filter the result based on the selected meal plan. Example: When specified breakfast_included, it will show the product with free breakfast.

Enum: "all_inclusive" "breakfast_included" "full_board" "half_board"
page
string

Pagination token used to retrieve the next page of results. Obtained from next_page.

object

The payment filter for the request

object

If specified, will return only results where the price per night falls in the specified range (inclusive). This filter requires that a currency is passed

object

The rating filter for the request

region
integer >= 1

A signed integer number that uniquely identifies a geographical region. Regions usually define official administrative areas within a country, but may also include multiple countries and in some cases un-official but popular designations for geographical areas. An example of a region that crosses multiple countries is the Alps in Europe. The full list can be obtained by calling common/locations/regions.

room_facilities
Array of integers
rows
integer multiple of 10 [ 10 .. 100 ]
Default: 100

The maximum number of results to return.

object

The sorting parameters for the response

travel_proud
boolean

Filter the result based on if the property is LGBTQ+ friendly. When specified true, the result will filter and return only the accommodations that are Proud Certified.

post
/accommodations/search
Request samples
application/json
{
"booker": {
"country": "nl",
"platform": "desktop"
},
"checkin": "!START_DATE!",
"checkout": "!END_DATE!",
"city": -2140479,
"extras": [
"extra_charges",
"products"
],
"guests": {
"number_of_adults": 2,
"number_of_rooms": 1
}
}
Responses

200

Successful response.

Response Schema: application/json
request_id
string

Uniquely identifies the request. Please provide this identifier when contacting support.

Array of objects
next_page
string or null

Indicates that more results are available. Use this pagination token to retrieve the next page of results (via parameter page).

Response samples
application/json
{
"request_id": "01fr9ez700exycb98w90w5r9sh",
"data": [

"..."
],
"next_page": "..."
}