Developers
The HOTELSRATING Index as data: a public REST API and an MCP server for AI assistants. The same gate applies everywhere, only hotels with independent signal carry a score.
Authentication & free tier
All v0 endpoints require an API key in the X-API-Key header. Keys are free and self-serve: sign in and get an API key (a verified e-mail address is required). The free tier is 1,000 requests per calendar month; the X-RateLimit-Remaining header tracks what is left. Need more, ask via the contact form (category "API access").
GET /api/v0/hotels/{identifier}/hri
The public HRI breakdown for one hotel. identifier accepts an HR-code (HR-2047570), a numeric id, or the URL slug. Hotels without enough independent signal return "rated": false with null score fields, they are never given a pseudo-score.
curl -H "X-API-Key: YOUR_KEY" \
https://hotelsrating.com/api/v0/hotels/atlantis-the-royal/hriResponse shape under methodology 2.0 (served since 2026-10-26): the components are EXP and FAC with a confidence factor, the recognitions are named by body and family, memberships are informational only."confidence_floor": true marks a thin record: a rated score that rests on one recognition and the class baseline. Confirmed facts raise it.
{
"hotel": { "public_id": "73SV83S10J", "name": "…", "city": "…", "country_code": "…", "url": "https://hotelsrating.com/h/…" },
"rated": true,
"formula": "v2.0",
"weights": { "exp": 0.7, "fac": 0.3 },
"hri_version_break": "…",
"hri": 88.3,
"percentile": 0.9231,
"medal": "silver",
"components": {
"exp_award": 0.8111,
"exp_rank": 0.8368,
"exp": 0.8214,
"fac": 0.7,
"confidence": 0.4643
},
"recognition": {
"families": 1,
"family_labels": ["independent inspection"],
"bodies": [
{ "body": "forbes_travel_guide", "label": "Forbes Travel Guide", "family": 1, "family_label": "independent inspection", "title": "Forbes Travel Guide 5-Star", "year": 2026 },
{ "body": "michelin_keys", "label": "Michelin Keys", "family": 1, "family_label": "independent inspection", "title": "Michelin 3 Keys", "year": 2026 }
]
},
"memberships": [
{ "body": "relais_chateaux", "label": "Relais & Chateaux", "family": 3, "family_label": "paid membership (not scored)", "title": null, "year": null }
],
"confidence_inputs": { "families": 1, "wiki": true, "recognitions": 2, "brand": false },
"confidence_floor": false,
"computed_at": "…",
"attribution": "HotelsRating Index (HRI) by HotelsRating, https://hotelsrating.com (methodology: https://hotelsrating.com/methodology)"
}GET /api/v0/search
Search the rated set, ordered by HRI descending. Parameters: min_hri (0-100), category (slug, see below), geo (two-letter country code), limit (≤50), offset.
curl -H "X-API-Key: YOUR_KEY" \
"https://hotelsrating.com/api/v0/search?min_hri=99&geo=AE&limit=2"Live response (captured 2026-06-10):
{
"total_matched": 3,
"count": 2,
"hotels": [
{
"hr_code": "HR-2047570",
"slug": "atlantis-the-royal",
"name": "Atlantis The Royal",
"stars": 5,
"city": "Dubai",
"country_code": "AE",
"hri": 99.4,
"percentile": 0.9999,
"medal": "gold",
"url": "https://hotelsrating.com/h/atlantis-the-royal"
},
{
"hr_code": "HR-1575079",
"slug": "emirates-palace-mandarin-oriental",
"name": "Emirates Palace Mandarin Oriental",
"stars": 5,
"city": "Abu Dhabi",
"country_code": "AE",
"hri": 99.3,
"percentile": 0.9996,
"medal": "gold",
"url": "https://hotelsrating.com/h/emirates-palace-mandarin-oriental"
}
],
"attribution": "HotelsRating Index (HRI) by HotelsRating, https://hotelsrating.com (methodology: https://hotelsrating.com/methodology)"
}Category slugs (20)
luxury-hotels · budget-hotels · waterfront-hotels · spa-hotels · family-hotels · business-hotels · countryside-hotels · accessible-hotels · conference-hotels · pet-friendly-hotels · airport-hotels · wedding-hotels · golf-resorts · eco-hotels · ski-resorts · diving-hotels · infinity-pool-hotels · all-inclusive-resorts · adults-only-hotels · halal-friendly-hotels
GET /api/v0/calibration
The nightly calibration table that pins the HRI scale (median = 62, top 5% = 90, top 0.5% = 97), so you can verify the scale has not drifted. The same data renders live on the methodology page.
Attribution
You may quote individual scores with attribution to HOTELSRATING and a link, every response carries a ready-made attribution field. Systematic reproduction of scores or rankings, or commercial redistribution, requires a license, see the Terms of Service.
For AI assistants (MCP)
An MCP server (streamable HTTP, no key needed) lives at https://hotelsrating.com/api/mcp with six tools. One prompt sets it up in an assistant:
The prompt is the file /agent-setup/prompt.md.
get_hotel_hri
Get the public Hotelsrating Index (HRI) breakdown for one hotel by its public id (e.g. "MHEZST8VVC"). Returns null score for hotels that are not yet rated. `confidence_floor: true` marks a thin record: the score rests on one recognition and the class baseline, and confirmed facts raise it. Includes the hotel's published contact details under `contacts` for hotels that publish them: website, phone, email, instagram, facebook, x, linkedin, and the direct door - booking_url (the hotel's own booking page), whatsapp (E.164 number), telegram (username), line (LINE ID) and wechat (WeChat ID).
identifier(string, required): Hotel public id (e.g. "MHEZST8VVC")
search_hotels
Find a specific hotel by its name (block W13). Use this whenever the user names a hotel, before concluding it is not on HOTELSRATING. Returns up to 10 published hotels whose name matches (an exact name first), each with public_id, name, city, country, stars, its HRI and medal (null when the hotel is not yet rated) and its page URL, and `contacts` (the same fields as get_hotel_hri) for hotels that publish them. Pass the public_id to get_hotel_hri for the full breakdown.
name(string, required): The hotel name, or a distinctive part of it, e.g. "Castel de Daval"country(string, optional): Two-letter ISO-3166 country code to narrow the search, e.g. "CH"
search_hotels_by_hri
Search rated hotels (signal set only) ordered by HRI descending. Filter by minimum HRI, category slug, and ISO-3166 country code.
min_hri(number, optional): Minimum HRI score, 0-100category(string, optional): Category slug. One of: luxury-hotels, budget-hotels, waterfront-hotels, spa-hotels, family-hotels, business-hotels, countryside-hotels, accessible-hotels, conference-hotels, pet-friendly-hotels, airport-hotels, wedding-hotels, golf-resorts, eco-hotels, ski-resorts, diving-hotels, infinity-pool-hotels, all-inclusive-resorts, adults-only-hotels, halal-friendly-hotels, winery-hotels, pool-hotels, beach-access-hotelscountry(string, optional): Two-letter country code, e.g. "AE"limit(number, optional): Max results, default 20, cap 50
rank_hotels_for_preferences
Rank rated hotels for what a traveller cares about, in one country or one city. Pass EITHER `preset` (a ready-made traveller profile or single fact) OR `facts` (a list of fact keys), and a scope: `country` (two-letter code) or `city` (with `country` when the city name exists in more than one). Rated hotels only: a hotel no independent body has recognised is never in the list. Each hotel carries `hri` (its public score), `pfi` (its personal score), `coverage`, `keys.confirmed` (the requested facts the hotel is confirmed to have) and `keys.unknown` (requested facts nobody has confirmed: listed, not assumed present and not assumed absent), and its page URL. `coverage` (0 to 1) is how strongly the requested facts are evidenced, not how many are confirmed: a fact counts as confirmed from a signal of 0.4, and a fact confirmed on thin evidence adds less than one confirmed in full. So every fact can be confirmed while coverage is below 1. The personal score never exceeds the public one: PFI lies between 0.75 x HRI and HRI, so a preference can only reorder or demote. pfi is computed from the unrounded public score, so it can differ from the product of the printed numbers by a few hundredths. `n_rated` is the number of rated hotels in the scope, `excluded_n` how many a hard filter removed. Call with no preset and no facts to get the scope in plain HRI order. An unknown or unserved preset answers an error listing the valid presets and facts.
preset(string, optional): A served preset id, e.g. "family", "city_work", "fact_pool". The error of a wrong id lists the valid ones.facts(string[], optional): Fact keys, e.g. ["pool", "kids_club"]: category codes or slugs as get_categories returns them.country(string, optional): Two-letter ISO-3166 country code, e.g. "IT"city(string, optional): City name or slug, e.g. "Rome" or "new-york"limit(number, optional): Max hotels, default 10, cap 50
get_categories
The 22 hotel categories, with both names. `slug` is what search_hotels_by_hri takes; `code` is what the personalisation endpoint matches against, and rank_hotels_for_preferences takes either in `facts`. Use this before passing category names anywhere.
No parameters.
get_methodology_summary
Get a faithful summary of how the Hotelsrating Index is computed, including the integrity policy.
No parameters.
Claude Code:
claude mcp add --transport http hotelsrating https://hotelsrating.com/api/mcpAny MCP client with streamable-HTTP support:
{
"mcpServers": {
"hotelsrating": {
"type": "http",
"url": "https://hotelsrating.com/api/mcp"
}
}
}The API exposes exactly what the site shows: scores from the published formula, nothing pay-to-play. Integrity Policy →