Hotel rates

Retrieve rates for hotels

Changed on Nov 3, 2026

Overview

Search for hotel rates and availability across multiple hotels. This is your primary endpoint for finding bookable hotel rooms with real-time pricing.

When to Use

Display hotel listings with prices on your search results page
Show detailed rate options for specific hotels users are viewing
Support multi-room bookings for families or groups
Filter hotels by location, amenities, ratings, or AI-powered semantic search

What You Get

Real-time rates with availability and pricing
Multiple room options per hotel, sorted by price
Complete booking details including cancellation policies, meal plans, and room types
Hotel information (name, photos, address, ratings) when searching by filters

Key Features

Multiple search methods: Search by hotel IDs, city/country, coordinates, Place ID, IATA code, or natural language (AI search)
Flexible filtering: Filter by star rating, facilities, hotel chains, accessibility, and more
Multi-room support: Book multiple rooms with different guest configurations in one request
Performance optimized: Default limit of 200 hotels (expandable to 5,000), recommended timeout of 6-12 seconds
Price consistency: Optional sessionId ensures rates stay consistent across listing and detail searches within a user session (accounts with price consistency enabled)

Quick Start

Required fields: checkin, checkout, currency, guestNationality, occupancies, plus one location method (hotel IDs, city/country, coordinates, Place ID, or IATA code)

Tip: When searching by filters (like aiSearch or cityName), hotel data is automatically included. For direct hotel ID searches, set includeHotelData=true to include hotel names and photos.

Price consistency: Generate a unique sessionId per user search session and include it on every rates request in that session, using the same checkin, and checkout.

post/hotels/rates

Request

Base URL
https://api.liteapi.travel/v3.0
URL
https://api.liteapi.travel/v3.0/hotels/rates
Auth
API key in header X-API-Key

Request body

hotelIdsstring[]

An array of hotel IDs to search for availability and pricing. These are usually pulled from https://docs.liteapi.travel/reference/get_data-hotels. Cannot be combined with aiSearch.

currencystring required

The currency in which the prices will be displayed.

guestNationalitystring required

The guest's nationality in ISO 2-letter country code format.

checkinstring required

The check-in date in YYYY-MM-DD format (ISO 8601).

checkoutstring required

The check-out date in YYYY-MM-DD format (ISO 8601).

timeoutinteger

The maximum time in seconds before the request times out. This is when the live request for rates will cut off responses; it will take a few more ms to return the value.

maxRatesPerHotelinteger

The number of room rates to return per hotel, sorted by price (cheapest first). Set to 1 to just get the cheapest rate for each hotel, this is helpful for listing pages. Try increasing this if you are missing rate types, and be aware that the cap is applied before room mapping.

boardTypestring

Filter results by board type(s). Can be a single value (e.g., 'BI') or comma-separated values (e.g., 'BI,HB') for OR logic. Example values: RO (Room Only), BI (Breakfast Included), HB (Half Board), FB (Full Board), AI (All Inclusive), DI (Dinner Included), LI (Lunch Included), BDI (Breakfast and Dinner Included), BLI (Breakfast and Lunch Included), LDI (Lunch and Dinner Included).

refundableRatesOnlyboolean

If true, only refundable rates (RFN) will be included in the response.

roomAmenitiesnumber[]

Legacy room-level amenity filter. Only rates from rooms that match the specified amenities will be returned. Use amenityFilterLogic to control flat AND/OR behavior. If roomAmenitiesFilter is provided, it takes precedence over this field.

roomAmenitiesFilterstring

Grouped room-level amenity filter. Use '-' for OR within a group and ',' for AND across groups. Example: '1-2,3-4' means (1 OR 2) AND (3 OR 4). If provided, this field takes precedence over roomAmenities and amenityFilterLogic.

amenityFilterLogic'AND' | 'OR'

Legacy logic applied to roomAmenities. 'AND': room must have all specified amenities. 'OR': room must have at least one specified amenity. Ignored when roomAmenitiesFilter is provided.

bedTypesstring[]

Filter results by bed types extracted from room names. Only rates from rooms matching the specified bed types will be returned. Example values: 'double', 'twin', 'king', 'queen', 'single'.

roomMappingboolean

Enable room mapping to retrieve the mappedRoomId for each room. This allows you to link a rate to its specific room by combining it with hotel details, providing access to room images and additional information

hotelNamestring

A case-insensitive search for a hotel's name (e.g., 'Hilton').

countryCodestring

The country code in ISO 2-letter format (e.g., 'SG' for Singapore). Instead of using hotel IDs, you can search by country/city. With aiSearch, countryCode is forwarded as a hard filter on semantic search (pairs with cityName). This is a valid main query.

cityNamestring

The name of the city to search for hotels in. Pairs with countryCode to do a country/city search. With aiSearch, cityName is forwarded as a hard filter on semantic search so brand or vibe queries stay in that city.

latitudenumber

The latitude coordinate for location-based hotel searches. Instead of using hotel IDs, you can search by lat/long and a radius around that spot. With aiSearch, latitude, longitude, and radius together constrain semantic search to that area (hard radius). This is a valid main query.

longitudenumber

The longitude coordinate for location-based hotel searches. Pairs with latitude to do a lat/long search. Required with latitude and radius when using aiSearch for area-scoped semantic search.

radiusinteger

The search radius in meters for location-based searches. Pairs with latitude and longitude. Required with coordinates when using aiSearch for area-scoped semantic search.

iataCodestring

The IATA code of the search location, typically an airport code. Instead of using hotel IDs, you can search by IATA code. Cannot be combined with aiSearch. This is a valid main query.

limitinteger

The maximum number of results to return. Defaults to 200, max allowed is 5000.

offsetinteger

The number of results to skip for pagination. This paginates the passed hotels not the results returned so the actual returned results will vary.

aiSearchstring

AI-powered hotel search based on a natural language query. Uses semantic search to find hotels matching the query intent. You can scope results by passing cityName and/or countryCode (hard filters), or latitude + longitude + radius in meters (hard area filter). Location can also be included in the aiSearch string (e.g. '5 star hotels in Paris'). Cannot be combined with hotelIds, placeId, iataCode, or zip — the request returns 400. For exact brand matching without semantic search, drop aiSearch and use cityName + countryCode + hotelName. This is a valid main query.

minReviewsCountinteger

The minimum number of reviews a hotel must have to be included in results. This is a filter on top of the main query.

minRatingnumber

The minimum rating (on a scale of 0-5) required for hotels in search results. This is a filter on top of the main query.

zipstring

The zip code of the search location. This is a filter on top of the main query. Cannot be combined with aiSearch.

placeIdstring

The unique Place ID of the search location. Instead of using hotel IDs, pass a Place ID to get all the hotels in the specified region. Cannot be combined with aiSearch. This is a valid main query.

starRatingnumber[]

An array of hotel star ratings to include. Ratings are rounded to the nearest half-star (e.g., [3.5, 4.0, 4.5, 5.0]). This is a filter on top of the main query.

hotelTypeIdsnumber[]

An array of hotel type IDs to filter the search results. This is a filter on top of the main query.

chainIdsnumber[]

An array of hotel chain IDs to filter the search results. This is a filter on top of the main query.

facilitiesnumber[]

An array of facility IDs. Results will include hotels with at least one of these facilities by default. This is a filter on top of the main query.

strictFacilityFilteringboolean

If enabled, only hotels with all specified facilities will be returned.

streamboolean

If true, enables streaming mode where response data is sent incrementally instead of as a single payload.

advancedAccessibilityOnlyboolean

If true, only hotels with advanced accessibility features will be returned.

feedstring

Which feed to use when searching for rates. This applies only to accounts with multiple feeds enabled

includeHotelDataboolean

If true, includes hotel data (name, main photo, address, rating) in the response even when searching by direct hotel IDs. By default, hotel data is only included when searching by filters (e.g., using aiSearch, countryCode, cityName, etc.). Setting this to true enables hotel data inclusion for all search types.

marginnumber

Override the markup percentage for this specific request. When provided, this value takes precedence over your account-level margin setting, allowing you to dynamically adjust pricing based on your business logic, customer segments, or other factors. Specified as a percentage number (e.g., 10 for 10% commission).

sessionIdstring

Optional client-generated session identifier that ensures price consistency for the user's search session. When your account has price consistency enabled, pass the same sessionId with the same checkin and checkout across related requests in that session. Has no effect when price consistency is not enabled for your account.

loyaltyProgramstring

Loyalty program identifier used to request loyalty-eligible rates from supported suppliers. When set, rates that support the program may return member pricing and benefits.

Example request

{
  "hotelIds": [
    "lp1897"
  ],
  "occupancies": [
    {
      "adults": 2,
      "children": [
        5,
        2
      ]
    }
  ],
  "currency": "USD",
  "guestNationality": "US",
  "checkin": "2027-01-15",
  "checkout": "2027-01-16",
  "timeout": 6,
  "maxRatesPerHotel": 1,
  "boardType": "BI,HB",
  "refundableRatesOnly": true,
  "roomAmenities": [
    1,
    2,
    3
  ],
  "roomAmenitiesFilter": "1-2,3-4",
  "amenityFilterLogic": "AND",
  "bedTypes": [
    "double",
    "twin"
  ],
  "sort": [
    {
      "field": "top_picks",
      "direction": "descending"
    }
  ],
  "roomMapping": true,
  "hotelName": "Hilton",
  "countryCode": "US",
  "cityName": "New York",
  "latitude": 34.052235,
  "longitude": -118.243683,
  "radius": 5000,
  "iataCode": "LAX",
  "limit": 10,
  "aiSearch": "Romantic getaway with Italian vibes in London near the London Eye",
  "minReviewsCount": 100,
  "minRating": 4.5,
  "zip": "10012",
  "placeId": "ChIJYeZuBI9YwokRjMDs_IEyCwo",
  "starRating": [
    4,
    5
  ],
  "hotelTypeIds": [
    201,
    204,
    208
  ],
  "chainIds": [
    14675,
    14677
  ],
  "facilities": [
    1,
    2,
    3
  ],
  "strictFacilityFiltering": true,
  "advancedAccessibilityOnly": true,
  "feed": "custom_feed",
  "includeHotelData": true,
  "margin": 10,
  "sessionId": "pc-session-3f2504e0-4f89-11d3-9a0c-0305e82c3301",
  "loyaltyProgram": "HH",
  "loyaltyProgramDetails": [
    {
      "membershipId": "814125083",
      "programId": "HH"
    }
  ]
}

Response

guestLevelinteger

Used with loyalty programs to determine the guests level of cost reduction.

sandboxboolean

Indicates if the request was made in a sandbox (test) environment

Example response

{
  "data": [
    {
      "roomTypes": [
        {
          "rates": [
            {
              "retailRate": {
                "promotions": [
                  {
                    "from": "2025-11-14",
                    "to": "2025-11-27",
                    "discountType": "percentage"
                  }
                ]
              }
            }
          ],
          "paymentTypes": [
            "NUITEE_PAY",
            "CREDIT_CARD_SCHEDULED"
          ]
        }
      ]
    }
  ]
}

Changes

Nov 3, 20260414c9ba2a76 Revision changes
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status

Operation history