MAQAMI Travel

Search hotel rates

post_hotels_rates

Read-only

Search live hotel rates and availability across multiple hotels, then filter by location, dates, guests, amenities, and room options for booking.

Instructions

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

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.

Input Schema

TableJSON Schema

Name	Required	Description
`zip`	No	The zip code of the search location. This is a filter on top of the main query.
`feed`	No	Which rate feed to search. Leave unset to use the default feed.
`sort`	No	Sorting criteria for the results. Multiple criteria can be provided, processed in order. The default sorting is by top picks (weighted by search popularity, review quality, and content completeness). Use 'revenue' to sort by historical booking value and monetary performance.
`limit`	No	The maximum number of results to return. Defaults to 200, max allowed is 5000.
`offset`	No	The number of results to skip for pagination. This paginates the passed hotels not the results returned so the actual returned results will vary.
`radius`	No	The search radius in meters for location-based searches. Pairs with latitude to do a lat/long search.
`stream`	No	If true, enables streaming mode where response data is sent incrementally instead of as a single payload.
`checkin`	Yes	The check-in date in YYYY-MM-DD format (ISO 8601).
`placeId`	No	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. This is a valid main query.
`timeout`	No	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.
`aiSearch`	No	AI-powered hotel search based on a natural language query. Uses semantic search to find hotels matching the query intent. Examples: 'Romantic getaway with Italian vibes in London near the London Eye', 'hotels near Paris'. This is a valid main query.
`bedTypes`	No	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'.
`chainIds`	No	An array of hotel chain IDs to filter the search results. This is a filter on top of the main query.
`checkout`	Yes	The check-out date in YYYY-MM-DD format (ISO 8601).
`cityName`	No	The name of the city to search for hotels in. Pairs with countryCode to do a country/city search.
`currency`	Yes	The currency in which the prices will be displayed.
`hotelIds`	No	An array of hotel IDs to search for availability and pricing. Get them from `get_data_hotels` or `get_data_hotel_search`.
`iataCode`	No	The IATA code of the search location, typically an airport code. Instead of using hotel IDs, you can search by IATA code. This is a valid main query.
`latitude`	No	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. This is a valid main query.
`boardType`	No	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).
`hotelName`	No	A case-insensitive search for a hotel's name (e.g., 'Hilton').
`longitude`	No	The longitude coordinate for location-based hotel searches. Pairs with latitude to do a lat/long search.
`minRating`	No	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.
`sessionId`	No	Optional client-generated session identifier that ensures price consistency for the user's search session. Pass the same `sessionId` with the same `checkin` and `checkout` across related requests in that session.
`facilities`	No	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.
`starRating`	No	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.
`countryCode`	No	The country code in ISO 2-letter format (e.g., 'SG' for Singapore). Instead of using hotel IDs, you can search by country/city. This is a valid main query.
`occupancies`	Yes	An array of objects specifying the number of guests per room. Required.
`roomMapping`	No	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
`hotelTypeIds`	No	An array of hotel type IDs to filter the search results. This is a filter on top of the main query.
`roomAmenities`	No	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.
`loyaltyProgram`	No	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.
`minReviewsCount`	No	The minimum number of reviews a hotel must have to be included in results. This is a filter on top of the main query.
`guestNationality`	Yes	The guest's nationality in ISO 2-letter country code format.
`includeHotelData`	No	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.
`maxRatesPerHotel`	No	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.
`amenityFilterLogic`	No	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.
`refundableRatesOnly`	No	If true, only refundable rates (RFN) will be included in the response.
`roomAmenitiesFilter`	No	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.
`loyaltyProgramDetails`	No	Loyalty membership details forwarded to supported suppliers to unlock member rates and benefits. Provide one entry per loyalty program membership.
`strictFacilityFiltering`	No	If enabled, only hotels with all specified facilities will be returned.
`advancedAccessibilityOnly`	No	If true, only hotels with advanced accessibility features will be returned.

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv1.0.6Oct 7, 2026

changedInput schema / properties / feed / description

Previous value: -"Which feed to use when searching for rates. This applies only to accounts with multiple feeds enabled"New value: +"Which rate feed to search. Leave unset to use the default feed."

changedInput schema / properties / hotelIds / description

Previous value: -"An array of hotel IDs to search for availability and pricing. These are usually pulled from https://docs.liteapi.travel/reference/get_data-hotels."New value: +"An array of hotel IDs to search for availability and pricing. Get them from `get_data_hotels` or `get_data_hotel_search`."

removedInput schema / properties / margin

Removed value: -{
-  "description": "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).",
-  "type": "number"
-}

changedInput schema / properties / maxRatesPerHotel / description

Previous value: -"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."New value: +"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."

changedInput schema / properties / sessionId / description

Previous value: -"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."New value: +"Optional client-generated session identifier that ensures price consistency for the user's search session. Pass the same `sessionId` with the same `checkin` and `checkout` across related requests in that session."

First observedv0.1.0Sep 28, 2026

TDQS

A4.3/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With annotations already covering readOnly/openWorld/idempotent/destructive, the description adds substantial non-obvious behavior: recommended timeout of 6-12s, default limit of 200 (expandable to 5,000), incremental streaming mode, the `sessionId` price-consistency contract, and the caveat that pagination via `offset` skips passed hotels rather than returned results. It also warns that `maxRatesPerHotel` caps before room mapping.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The markdown structure is front-loaded and scannable, opening with Overview, When to Use, then What You Get. The price-consistency guidance is duplicated across 'Key Features' and the Quick Start tip, and the bullet-heavy formatting makes it longer than strictly necessary, but nearly every line earns its place for a 42-parameter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 42-param search tool with no output schema, the description compensates with a 'What You Get' section describing rates, room options, booking details, and hotel data. It covers required inputs, location-method alternatives, and performance defaults. Minor gaps remain around response ordering, error behavior, and timeout defaults, but nothing an agent needs to construct a valid call is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 42 parameters thoroughly. The description mostly restates the required fields and the `includeHotelData` tip rather than adding new semantics; the one genuinely additive piece is the `sessionId` usage pattern (unique per session, reused with the same checkin/checkout). Baseline 3 is appropriate when the schema carries the load.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Search for hotel rates and availability') and positions the tool precisely as 'your primary endpoint for finding bookable hotel rooms with real-time pricing.' It differentiates itself from data-lookup siblings by noting hotel IDs come from `get_data_hotels` or `get_data_hotel_search`, and it enumerates the search methods it supports.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'When to Use' section gives four concrete scenarios (listing pages, detail pages, multi-room bookings, filtering) and the Quick Start names the required fields and the alternative location methods. However, it never explicitly contrasts with the closest sibling, `post_hotels_min_rates`, nor states when not to use this tool, leaving some routing inference to the agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server