GET

Hotel Details API

v2

Get hotel information with a compact response shape. Returns top-level hotel_id, flat data object, and retrieval timestamp.

Copy for your AI agent

Paste into Claude, ChatGPT, Cursor or Copilot — endpoint, parameters, response fields and a curl example in Markdown.

v1 deprecated

/v1/booking/hotel/details is still available for existing integrations but deprecated. Use /v2/booking/hotel/details for all new development.

Overview

The Hotel Details v2 endpoint accepts a hotel_id and returns a compact response with property classification, location, ratings, a main photo, and page_name. Includes a nullable property description and nullable check-in/out times. Nested metadata is excluded.

Endpoint URL

GET https://api.stayapi.com/v2/booking/hotel/details

Parameters

Parameter Type Required Description
hotel_id string Required Booking.com hotel ID (e.g., 1331780).

Description, check-in/out times, and property classification

data.description is the property description as a string, or null when unavailable.

data.check_in_time is the earliest check-in and data.check_out_time the latest check-out, each an "HH:MM" string or null when unavailable.

data.property_type is a string or null. It reports Booking.com’s property category, for example HOTEL, APARTMENT, HOLIDAY_HOME, or CHALET. These examples are not an exhaustive enum: clients should accept new string values. The field is null when the category is unavailable.

Error handling and status codes

Status codes: 200 on success; errors use non-2xx (400, 404, 500, 502, 503, 504) with Problem Details.

  • 400 MISSING_PARAMETER: hotel_id is required.
  • 400 INVALID_HOTEL_ID: hotel_id must be numeric.
  • 400 INVALID_PARAMETERS: url param is not accepted (use v1 for URL lookups).
  • 404 Not Found: Upstream indicates the hotel is missing.
  • 502 UPSTREAM_ERROR: Booking.com could not complete the request.
  • 503 Service Unavailable: Upstream rate-limited/maintenance (may include Retry-After).
  • 504 Upstream Timeout: The provider timed out.
  • 500 CONTENT_EXTRACTION_FAILED or INTERNAL_ERROR: Unexpected parsing/processing errors.

Error responses (Problem Details)

All Booking.com hotel endpoints return errors using RFC 7807 Problem Details.

{
  "type": "https://api.stayapi.com/errors/invalid-url",
  "title": "Invalid URL",
  "status": 400,
  "detail": "Parameter 'url' must be a full Booking.com hotel URL of the form https://www.booking.com/hotel/{cc}/{slug}.html.",
  "error_code": "INVALID_URL",
  "provided": "baan-coconut"
}

Media type: application/problem+json

Standard fields: type, title, status, detail

Extensions: error_code and any endpoint-specific fields

2xx policy: 2xx is returned only when data extraction succeeds.

Request 
curl -X GET "https://api.stayapi.com/v2/booking/hotel/details?hotel_id=1331780" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"
Response 
{
  "success": true,
  "hotel_id": "1331780",
  "data": {
    "hotel_name": "Hotel Meslay Republique",
    "description": null,
    "property_type": "HOTEL",
    "address": "3, rue Meslay",
    "city": "Paris",
    "country": "fr",
    "postal_code": "75003",
    "latitude": 48.8673,
    "longitude": 2.362240,
    "star_rating": 3,
    "review_score": 8.1,
    "review_count": 3022,
    "check_in_time": "15:00",
    "check_out_time": "12:00",
    "main_photo_url": "https://cf.bstatic.com/xdata/images/hotel/square200/44369511.jpg?k=…&o=",
    "page_name": "meslay-republique"
  },
  "message": "Success",
  "retrieved_at": "2026-04-01T12:00:00Z"
}
Browse documentation