API Documentation

HotelGrade provides official hotel star ratings sourced directly from national tourism authorities. Every rating is government-issued — no scraped data, no review aggregates.

What's included

The API gives you access to 24,000+ hotels across France, Portugal, Spain (12 regions), and more countries coming. Each record includes the official star classification, GPS coordinates (where available), contact details, and the source authority.

Quick Start

Get up and running in under 2 minutes.

# Search for 5-star hotels in France
curl "https://hotelgrade.eu/api/hotels?country=France&stars=5&limit=10" \
  -H "X-API-Key: hsa_your_key_here"

const response = await fetch(
  'https://hotelgrade.eu/api/hotels?country=France&stars=5&limit=10',
  { headers: { 'X-API-Key': 'hsa_your_key_here' } }
);
const data = await response.json();
console.log(data.data); // array of hotels

import requests

response = requests.get(
    'https://hotelgrade.eu/api/hotels',
    params={'country': 'France', 'stars': 5, 'limit': 10},
    headers={'X-API-Key': 'hsa_your_key_here'}
)
data = response.json()
print(data['data'])

Authentication

All API requests require a valid API key passed in the X-API-Key request header.

X-API-Key: hsa_your_key_here

API keys follow the format hsa_ followed by 48 hexadecimal characters. You can generate up to 3 keys per account from your dashboard.

Try the API without a key

The /api/demo endpoint is publicly accessible without authentication and returns up to 5 results. It's rate-limited to 10 requests per minute per IP.

curl "https://hotelgrade.eu/api/demo?country=Portugal&stars=5"

API Key Management

Manage your keys from the dashboard. You can also use the REST endpoints below directly.

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI...",  // JWT — valid 30 days
  "user": { "email": "you@example.com" },
  "api_key": "hsa_a1b2c3d4..."  // shown once — save it!
}

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI...",
  "user": { "email": "you@example.com" }
}

{
  "success": true,
  "user": { "email": "you@example.com" },
  "keys": [
    {
      "id": 12,
      "name": "My App",
      "plan": "free",
      "status": "active",
      "requests_today": 47,
      "requests_total": 1203,
      "last_used_at": "2026-03-23T10:42:00Z",
      "created_at": "2026-01-15T08:00:00Z"
    }
  ],
  "can_create_key": true  // false when 3 keys already exist
}

Search Hotels

Search and filter hotels across the entire database. Returns paginated results.

Query parameters

curl "https://hotelgrade.eu/api/hotels?country=Spain&stars=4&limit=20" \
  -H "X-API-Key: hsa_your_key_here"

const params = new URLSearchParams({ country: 'Spain', stars: 4, limit: 20 });
const res = await fetch(`https://hotelgrade.eu/api/hotels?${params}`, {
  headers: { 'X-API-Key': 'hsa_your_key_here' }
});
const { data, pagination } = await res.json();

r = requests.get('https://hotelgrade.eu/api/hotels',
    params={'country': 'Spain', 'stars': 4, 'limit': 20},
    headers={'X-API-Key': 'hsa_your_key_here'})

Response

{
  "success": true,
  "data": [
    {
      "id": 18234,
      "name": "Hotel Arts Barcelona",
      "stars": 5,
      "country": "Spain",
      "country_code": "ES",
      "city": "Barcelona",
      "address": "Carrer de la Marina, 19-21",
      "latitude": 41.3874,
      "longitude": 2.1965,
      "phone": "+34 93 221 10 00",
      "website": "https://www.hotelartsbarcelona.com",
      "email": null,
      "source": "spain-oficial",
      "source_id": "es-ct-HO-000123"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 487,
    "totalPages": 25
  }
}

Rate limit headers

Every response includes headers indicating your current rate limit status:

X-RateLimit-Limit: 10             # requests allowed per minute
X-RateLimit-Remaining: 8          # requests left this minute
X-RateLimit-Reset: 1711187120    # Unix timestamp of window reset
X-RateLimit-Daily-Limit: 100      # daily quota
X-RateLimit-Daily-Remaining: 53  # daily quota remaining

Get Hotel by ID

Retrieve full details for a single hotel using its internal ID from a search result.

Path parameters

curl "https://hotelgrade.eu/api/hotels/18234" \
  -H "X-API-Key: hsa_your_key_here"

{
  "success": true,
  "data": { /* full hotel object */ }
}

Countries Statistics

Returns hotel count and star rating statistics per country. Useful for understanding coverage and market analysis.

curl "https://hotelgrade.eu/api/stats/countries" \
  -H "X-API-Key: hsa_your_key_here"

{
  "success": true,
  "data": [
    {
      "country": "France",
      "total_hotels": 13209,
      "avg_stars": "3.2",
      "min_stars": 1,
      "max_stars": 5,
      "hotels_with_stars": 12847
    },
    // ...
  ]
}

Stars Distribution

Count of hotels by star rating. Optionally filter by country.

Query parameters

curl "https://hotelgrade.eu/api/stats/stars?country=France" \
  -H "X-API-Key: hsa_your_key_here"

{
  "success": true,
  "data": [
    { "stars": 1, "count": "512" },
    { "stars": 2, "count": "1840" },
    { "stars": 3, "count": "4203" },
    { "stars": 4, "count": "4918" },
    { "stars": 5, "count": "1736" }
  ]
}

Countries List

Returns all countries currently available in the database. Use this to populate a country picker in your UI.

{
  "success": true,
  "data": ["France", "Portugal", "Spain"]
}

Hotel Object Reference

Every hotel endpoint returns objects with the following fields:

Source identifiers

When the same hotel exists in multiple sources, the highest-priority version is kept. Official government data always wins over community data.

Plans & Rate Limits

Rate limits apply per API key. When a limit is exceeded the API responds with HTTP 429.

Error Codes

All error responses follow a consistent JSON format:

{
  "success": false,
  "error": "Human-readable description of the error."
}

429 response example

{
  "success": false,
  "error": "Limite journalière dépassée.",
  "limit": 100,
  "plan": "Free",
  "resets_at": "2026-03-24T00:00:00.000Z",
  "upgrade": "Passez à un plan supérieur pour augmenter votre quota."
}