# Booking.com API — hotel search, prices, availability, guest reviews & destination lookup (booking.com, global coverage)

> Search hotels in a destination for given dates (25 hotels per page, with prices, review scores, photos, room configurations). Supports sorting, price/star/rating/amenity filters and paging. Pass ?include_facets=1 to list every available filter and sorter for the destination.
> ReefAPI engine `booking` · 5 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/booking/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /booking/v1/hotels/search — 2 credits
Search hotels in a destination for given dates (25 hotels per page, with prices, review scores, photos, room configurations). Supports sorting, price/star/rating/amenity filters and paging. Pass ?include_facets=1 to list every available filter and sorter for the destination.

**Parameters:**
- `query` (string, optional) — Destination as free text — city, region or landmark. Provide query OR dest_id+dest_type.
- `dest_id` (string, optional) — Advanced: Booking destination ID (unambiguous — bypasses the free-text lookup). Pair with dest_type.
- `dest_type` (string, optional) — Advanced: the destination's type as Booking labels it. One of: city, region, district, landmark, airport, hotel, country.
- `checkin` (string, optional) — Check-in date (YYYY-MM-DD). Always pass real dates — prices and availability depend on them.
- `checkout` (string, optional) — Check-out date (YYYY-MM-DD).
- `adults` (integer, optional, default 2) — Number of adult guests.
- `rooms` (integer, optional, default 1) — Number of rooms.
- `children_ages` (string, optional) — Comma-separated ages of children (e.g. '5,9'). Adds child occupancy to the search/price. Omit for adults-only.
- `currency` (string, optional, default "EUR") — Price currency (ISO code: EUR, USD, GBP, TRY…).
- `page` (integer, optional, default 1) — Result page (25 hotels each). pagination.total in the response tells you how many results exist.
- `sort_by` (string, optional) — Sort order. One of: top_picks (default), price (low→high), price_desc (high→low), review_score, best_reviewed_and_price, stars_desc, stars_asc, distance.
- `min_price` (number, optional) — Minimum price per stay, in the chosen currency.
- `max_price` (number, optional) — Maximum price per stay, in the chosen currency.
- `min_rating` (number, optional) — Minimum guest review score (1–10). E.g. 8 = 'Very good+'.
- `stars` (string, optional) — Star rating(s) to include, comma-separated (1–5). E.g. '4,5' = 4- and 5-star only.
- `free_cancellation` (boolean, optional, default false) — Only properties offering free cancellation.
- `breakfast_included` (boolean, optional, default false) — Only properties where breakfast is included.
- `amenities` (string, optional) — Advanced: comma-separated Booking filter IDs (from ?include_facets=1 → available_filters). E.g. hotelfacility-107 (pool), roomfacility-11 (air-con).
- `include_facets` (boolean, optional, default false) — Also return available_sorters + available_filters for the destination (filter/sort discovery).
- `include_raw` (boolean, optional, default false) — Include Booking's full raw payload per item (large). Default off — the normalized fields cover the common cases.

**Returns:** items[]{hotel_id, page_name, name, description, url, location, price{amount, amount_unformatted, currency}, price_before_discount, review_score{score, review_count, label}, star_rating, photo, room_configurations, policies, badges} + count (25/page) + pagination{per_page, total, offset} + (with include_facets) available_sorters[] + available_filters[]

**Example request body:**
```json
{
  "dest_id": "-755070",
  "dest_type": "city",
  "checkin": "2026-08-01",
  "checkout": "2026-08-03"
}
```

### POST /booking/v1/hotels/detail — 3 credits
Full hotel record: summary, rating breakdown, facilities, room types, surroundings, FAQ.

**Parameters:**
- `page_name` (string, optional) — REQUIRED for hotels/detail & hotels/reviews (with country_code): the hotel's URL slug — booking.com/hotel/<country_code>/<page_name>.html. Copy page_name + country_code straight from a hotels/search result item (or pass the item's full url as hotel_url). A numeric hotel_id alone does NOT work — Booking detail pages are addressed by this slug.
- `country_code` (string, optional) — REQUIRED with page_name (for hotels/detail & hotels/reviews): the 2-letter country in the hotel URL (booking.com/hotel/<country_code>/…). Comes from the hotels/search result item alongside page_name.
- `hotel_url` (string, optional) — Full hotel URL (alternative to page_name+country_code) — the url field of a hotels/search result item.
- `checkin` (string, optional) — Check-in date (YYYY-MM-DD). Always pass real dates — prices and availability depend on them.
- `checkout` (string, optional) — Check-out date (YYYY-MM-DD).
- `adults` (integer, optional, default 2) — Number of adult guests.
- `rooms` (integer, optional, default 1) — Number of rooms.
- `currency` (string, optional, default "EUR") — Price currency (ISO code: EUR, USD, GBP, TRY…).

**Returns:** hotel_id + name + summary + rating_breakdown + facilities[] + room_types[] + surroundings + faq[]

### POST /booking/v1/hotels/availability — 2 credits
Visible room blocks (room, occupancy, price, cancellation policy, meal plan) for a destination's top hotel on given dates.

**Parameters:**
- `query` (string, optional) — Destination free text. Provide query OR dest_id+dest_type.
- `dest_id` (string, optional) — Advanced: Booking destination ID (unambiguous — bypasses the free-text lookup). Pair with dest_type.
- `dest_type` (string, optional) — Advanced: the destination's type as Booking labels it. One of: city, region, district, landmark, airport, hotel, country.
- `checkin` (string, optional) — Check-in date (YYYY-MM-DD). Always pass real dates — prices and availability depend on them.
- `checkout` (string, optional) — Check-out date (YYYY-MM-DD).
- `hotel_id` (integer, optional) — Pin to one hotel from the search results (default: the top result).
- `adults` (integer, optional, default 2) — Number of adult guests.
- `rooms` (integer, optional, default 1) — Number of rooms.
- `children_ages` (string, optional) — Comma-separated ages of children (e.g. '5,9'). Adds child occupancy to the search/price. Omit for adults-only.
- `currency` (string, optional, default "EUR") — Price currency (ISO code: EUR, USD, GBP, TRY…).

**Returns:** room_blocks[]{room_id, occupancy, final_price, original_price, free_cancellation_until, cancellation_type, available_count_hint, breakfast_included, meal_plan} + hotel_id + is_available + price

### POST /booking/v1/hotels/reviews — 1 credit
Paginated, deduped guest reviews for one hotel (score, title, pros/cons text, owner reply, room type, stay dates, reviewer country, photos). Fetches ALL reviews by default; supports sorting and keyword search. The response also lists the available review filters (by score / language / customer type / season / topic).

**Parameters:**
- `page_name` (string, optional) — REQUIRED for hotels/detail & hotels/reviews (with country_code): the hotel's URL slug — booking.com/hotel/<country_code>/<page_name>.html. Copy page_name + country_code straight from a hotels/search result item (or pass the item's full url as hotel_url). A numeric hotel_id alone does NOT work — Booking detail pages are addressed by this slug.
- `country_code` (string, optional) — REQUIRED with page_name (for hotels/detail & hotels/reviews): the 2-letter country in the hotel URL (booking.com/hotel/<country_code>/…). Comes from the hotels/search result item alongside page_name.
- `hotel_url` (string, optional) — Full hotel URL (alternative to page_name+country_code).
- `max_reviews` (integer, optional) — How many reviews to fetch. Omit for ALL reviews (paged 25/page internally).
- `sort_by` (string, optional) — Review order. One of: most_relevant (default), newest, oldest, highest_score, lowest_score.
- `keyword` (string, optional) — Only reviews mentioning this keyword (free-text search).
- `review_page_size` (integer, optional, default 25) — Advanced: reviews per internal page (Booking caps at 25).
- `hotel_id` (integer, optional) — Advanced: Booking hotel ID.

**Returns:** reviews[]{review_id, score, reviewed_date, reviewed_date_iso, language, title, positive_text, negative_text, partner_reply, reviewer_country, reviewer_country_code, guest_type, customer_type, room_type, stay{checkin, checkout, nights}, photos[], helpful_votes, review_url} + unique_count + total_count + rating_breakdown[] + language_filters[] + available_filters{score_buckets, customer_types, time_of_year, topics} + available_sorters[]

### POST /booking/v1/destinations/autocomplete — 1 credit
Resolve a free-text place ('Paris', 'Maldives', 'JFK') into the destination IDs the other actions take (dest_id + dest_type), with country, coordinates and how many hotels/homes each match has. Use this first when you only have a place name.

**Parameters:**
- `query` (string, required) — Place to look up — city, region, landmark, airport or country.
- `limit` (integer, optional, default 10) — Max suggestions to return (1–20).

**Returns:** suggestions[]{dest_id, dest_type, label, name, region, country_code, latitude, longitude, hotel_count, home_count, photo} + count

**Example request body:**
```json
{
  "query": "Paris"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=booking
- Human docs page: https://reefapi.com/docs/booking
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt