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

# Amadeus Hotel Ratings

The Amadeus Hotel Ratings API returns aggregated guest sentiment scores for hotels identified by Amadeus hotelIds. Each call returns an overall sentiment score together with a breakdown across categories such as service, room, location, and value, computed from review text mined across multiple sources. The single endpoint accepts up to several hotelIds at once and is designed to enrich booking interfaces, comparison shoppers, and ranking algorithms with quality signals beyond star ratings.

## For AI agents

Fetch aggregated guest sentiment scores by category for one or more Amadeus hotelIds, so agents can rank or filter hotels by review-based quality.

## Scope

Does not return raw review text, prices, or bookings - use for aggregated hotel sentiment scores only.

## Capabilities

- Retrieve overall sentiment score for a hotel from Amadeus's review aggregation pipeline
- Break down sentiment by category - service, room, location, value, sleep, internet, catering
- Compare quality signals across multiple hotelIds in a single GET call
- Enrich Hotel Search offers with review sentiment to power ranking and filtering
- Surface review-based scores alongside star ratings in booking UIs

## Use cases

### Ranking hotel search results by quality

After calling Hotel Search and receiving a list of offers, fetch sentiment scores for each hotelId and re-rank the results by overall sentiment or a specific category like cleanliness or location. The endpoint accepts a comma-separated list of hotelIds in a single request, so the enrichment step adds one round-trip rather than one per hotel. This is the difference between sorting by 'closest match' and sorting by 'highest review quality near you'.

Example prompt: Given hotelIds [TELONMFS, ADNYCCTB, HLLON101], call GET /e-reputation/hotel-sentiments and return the hotelId with the highest overall score.

### Category-aware traveller filtering

Different travellers care about different things - a business traveller weights internet and sleep, a family weights catering and value. Hotel Ratings exposes per-category sentiment so the application can build trip-aware filters that surface hotels matching the traveller's actual priorities. Combine with Hotel Search to deliver a shortlist that reflects review-based fit, not just price.

Example prompt: Filter a shortlist of 20 hotels to only those with a service sentiment score above 80 and an internet score above 70.

### Quality signal for AI travel recommendations

An AI-powered travel recommender uses hotel sentiment as one of several signals when explaining a recommendation to a user. The agent fetches sentiment via Hotel Ratings, combines it with price from Hotel Search and points-of-interest proximity, and produces a ranked recommendation with a citation: 'guests rate this hotel 88/100 for location and 91/100 for cleanliness'. This grounds AI-generated recommendations in real review data.

Example prompt: Use Jentic to search 'get hotel sentiment scores', load Hotel Ratings, execute with hotelIds=TELONMFS,ADNYCCTB and produce a ranked summary citing each category score.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /e-reputation/hotel-sentiments | Get sentiment scores by Amadeus hotelIds |

## Key resources

- **Hotel Sentiments** — Single endpoint returning aggregated sentiment scores and category breakdowns for one or more hotelIds.

## Why Jentic

- **Setup:** Wiring Hotel Ratings by hand means running the Amadeus Self-Service OAuth 2.0 client_credentials exchange, refreshing the bearer token before it expires, choosing the v2 test or production host, and packing a comma-separated hotelIds query parameter to fetch a shortlist in one round-trip. Through Jentic you install once, import Hotel Ratings from the API Directory, store the client_id and client_secret once, and your agent calls it.
- **Permission scoping:** The hotelIds travel as a query parameter on the GET to /e-reputation/hotel-sentiments, not in the URL path, so scoping is by operation rather than by a specific hotel. Limit the agent to the operations it needs, such as reading hotel sentiment scores, and it stays a read-only enrichment caller with no path to search or booking operations.
- **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 'get hotel sentiment scores', and Jentic returns the /e-reputation/hotel-sentiments operation with its hotelIds parameter and category response shape so the agent calls it directly.

## Related APIs

- **Amadeus Hotel Search** — Hotel Search returns the offers; Hotel Ratings enriches each hotelId with review-based sentiment.
- **Amadeus Hotel Name Autocomplete** — Resolve a partial keyword to a hotelId before fetching its sentiment scores.
- **Amadeus Hotel Booking** — Hotel Booking commits the reservation once Hotel Ratings has informed the user's choice.

## FAQ

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

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

### Can I retrieve sentiment for multiple hotels in one call?

Yes. The endpoint GET /e-reputation/hotel-sentiments accepts a comma-separated hotelIds query parameter, so you can fetch scores for a shortlist of hotels in a single round-trip rather than one call per hotel.

### What categories of sentiment does the API return?

Each result includes an overall score plus per-category sentiment for service, room, sleep, value, location, internet, food, and points of interest. Scores are normalised to a 0-100 scale and are computed from review text aggregated across multiple sources.

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

Amadeus enforces per-second and monthly transaction limits that vary by environment. The test base URL test.api.amadeus.com/v2 has lower quotas appropriate for development; production tiers and quotas are set in your Amadeus for Developers contract.

### How do I retrieve hotel sentiment through Jentic?

Install the SDK with pip install jentic, then search 'get hotel sentiment scores' to discover the Hotel Ratings operation. Load its schema, then execute with hotelIds. Jentic returns the parsed sentiment payload ready for ranking. Get started with Jentic One, the self-hosted execution layer.

### Is the Hotel Ratings API available in the test environment?

Yes, but with restricted coverage - the test environment exposes a subset of production hotels (around 24 properties across London and New York). For broader coverage you must upgrade to the production tier in the Amadeus for Developers portal.

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

Yes. Because you run Jentic One yourself, your own rules decide which operations and credentials the agent may use. This API exposes a single read operation, GET /e-reputation/hotel-sentiments, so you can allow the agent only to read hotel sentiment scores and nothing else. Scoped that way, it stays a read-only enrichment caller with no path to Amadeus search or booking operations, and your client_id and client_secret are held by your own instance rather than the agent.