Developers

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 an API key

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/hri

Live response (captured 2026-06-10):

{
  "hotel": {
    "hr_code": "HR-2047570",
    "name": "Atlantis The Royal",
    "city": "Dubai",
    "country_code": "AE",
    "url": "https://hotelsrating.com/h/atlantis-the-royal"
  },
  "rated": true,
  "hri": 99.4,
  "percentile": 0.9999,
  "medal": "gold",
  "components": {
    "crs": 0.8872,
    "exp_award": 0.9005,
    "exp_rank": 1,
    "exp": 0.9403,
    "fac": 0.5,
    "trj": 0.5,
    "confidence": 0.75
  },
  "consensus": {
    "sources": 2,
    "reviews": 9356,
    "agreement": 1
  },
  "computed_at": "2026-06-10T15:16:19.807Z",
  "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)"
}

GET /api/v0/calibration

The nightly calibration anchors that pin 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 three tools: get_hotel_hri, search_hotels_by_hri, get_methodology_summary.

Claude Code:

claude mcp add --transport http hotelsrating https://hotelsrating.com/api/mcp

Any 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 →