canonical: https://jentic.com/apis/amadeus.com/amadeus-hotel-search

# Amadeus Hotel Search API

The Amadeus Hotel Search API returns live hotel offers - rates, room types, board options, cancellation policies - for a list of Amadeus hotelIds and a stay window. It powers the price-and-availability step of a hotel booking funnel: take a shortlist of hotels and produce concrete, bookable offers with offerIds that can be confirmed downstream by the Hotel Booking API. Two endpoints cover the flow: a list call that returns offers across many hotels at once, and a detail call that re-prices a single offer before booking.

## For AI agents

Fetch live hotel offers and pricing for a set of Amadeus hotelIds, returning bookable offerIds, room descriptions, and cancellation rules ready to pass to Hotel Booking.

## Scope

Does not commit reservations, charge cards, or store booking records - use for hotel offer search and re-pricing only.

## Capabilities

- Retrieve hotel offers for up to many hotelIds in a single getMultiHotelOffers call
- Filter offers by check-in and check-out dates, adults, room quantity, and currency
- Re-price a specific offerId before booking using getOfferPricing
- Surface board type, cancellation policy, and total price for each room offer
- Support best-rate-only and paymentPolicy filters to narrow returned offers

## Use cases

### Multi-hotel comparison shopper

Power a hotel comparison page that takes a shortlist of properties (typically 10-50 hotelIds from a previous search step) and returns live offers for each, enabling side-by-side comparison of price, room type, and cancellation flexibility. The getMultiHotelOffers endpoint accepts the hotelIds list and stay parameters and returns a structured offers array, so the front-end can render comparison cards without fan-out calls.

Example prompt: Call GET /shopping/hotel-offers with hotelIds=TELONMFS,ADNYCCTB,HLLON101 checkInDate=2026-07-01 checkOutDate=2026-07-04 adults=2 and return each hotel's lowest total price.

### Pre-booking price confirmation

Before charging a customer, hotel sites must re-confirm the offer is still available at the quoted price - rates change frequently and an offer surfaced in a search result may already be stale. The getOfferPricing endpoint re-prices a specific offerId and returns the current rate plus full booking metadata. This is the standard last step before invoking Hotel Booking to commit the reservation.

Example prompt: Call GET /shopping/hotel-offers/{offerId} for offerId=B5GHX3 and verify the total price still matches what was shown to the user.

### Date-flexible availability scan

Some travellers care more about getting a specific hotel than a specific date. Sweep getMultiHotelOffers across a range of check-in dates for a single hotelId to find when the property has availability and at what rate. Combine with Hotel Ratings to surface highly-rated alternatives if the preferred hotel is unavailable. Useful for concierge agents and travel research assistants.

Example prompt: For hotelId=TELONMFS, call /shopping/hotel-offers across 14 consecutive check-in dates and return all dates with at least one bookable offer.

### AI agent booking flow

An AI agent handling 'book me a room in Paris next Friday for two nights' uses Hotel Search to fetch concrete offers after the user has chosen a hotel via Autocomplete and Ratings. The agent calls Jentic to discover Hotel Search, executes it with the user's parameters, presents the cheapest cancellable offer for confirmation, then re-prices it via getOfferPricing before chaining to Hotel Booking.

Example prompt: Use Jentic to search 'search hotel offers', execute Hotel Search with hotelIds, dates, and adults parameters, and return the lowest cancellable offer for user confirmation.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /shopping/hotel-offers | Get offers across multiple hotelIds for a stay |
| GET | /shopping/hotel-offers/{offerId} | Re-price a specific hotel offer by offerId |

## Key resources

- **Hotel Offers** — List live offers across multiple hotelIds and re-price a specific offer before booking.

## Why Jentic

- **Setup:** Wiring Hotel Search by hand means running the Amadeus Self-Service OAuth 2.0 client_credentials exchange, refreshing the bearer token before it expires, choosing the v3 test or production host, and handling both the multi-hotel offers list and the single-offer re-pricing call. Through Jentic you install once, import Hotel Search from the API Directory, store the client_id and client_secret once, and your agent calls it.
- **Permission scoping:** Both endpoints are read-only: /shopping/hotel-offers takes hotelIds and stay dates as query parameters and the re-price call carries the offerId in the URL path, so scoping is by operation rather than by a single hotel. Limit the agent to the operations it needs, such as searching hotel offers and re-pricing an offer, and it cannot reach the separate Hotel Booking operation unless you add it.
- **Credential handling:** Your Amadeus client_id and client_secret are stored once, encrypted, by your own Jentic One instance, which runs the OAuth exchange and injects a fresh bearer token at execution time. The secret never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'search hotel offers', and Jentic returns the Hotel Search operations with their hotelIds, date, and occupancy parameter schemas so the agent calls them without parsing the reference docs.

## Related APIs

- **Amadeus Hotel Booking** — Hotel Booking commits an offerId returned by Hotel Search into a confirmed reservation.
- **Amadeus Hotel Name Autocomplete** — Resolve free-text hotel keywords into the hotelIds Hotel Search needs as input.
- **Amadeus Hotel Ratings** — Hotel Ratings enriches the offers returned by Hotel Search with sentiment scores for ranking.

## FAQ

### What authentication does the Hotel Search API use?

OAuth 2.0 client credentials. Exchange your Amadeus API key and secret for a bearer access token, then pass it as the Authorization header on each call. Through Jentic, the client secret stays encrypted in the vault and the agent only ever receives a scoped bearer token.

### Can I search offers across many hotels in one call?

Yes. GET /shopping/hotel-offers accepts a comma-separated hotelIds parameter so you can fetch live offers for a shortlist of hotels in a single request. This is the recommended pattern for comparison shoppers and multi-hotel result pages.

### Why do I need to re-price an offer before booking?

Hotel rates change frequently. The /shopping/hotel-offers/{offerId} endpoint re-confirms the current price and availability for a specific offerId before you commit it to Hotel Booking. Skipping this step often results in price-mismatch errors at booking time.

### What are the rate limits for the Hotel Search API?

Amadeus enforces per-second TPS and monthly transaction quotas that depend on environment and contract. Test (test.api.amadeus.com/v3) has low quotas suitable for development; production limits are set in your Amadeus for Developers contract.

### How do I search hotel offers through Jentic?

Install with pip install jentic, then search 'search hotel offers' to discover the Hotel Search operation. Load its schema, then execute with hotelIds, checkInDate, checkOutDate, and adults parameters. Jentic returns the parsed offers ready to display or chain into Hotel Booking. Get started with Jentic One, the self-hosted execution layer.

### Does the test environment cover all hotels?

No. The Amadeus test environment offers only a subset of production hotels and may change dynamically. For prototyping, test against major-city hotelIds like those in London (LON) or New York (NYC); upgrade to production for full inventory.

### Can I limit what my agent is allowed to do with the Hotel Search API?

Yes. Because you run your own self-hosted Jentic One instance, your rules decide which operations and credentials the agent may use. Both Hotel Search operations are read-only, so you can grant the agent just the ones it needs, such as searching offers across hotelIds via /shopping/hotel-offers and re-pricing a single offerId via /shopping/hotel-offers/{offerId}. Scoping is by operation, so the agent cannot reach the separate Hotel Booking operation unless you explicitly add it.