Name: Booking.com Live Hotels API: real-time rates
Brand: flightpowers
SKU: api-flightpowers-booking-hotels
Availability: InStock
Author: API Market

Matan Rabi

# Booking.com Live Hotels API

## Overview

The Booking.com Live Hotels API reads Booking.com at request time and returns live hotel rates and availability as flat JSON. Three endpoints look a hotel up by the name a person would type, search a destination with Booking.com's own filters and sort, and list every room of one property with its type, meal plan, guest capacity and price. Results carry the stay total, review score and count, coordinates, an image and the booking link.

It is built for travel apps and meta-search sites, rate-parity and revenue management teams, travel agents and AI trip planners. Every endpoint takes `proxy_country`, so you can see the rate a guest booking from another country is quoted, and sold-out or unmatched hotels come back in the same shape as a hit with `available: false`.

## Features

*   **3 endpoints**: hotel by name, destination search and rooms of one property.
*   **Name resolution**: `by-name` matches the hotel for you and returns `matched_name` and `match_confidence`.
*   **Destination filters**: 24 Booking.com filters, `budget_per_night` and Booking.com's sort.
*   **Room-level prices**: room type, meal plan, guests and price for every room.
*   **Geo pricing**: `proxy_country` prices the stay as seen from another market.
*   **Rate limit**: 1 request per second.

## Use Cases

*   **Travel apps**: show live hotel prices and booking links.
*   **Rate parity monitoring**: compare a property's price across countries.
*   **Revenue management**: track competitor rates for your dates.
*   **AI trip planners**: answer hotel questions with real rates.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/flightpowers/booking-hotels
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Hotel by name

Availability and the stay total for one named hotel. Name resolution included; matched_name says what it matched.

**Method:** `POST`

**Endpoint:** `/v1/hotels/by-name`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| hotel_name | body | The hotel name as a person would type it | string | Yes | - | - |
| area | body | City or region to disambiguate a generic name | string | No | - | - |
| checkin_date | body | Check-in date (YYYY-MM-DD, must be in the future) | string | Yes | - | - |
| checkout_date | body | Check-out date (YYYY-MM-DD, must be in the future) | string | Yes | - | - |
| adults | body | Number of adults | integer | No | 2 | - |
| children | body | Number of children | integer | No | 0 | - |
| currency | body | Currency code, e.g. USD, EUR | string | No | USD | - |
| proxy_country | body | Two-letter lowercase country code (us, de, il). Routes the request through a residential proxy in that market, so you see the rate a guest there is quoted. | string | No | - | - |
| free_cancellation | body | - | boolean | No | - | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/flightpowers/booking-hotels/v1/hotels/by-name' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"hotel_name": "Hotel Arts Barcelona", "checkin_date": "2027-06-15", "checkout_date": "2027-06-18", "adults": 2, "currency": "EUR"}'
```

**Example Response (200 OK, trimmed):**

Long lists are cut to their first items and long text is shortened.

```json
{
  "name": "Hotel Arts Barcelona",
  "matched_name": "Hotel Arts Barcelona",
  "match_confidence": 1,
  "matched_via": "name",
  "available": true,
  "price_string": "€ 2,376",
  "price": 2376,
  "review_score": null,
  "review_count": 939,
  "room_type": "Scenic Double Room",
  "image_url": "https://cf.bstatic.com/xdata/images/hotel/square240/836056401.webp?k=2d190c7305dc0c8147852c96e1829ae0b278514ce73bbcc46f573e1e524ba570&o=",
  "link": "https://www.booking.com/hotel/es/arts-barcelona.html?aid=304142&label=gen173nr-10CAQoggJCC2hvdGVsXzE0NzEzSDFYBGg6iAEBmAEzuAEHyAEM2AED6AEB-AEBiAIBqAIBuAKik4HXBsACAdICJDYxNWMxMzIzLWZkNjQtNGI0NC04NWE2LTNiMzMxMDk3YTZiNdgCAeACAQ&ucfs=1&arphpl=1&checkin=2027-06-15&checkout=2027-06-18&dest_id=14713&dest_ty...",
  "nights": 3,
  "adults": 2,
  "children": null,
  "latitude": 41.38721727474228,
  "longitude": 2.196072041988373,
  "retrieved_at": "2026-10-27T06:50:12.938Z"
}
```

#### 2. Destination search

Search a destination with Booking.com filters; ranked properties with prices, review scores, coordinates and links.

**Method:** `POST`

**Endpoint:** `/v1/hotels/search`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| destination | body | Free text: "Paris", "Tokyo Shibuya", "Hilton NYC" | string | Yes | - | - |
| checkin_date | body | Check-in date (YYYY-MM-DD, must be in the future) | string | Yes | - | - |
| checkout_date | body | Check-out date (YYYY-MM-DD, must be in the future) | string | Yes | - | - |
| adults | body | Number of adults | integer | No | 2 | - |
| children | body | Number of children | integer | No | 0 | - |
| currency | body | Currency code, e.g. USD, EUR | string | No | USD | - |
| budget_per_night | body | Max price per night, in the currency you set | number | No | - | - |
| proxy_country | body | Two-letter lowercase country code (us, de, il). Routes the request through a residential proxy in that market, so you see the rate a guest there is quoted. | string | No | - | - |
| sort | body | Booking.com's own sort | string | No | - | - |
| filters | body | Booking.com filters (24) | array of string | No | - | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/flightpowers/booking-hotels/v1/hotels/search' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"destination": "Lisbon", "checkin_date": "2027-06-15", "checkout_date": "2027-06-18", "adults": 2, "currency": "EUR", "filters": ["free_cancellation", "review_score_8"]}'
```

**Example Response (200 OK, trimmed):**

Long lists are cut to their first items and long text is shortened.

```json
{
  "destination": "Lisbon",
  "checkin_date": "2027-06-15",
  "checkout_date": "2027-06-18",
  "applied_filters": [
    "free_cancellation",
    "review_score_8"
  ],
  "budget_per_night": null,
  "properties": [
    {
      "name": "Hotel Avenida Park",
      "price_string": "€252",
      "price": 252,
      "review_score": 8.8,
      "review_count": 1577,
      "room_type": "Twin Room",
      "location": "Avenidas Novas, Lisbon",
      "image_url": "https://cf.bstatic.com/xdata/images/hotel/square240/493800060.webp?k=835c5b30d1ad90f39c992c3b56bed1150cf9727a560a14202eeaae3eadd5ccba&o=",
      "link": "https://www.booking.com/hotel/pt/avenida-parque.html?aid=304142&label=mkt123sc-a463a218-33cc-48ee-b0d1-d1de4828e763&ucfs=1&arphpl=1&checkin=2027-06-15&checkout=2027-06-18&group_adults=2&req_adults=2&no_rooms=1&group_children=0&req_children=0&hpos=1&hapos=1&sr_order=popularity&nflt=fc%3D2%3Breview_sc...",
      "nights": 3,
      "adults": 2,
      "children": null,
      "latitude": 38.72817713553036,
      "longitude": -9.149523228406906,
      "retrieved_at": "2026-10-27T06:50:21.741Z"
    },
    {
      "name": "Ouro Rossio Hotel",
      "price_string": "€365",
      "price": 365,
      "review_score": 9.3,
      "review_count": 711,
      "room_type": "Standard Double or Twin Room",
      "location": "Santa Maria Maior, Lisbon",
      "image_url": "https://cf.bstatic.com/xdata/images/hotel/square240/898047865.webp?k=0735a7fec6f9c8e4191baca4afc5d01c2653a0d6bba3073c305aada2bb4715e4&o=",
      "link": "https://www.booking.com/hotel/pt/ouro-rossio.html?aid=304142&label=mkt123sc-a463a218-33cc-48ee-b0d1-d1de4828e763&ucfs=1&arphpl=1&checkin=2027-06-15&checkout=2027-06-18&group_adults=2&req_adults=2&no_rooms=1&group_children=0&req_children=0&hpos=2&hapos=2&sr_order=popularity&nflt=fc%3D2%3Breview_score...",
      "nights": 3,
      "adults": 2,
      "children": null,
      "latitude": 38.7125711,
      "longitude": -9.1389291,
      "retrieved_at": "2026-10-27T06:50:21.741Z"
    }
  ],
  "retrieved_at": "2026-10-27T06:50:21.741Z"
}
```

#### 3. Rooms of one property

Every room in one property with room type, meal plan, guest capacity and price.

**Method:** `POST`

**Endpoint:** `/v1/hotels/rooms`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| hotel_booking_id | body | Booking.com path ID, e.g. it/boffenigoboutiquegarda: the part of a by-name or search result's link between /hotel/ and .html | string | Yes | - | - |
| checkin_date | body | Check-in date (YYYY-MM-DD, must be in the future) | string | Yes | - | - |
| checkout_date | body | Check-out date (YYYY-MM-DD, must be in the future) | string | Yes | - | - |
| adults | body | Number of adults | integer | No | 2 | - |
| children | body | Number of children | integer | No | 0 | - |
| currency | body | Currency code, e.g. USD, EUR | string | No | USD | - |
| proxy_country | body | Two-letter lowercase country code (us, de, il). Routes the request through a residential proxy in that market, so you see the rate a guest there is quoted. | string | No | - | - |
| free_cancellation | body | - | boolean | No | - | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/flightpowers/booking-hotels/v1/hotels/rooms' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"hotel_booking_id": "it/boffenigoboutiquegarda", "checkin_date": "2027-06-15", "checkout_date": "2027-06-18", "adults": 2, "currency": "EUR"}'
```

**Example Response (200 OK, trimmed):**

Long lists are cut to their first items and long text is shortened.

```json
{
  "hotel_booking_id": "it/boffenigoboutiquegarda",
  "checkin_date": "2027-06-15",
  "checkout_date": "2027-06-18",
  "booking_url": "https://www.booking.com/hotel/it/boffenigoboutiquegarda.html?checkin=2027-06-15&checkout=2027-06-18&dest_type=hotel&group_adults=2&group_children=0&no_rooms=1&sb_price_type=total&sr_order=popularity&selected_currency=EUR",
  "rooms": [
    {
      "room_type": "Classic Double Room",
      "room_economy": "Wonderful breakfast included",
      "guests": 2,
      "price_as_number": 766,
      "price": "€ 766",
      "retrieved_at": "2026-10-27T06:50:37.969Z"
    },
    {
      "room_type": "Classic Double Room",
      "room_economy": "Wonderful breakfast included",
      "guests": 1,
      "price_as_number": 536,
      "price": "€ 536",
      "retrieved_at": "2026-10-27T06:50:37.969Z"
    }
  ],
  "retrieved_at": "2026-10-27T06:50:37.969Z"
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the body holds the result. |
| 400 | Bad Request | The body is not valid JSON, a required field is missing, or a date is not in YYYY-MM-DD format. |
| 401 | Unauthorized | The `x-api-market-key` header is missing, invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The path, or the item you asked for, does not exist. |
| 429 | Too Many Requests | You sent more than 1 request per second, or you used all 10 calls of the Free plan. |
| 500 | Internal Server Error | Something failed on the provider side. Retry after a short delay. |
| 503 | Service Unavailable | The service or its data source is temporarily unavailable. Retry with backoff. |

## Rate Limits

You can send up to 1 request per second. Free includes 10 calls (a 7-day trial), PRO includes 2,000 calls a month for $10, ULTRA includes 6,500 calls a month for $30 and MEGA includes 25,000 calls a month for $75. Requests above the limit return `429 Too Many Requests`; throttle your requests, back off before retrying, and honour the `Retry-After` header when it is present.

## FAQ

*   **How do I get a `hotel_booking_id` for `/v1/hotels/rooms`?**
    Take it from the `link` of a by-name or search result: it is the country and property part of the URL, for example `it/boffenigoboutiquegarda`.

*   **What does `available: false` mean?**
    The hotel is sold out for those dates or no property matched the name; the other fields are `null`.

*   **Is `price` per night?**
    No. `price` is the total for the stay in the currency you asked for; `price_string` is the same amount as Booking.com shows it.

*   **Why can a call take several seconds?**
    Every call reads Booking.com live; room lists take the longest.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Live Booking.com rates as flat JSON. Look a hotel up by name, search a destination with 24 filters, and price a room as seen from another country.