GET
# Hotel Details API
v2

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

#### 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
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

```json
{
  "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"
}
```

```json
{
  "type": "https://api.stayapi.com/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Hotel not found for the requested hotel ID. The hotel may have been removed or the ID is incorrect.",
  "error_code": "NOT_FOUND",
  "provider": "booking"
}
```