Preparing a List of Hotel IDs

The first step in searching for rates is identifying which hotels you want to search. This guide walks through some common methods for identifying the right hotels and best practices to consider.

Using Hotel list

The starting point to getting a list of hotel IDs is to query the Hotel list endpoint. This endpoint returns an array of hotels with their IDs that can then be passed to Hotel rate availability. There are two main ways to query, which will be covered in more detail further down. You can request a list of hotels located in a specific city or within a radius of a specific latitude and longitude.

Hotel list has two optional fields, offset and limit. Together, they can be used to paginate the results. The limit parameter specifies the maximum number of records to return in a single request, while the offset parameter indicates the starting point within the dataset. By adjusting these parameters, you can retrieve a specific subset of data. For example, setting limit=100 and offset=200 will return 100 records starting from the 201st record.

⭐️ Note: The returned HotelIds field contains all the IDs, already comma delimited and ready to pass to the rate endpoint.

Search for hotels by City

The easiest way to get those hotel IDs is to query the Hotel list endpoint by city. This involves passing the country code and city name of the area where you want hotel IDs. This method requires the fields countryCode and cityName and returns a list of all the hotels in that city.

🚨 Note: The array will be empty if nothing is found. This is usually because an invalid countryCode or cityName was passed.

Getting countryCode and cityName

Since countryCode and cityName need to match exactly, any request must use the format the endpoint expects, or no hotels will be found. To facilitate this, the endpoints Country list and City list are available to ensure the expected format is used.

⭐️ Note: Country and city names don't often change, which is why these endpoints are in the Static Data section. Rather than calling these endpoints each time, it's usually faster and more efficient to store valid country and city data in the application and only call the endpoint to update them periodically.

Search for hotels by latitude and longitude

The other way to query the hotel list endpoint is by entering a specific latitude and longitude. Using this method, you must also pass in a radius to define the distance from the selected point that hotels will be included. The field is in meters and must be greater than 1000.

Getting longitude and latitude

The challenge with the longitude and latitude method is getting the longitude and latitude in the first place. The two most common ways to do this are to use a map and have users select a specific point or to use a text search that maps the location name or address to a latitude and longitude.

With the map option, the location the user selects on a map needs to be identified by its coordinates.Google Maps can pass latitude and longitude from a click event. Those values can then be passed to the Hotel list endpoint to return a list of nearby hotels.

With the text search option, you often want to combine it with autocomplete to avoid spelling errors and confusion over locations with the same name.

A service like Google's Geocoding API allows the selected location to be passed and returns back the latitude and longitude of the location to then be passed to the Hotel list endpoint to return a list of nearby hotels.

Which one to use?

While locating hotel IDs using Country and City is less work to integrate, the results returned are defined by the city boundaries. Some cities are very large, while others are tiny, not just in population but also in geographic coverage. For a large walkable city, being on the wrong side means substantial time loss, while small cities often have fewer options and benefit from neighboring lodging facilities.

For most lodging seekers, scoping the search to a radius around the location where they want to stay is more intuitive. Even when users can search for cities or points of interest, it is nearly always preferable to convert those locations into a specific latitude and longitude value and plot a radius from there. Not only do users get the value of a radius search, but it also removes many of the challenges associated with duplicate city names or misspellings.

Creating a custom hotel ID list

Sometimes, a method other than the ones provided by our API is preferred. The two methods of listing hotel IDs that liteAPI provides are optimized to return results quickly. There are more complex ways of identifying a set of hotels, but to keep response times fast, we recommend running those locally in your application. To do so, copy our list of hotel IDs to a table in your application where complex operations can quickly be run.

⭐️ Note: Rather than needing to query the API repeatedly to build your own hotel IDs table, you may find it faster to download all the hotels by country from our Static Data repository.