Locations operations

The location operations return the information of the different levels on our destination tree (countries, destinations, and zones) in lists in XML or JSON format responses.

Countries

This is the higher level available in our destination tree. We do not allow search by country, but it's included for organizational reasons (to group destinations) and because the country codes returned are used in other levels of APItude (for example to define the sourceMarket in Availability operation of HotelBookingAPI.

Destinations

This is the main code in our system and covers the largest area of search. 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.

Zones

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).

NOTE: In HotelBookingAPI, we recommend searching by hotel code and associate the hotel code lists for different destinations in your own destination tree. Searching by Destination or Destination/Zone in the BookingAPI is disabled by default and has to be requested on demand to our support team.

There are two main operations:

/locations/countries

Return the list of available countries.

Request

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.

Request examples

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

 

Response

Response parameters

Node/Attribute Type Max Size KEY Description
auditData Element Occurrences 1 No Key Relevant internal information
auditData/@processTime String Occurrences 1 No Key Server process time in milliseconds
auditData/@timestamp String Occurrences 1 No Key Date/time when the requests has been processed. Always returned at Spanish time
auditData/@requestHost String Occurrences 1 No Key IP From where the petition was sent to the system
auditData/@serverId String Occurrences 1 No Key Server code or ID(Internal use)
auditData/@environment String Occurrences 1 No Key Environment where the request has been sent and processed
auditData/@release String Occurrences 1 No Key Internal release information.
countries Array of Countries Occurrences 0..* No Key Top Level
countries/@code String 3 Key Internal country code
countries/@isoCode String 2 Key ISO Country Code
countries/description Element Occurrences 0..* No Key Country Description and Language
countries/description/@languageCode String 3 No Key Language in which the content is returned
countries/description/@content String 40 No Key Country Description
@from Integer 8 No key Record# origin of the response
@to Integer 8 No key Record# end of the response
@total Integer 8 No key Total available records

XML schema

<?xml version="1.0" encoding="UTF-8"?>
	<countriesRS xmlns="http://www.hotelbeds.com/schemas/messages" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		<from>0</from>
		<to>0</to>
		<total>0</total>
		<auditData 
			processTime="" 
			timestamp="" 
			requestHost="" 
			serverId="" 
			environment="" 
			release=""/>
		<countries>
			<country code="" isoCode="">
				<description></description>
			</country>
		</countries>
	</countriesRS>

JSON Schema

{
	  "auditData": {    
		  "processTime": "",  
		  "timestamp": "", 
		  "requestHost": "", 
		  "serverId": "",  
		  "environment": "", 
		  "release": ""  
	  }, 
	  "countries": [    
		{   
		  "code": "",   
		  "isoCode": "", 
		  "description": {    
			   "languageCode": "",     
			   "content": ""      
		 }
		}
	  ],
	  "from": 0, 
	  "to": 0, 
	  "total": 0  
	}

 

/locations/destinations

Return the list of available destinations, zones and grouping zones.

Request

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.

Request examples

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

 

Response

Response parameters

Node/Attribute Type Max Size KEY Description
auditData Element Occurrences 1 No Key Relevant internal information
auditData/@processTime String Occurrences 1 No Key Server process time in milliseconds
auditData/@timestamp String Occurrences 1 No Key Date/time when the requests has been processed. Always returned at Spanish time
auditData/@requestHost String Occurrences 1 No Key IP From where the petition was sent to the system
auditData/@serverId String Occurrences 1 No Key Server code or ID(Internal use)
auditData/@environment String Occurrences 1 No Key Environment where the request has been sent and processed
auditData/@release String Occurrences 1 No Key Internal release information.
destinations Array of Destinations Occurrences 0..* No Key Top Level
destinations/@code String 3 Key Internal destination code
destinations/name Element Occurrences 0..* No Key Destination Description and Language
destinations/name/@languageCode String 3 No Key Language in which the content is returned
destinations/name/@content String 50 No Key Destination Description
destinations/@countryCode String 3 Key Internal Country Code
destinations/@isoCode String 2 Key ISO Country Code
destinations/zones Array of Zones Occurrences 1 No Key List of zones in which the destination is divided.
destinations/zones/@zoneCode String 3 Key Internal Zone Code
destinations/zones/@name String 50 No Key Internal zone name
destinations/zones/description Element Occurrences 0..* No Key Zone Description and Language
destinations/zones/description/@languageCode String 3 No Key Language in which the content is returned
destinations/zones/description/@content String 50 No Key Multilanguage Zone description
destinations/groupZones Array of Zone Groups Occurrences 1 No Key List of zone groups
destinations/groupZones/@groupZoneCode String 50 Key Group Zone Code
destinations/groupZones/name Element Occurrences 0..* No Key Group Zone Description and Language
destinations/groupZones/name/@languageCode String 3 No Key Language in which the content is returned
destinations/groupZones/name/@content String 50 No Key Multilanguage Group Zone description
destinations/groupZones/zones Array of Zones Occurrences 1 No Key List of zones included in the group zone
@from Integer 8 No key Record# origin of the response
@to Integer 8 No key Record# end of the response
@total Integer 8 No key Total available records

XML schema

<?xml version="1.0" encoding="UTF-8"?>
	<destinationsRS xmlns="http://www.hotelbeds.com/schemas/messages" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		<from>0</from>
		<to>0</to>
		<total>0</total>
		<auditData 
			processTime="" 
			timestamp="" 
			requestHost="" 
			serverId="" 
			environment="" 
			release=""/>
		<destinations>
			<destination code="" countryCode="" isoCode="">
				<name languageCode=""></name>
				<zones>
					<zone zoneCode="" name="">
						<description languageCode=""></description>
					</zone>
				</zones>
				<groupZones>
					<groupZone groupZoneCode="">
						<name languageCode=""></name>
						<zones>
							<zone></zone>
						</zones>
					</groupZone>
				</groupZones>
			</destination>
		</destinations>
	</destinationsRS>

JSON schema

{
	  "auditData": {    
		  "processTime": "",  
		  "timestamp": "", 
		  "requestHost": "",    
		  "serverId": "",    
		  "environment": "",  
		  "release": ""    
	  }, 
	  "destinations":[
		{
		  "code": ""
		  "name": {    
			"languageCode": "",            
			"content": ""         
		  },
		  "countryCode": "", 
		  "isoCode": "", 
		  "zones": [
		   {
			 "zoneCode": 0,
			 "name": "",
			 "description": {      
				  "languageCode": "",   
				  "content": ""   
			 }
		   }
		  ],
		  "groupZones": [
		   {
			 "groupZoneCode":"",
			 "name": {
			   "languageCode": "",   
			   "content": ""          
			 },
			 "zones":[
				 0
			 ]
		   }
		 ] 
		}
	   ],
	   "from": 0, 
	   "to": 0,
	   "total": 0 
	 }

Docs Navigation