Rate and Hotel Query Guide

Retrieve Rates Endpoint

The Retrieve rates for hotels endpoint allows users to retrieve hotel rates based on various search criteria and filters. This guide details the required fields, optional settings, common search patterns, and filters. many of these same fields are available on the Retrieve a list of hotels endpoint which will return IDs for use with this rate search. Feel free to chain calling these two endpoints together, or do it all from the rate request, as best fits your application.

Quick Reference Table

This table provides a quick overview of all the fields. For more information, scroll down to the parameter details.

Note: Parameters marked with * are required.

Required Fields

occupancies (Array of Objects, Required)

• Description: Specifies the number of adults and the ages of children for each room in the booking. This allows you to retrieve rates based on the exact occupancy configuration. Adding multiple occupancies will search for multiple rooms/rates at a single hotel to accommodate the requested party. (Multi-hotel bookings from one rate query are not yet supported)
• Example: This example is looking for accommodations for one room containing three adults and two children and a second room containing one adult and two children.
  JSON

  "occupancies": [
      {
        "adults": 3
        "children": [
          5,
          6
        ],
      },
      {
        "adults": 1,
        "children": [
          2
        ]
      }
    ]
  

currency (String, Required)

• Description: The currency in which the rates should be returned. Use the currencies endpoint to get valid values.
• Example: "USD"

guestNationality (String, Required)

• Description: The nationality of the guest. Some rates are specific to the guest's country of origin. Use the countries endpoint to get valid values.
• Example: "US"

checkin (String, Required)

• Description: The check-in date for the stay.
• Format: YYYY-MM-DD
• Example: "2024-12-30"

checkout (String, Required)

• Description: The check-out date for the stay.
• Format: YYYY-MM-DD
• Example: "2024-12-31"

Optional Settings

timeout (Integer, Optional)

• Description: Request timeout in seconds. Setting this too short will mean some slower rates may be missed, while longer times can frustrate users. For live requests, between 4-10 seconds is recommended.
• Example: 5 - Return all the rates that responded within 5 seconds.

roomMapping (Boolean, Optional)

• Description: Enables detailed room mapping in the response, providing a mapped room ID when available. Check out the Displaying Hotel Details guide to better understand how this room ID can be used to display room-specific details.
• Example: true - True enables mapped room IDs.

limit (Integer, Optional)

• Description: The maximum number of hotel results to return. Useful for testing or when you want to retrieve a smaller subset of results to speed up queries. This is a limit on the hotel IDs returned by your search pattern, which are then queried for rates. This limits the total number of hotels searched, not the rates themselves, which can be quite numerous. This does not guarantee that limit hotels will be returned since it won't be on the list if the hotel doesn't have available rates.
• Example: 10 - This will return rates from 10 or fewer hotels that match your search pattern..

offset (Integer, Optional)

• Description: Offset is mainly used alongside limit for iterating over a large returned result. offset indicates how many results to skip before starting to return results. Combine with limit to step through large lists.
• Example: 20 - This will skip the first 20 hotels that match your search pattern.

weatherInfo (Boolean, Optional)

• Description: Returns weather information for the date range and location being queried. The location is based on the first hotel being returned. If hotels from multiple areas or large areas are being queried, then it may be best to make separate queries to the Weather Data Endpoint for each hotel. Check out the Weather Data API Endpoint guide for more information about the data returned.
• Example: true - True returns an array of the weather. Example:

  "weather": [
    {
      "dailyWeather": {
        "date": "2025-01-03",
        "units": "metric",
        "cloud_cover": {
          "afternoon": 70.05
        },
        "humidity": {
          "afternoon": 85.66
        },
        "precipitation": {
          "total": 2.82
        },
        "temperature": {
          "min": 5.63,
          "max": 10.68,
          "afternoon": 5.63,
          "night": 10.68,
          "evening": 7.11,
          "morning": 9.31
        },
        "pressure": {
          "afternoon": 1023.48
        },
        "wind": {
          "max": {
            "speed": 5.38,
            "direction": 2.57
          }
        }
      }
    }
 ]

Common Search Patterns

Pass in Hotel IDs Directly

Use this method if you are statically storing and querying IDs on your application or using the hotel list endpoint to get the IDs.

hotelIds (Array of Strings, Optional)

• Description: Directly specify hotel IDs for which rates are requested.
• Example: ["lp3803c", "lp19e75"]

Search by City Name

Use this to search for hotels in a specific country and city combination. This is a fairly rudimentary option since countries may have multiple cities with the same name, and the size of some cities means returning very large result sets. Smaller cities may not be listed. Use the city list endpoint to get valid cities.

cityName (String, Optional)

• Description: Name of the city where the hotels are located. Use this alongside countryCode.
• Example: "New York"

countryCode (String, Optional)

• Description: ISO-2 country code of the location to search. Use this alongside cityName.
• Example: "US"

Latitude/Longitude Search

The Latitude/Longitude search allows you to retrieve hotel rates based on a specific geographic location. By providing latitude and longitude coordinates, along with an optional radius, you can narrow down hotel options within a defined area. This search method is particularly useful for finding accommodations near a specific point of interest, such as a landmark, business district, or event venue.

latitude (Number, Optional)

• Description: Latitude coordinate for the search area.
• Example: 34.052235

longitude (Number, Optional)

• Description: Longitude coordinate for the search area.
• Example: -118.243683

radius (Integer, Optional)

• Description: Search radius in meters from the specified latitude and longitude.
• Example: 5000

Search by IATA Code

The Search by IATA Code allows you to retrieve hotel rates based on proximity to a specific airport. By providing the IATA code of the desired airport, this search method focuses on finding hotels near that location, making it particularly useful for travelers looking for accommodations near their arrival or departure point.

iataCode (String, Optional)

• Description: IATA code of the airport near the search location.
• Example: "LAX"

Search by Google Place ID

Passing a Google Place ID in your search offers precise targeting of hotels near a specific landmark or by a known geometric area e.g. Manhattan. This method leverages Google’s extensive database of places, ensuring accurate results for areas defined by well-known spots. To get a valid Google Place’s IDs, you can integrate Google Places' Autocomplete and other Google Places API features. You can also use our Google Places' wrapper to get the placeId to pass through to this field.

This capability allows for smooth transitions between location searches, making it highly versatile for developers using Google’s ecosystem or even wrapping their own Google Places search functionality.

placeId (String, Optional)

• Description: Google Place ID for a specific location.
• Example: "ChIJYeZuBI9YwokRjMDs_IEyCwo"

Natural Language Search In Beta

The Natural Language Search enables you to retrieve hotel rates using intuitive, human-like queries. This method simplifies the search process by allowing users to enter phrases like “hotels near the Eiffel Tower,” making it easier to find relevant results without needing detailed parameters.

aiSearch (String, Optional)

• Description: AI-powered search query for hotels using natural language.
• Example: "hotels near paris"

Filters

These filters allow you to refine search results based on specific criteria, such as hotel ratings, amenities, and guest reviews. By applying these filters, you can ensure that the returned hotels meet your desired quality and feature requirements, enhancing the relevance of the search results.

hotelName (String, Optional)

• Description: Enter all or part of a name to filter to only hotels that loosely match. This is case-insensitive.
• Example: hilton

minReviewsCount (Integer, Optional)

• Description: The minimum number of reviews a hotel must have to be included in the search results.
• Example: 100

minRating (Number, Optional)

• Description: The minimum rating for hotels to be included in the search results.
• Example: 4.5

zip (String, Optional)

• Description: Limit hotels to a specific ZIP code.
• Example: "10012"

starRating (Array of Numbers, Optional)

• Description: Filters hotels by star rating. Specify multiple ratings to include in the search. Note: ratings are rounded to the nearest half from 0 to 5. e.g. [3.5, 4.0, 4.5, 5.0]
• Example: [3.5, 4, 5]

facilities (Array of Numbers, Optional)

• Description: Filters hotels by facilities (e.g., pool, gym, Wi-Fi). Each facility is represented by an ID.
• Example: [1, 2, 3] - By default any hotel haveing any one of these three facilities would be valid. Use the flag below to require all three.

strictFacilityFiltering (Boolean, Optional)

• Description: When set to true, only hotels with all specified facilities will be returned.
• Example: true

Return Format

stream (Boolean, Optional)

• Description: Controls whether the API response is streamed or returned as a single complete payload. By default, this is false and returns a single JSON response. Set this to 'true' to enable streaming mode, where the response data is sent incrementally. Check our Streaming Hotel Rates guide to learn more about taking advantage of this asynchronous functionality.
• Example: true