Location Request

These operations retrieve the lists of locations (countries, destinations, and zones) in a JSON or XML response.

The destination tree divides the destinations into three parts (Destination, Zone and Group of Zones), which limits the area covered by each one:

  • Destination 

This is the main code in our system and covers the largest area. Searching with the destination code retrieves all the results available. 

Please note that we do not use IATA codes; we have our own destination codes. It is very important to understand that our 'destination' will not always only correspond with a unique city, but usually with the main city and the area surrounding the city. 

For example, the destination code NYC in the US, corresponds with the whole New York Area, so it is not limited to the city of New York, but also covers the surrounding areas, such as New Jersey and The Hamptons. 

Another example is BCN in Spain, which corresponds with the entire Barcelona Province; so it searches hotels located in the city of Barcelona, but also in other cities within the Province of Barcelona, such us Hospitalet de Llobregat, Terrassa and Sabadell.

So when you search for availability using the destination code, you will receive results that may be located far from the main city for which you are actually searching. 

It is very important to check the locations that the search retrieves to avoid booking hotels in a different location than the one requested by your customers. 

  • Zone 

This is the most restrictive code in our system. We have divided our destinations into different areas so you can limit the number of results returned. 

In some cases, these zones correspond with neighborhoods within a city (like Brooklyn or Soho/Tribeca/Chinatown in the NYC destination code). 

However, in other cases they could correspond to different cities or areas in the area covered by the destination code (for example the Granollers Area, Vilafranca and Cerdanyola del Valles in the BCN destination, or the Kissimmee Area or Sandford in MCO, the Orlando area destination). 

  • Group of Zones 

We have also grouped some zones under the same code, which allows you to expand your search to a larger area within the destination. 

These group zones may correspond with a city in the destination (e.g., Group Zone BARCEBCN9 of BCN corresponds with Barcelona City), or with a group of similar zones (e.g., Group Zone UK185 in the LON destination, London UK, corresponds with London Airports), or an area in the destination (e.g., Group Zone USA140NJ of NYC corresponds with the New Jersey Area).

 

Depending on the level of the search filter used, you will receive fewer results from the most restrictive area (Zone), and more from the least restrictive area (Destination).  

For example, if you search by destination LON, you will receive results reflecting all the hotels in the London Area. If you request Group Zone UK185, you will receive results from all the London Airport zones. However, if you search for Zone 10 in the destination LON, you will only receive results from the Heathrow Airport zone.

NOTE: This search structure is only available in our XML2 version of the API; in our BookingAPI, we recommend searching by hotel code (which allows you to create your own destination tree). Searching by Destination or Destination/Zone is activated On Demand in the BookingAPI.

There are two main operations:

  • /locations/countries

It will return the list of available countries.

Request Parameters

Parameter Type Description
fields String List of fields you want to receive in the response. If nothing is specified the countryCode will be returned. Values: isoCode, description, all
codes String

Filter for a specific country of list of countries.

lastUpdateTime String

Specifying this parameter will limit the results to those modified or added after the date specified. The allowed format is YYYY-MM-DD

language String Language Code in which you want the descriptions to be returned. If it is not indicated English is the default language.
from String Number of the initial record to receive, if nothing is indicated 1 is the default value.
to String Number of the final record to receive, if nothing is indicated 100 is the default value.
useSecondaryLanguage String "True" if you want to receive the descriptions in English if the description is not available in the language requested.
"False" (default value) if you dont want to receive the description in English if the language requested is not available. 

GET Example

https://api.test.hotelbeds.com/hotel-content-api/1.0/locations/countries?fields=isoCode%2Cdescription&countryIds=US&language=ENG&from=1&to=100
https://api.test.hotelbeds.com/hotel-content-api/1.0/locations/countries?fields=all&language=ITA&from=125&to=250
https://api.test.hotelbeds.com/hotel-content-api/1.0/locations/countries?lastUpdateTime=2015-09-10&fields=All&language=ENG

 

  • /locations/destinations

It will return the list of available destinations, zones and grouping zones. 

Request Parameters

Parameter Type Description
fields String List of fields you want to receive in the response. If nothing is specified the hotelCode will be returned. Values: countryCode, isoCode, name, zones, groupZones, all
codes String

Filter to limit the results for an specific destination or list of destinations.

countryCodes String

Filter for a specific country of list of countries.

lastUpdateTime String

Specifying this parameter will limit the results to those modified or added after the date specified. The allowed format is YYYY-MM-DD

language String Language Code in which you want the descriptions to be returned. If not otherwise indicated, English is the default language.
from String Number of the initial record to receive, if nothing is indicated 1 is the default value.
to String Number of the final record to receive, if nothing is indicated 100 is the default value.
useSecondaryLanguage String "True" if you want to receive the descriptions in English if the description is not available in the language requested.
"False" (default value) if you dont want to receive the description in English if the language requested is not available. 

GET Example

https://api.test.hotelbeds.com/hotel-content-api/1.0/locations/destinations?fields=name%2CdestinationName%2Ccountry&countryId=US&language=ENG&from=1&to=100
https://api.test.hotelbeds.com/hotel-content-api/1.0/locations/destinations?fields=all&language=ITA&from=125&to=250
https://api.test.hotelbeds.com/hotel-content-api/1.0/locations/destinations?lastUpdateTime=2015-09-10&destinationIds=PAR&language=ENG&from=1000&to=2000

Docs Navigation