GET

Hotel Photos API

Get a hotel's full photo gallery. Each photo includes signed, ready-to-use image URLs at three sizes.

URLs are signed and ready to use

Booking's image CDN requires a signed token on every image URL — unsigned URLs return 401 Unauthorized. All URLs returned here carry that token. The token is size-independent, so you can swap the size segment (square200 / square600 / max1024x768) in any URL and it will still load.

Overview

The Hotel Photos endpoint accepts a hotel_id and returns the property's full photo gallery. Each item has a photo_id and three signed URLs: thumbnail_url (square200), medium_url (square600), and large_url (max1024x768). The gallery is available even for hotels with no current availability.

Endpoint URL

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

Parameters

Parameter	Type	Required	Description
hotel_id	string	Required	Booking.com hotel ID (e.g., `1331780`). Convert a Booking URL first with the URL to Hotel ID endpoint.

Response fields

Each entry in the photos array contains:

photo_id — Booking's numeric photo identifier.
thumbnail_url — signed URL, square200 size.
medium_url — signed URL, square600 size.
large_url — signed URL, max1024x768 size.

Top level also includes photo_count and retrieved_at. The first photo in the array is the hotel's main photo (the same image as main_photo_url on the Hotel Details endpoint).

Error handling and status codes

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

400 MISSING_PARAMETER: hotel_id is required.
400 INVALID_HOTEL_ID: hotel_id must be numeric.
400 INVALID_PARAMETERS: the url param is not accepted — convert it first with URL to Hotel ID.
404 Not Found: Upstream indicates the hotel is missing.
503 Service Unavailable: Upstream rate-limited/maintenance (may include Retry-After).
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/photos?hotel_id=1331780" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

const response = await fetch("https://api.stayapi.com/v2/booking/hotel/photos?" +
  new URLSearchParams({
    hotel_id: "1331780"
  }), {
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
});

const data = await response.json();
console.log(data.photos[0].large_url);

import requests

url = "https://api.stayapi.com/v2/booking/hotel/photos"
headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

params = {"hotel_id": "1331780"}
response = requests.get(url, headers=headers, params=params)
data = response.json()
print(f"{data[\"photo_count\"]} photos")
print(data["photos"][0]["large_url"])

Response

{
  "success": true,
  "hotel_id": "1331780",
  "photos": [
    {
      "photo_id": "141411508",
      "thumbnail_url": "https://cf.bstatic.com/xdata/images/hotel/square200/141411508.jpg?k=…&o=",
      "medium_url": "https://cf.bstatic.com/xdata/images/hotel/square600/141411508.jpg?k=…&o=",
      "large_url": "https://cf.bstatic.com/xdata/images/hotel/max1024x768/141411508.jpg?k=…&o="
    }
  ],
  "photo_count": 34,
  "message": "Success",
  "retrieved_at": "2026-04-01T12:00:00Z"
}

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