# Booking Hotels Scraper - Most Comprehensive (`kaix/booking-hotel-scraper`) Actor

🔥 ~$0.1/1K hotels 🔥 Get hotel profiles, guest reviews, facilities, photos, nearby places, and stay availability by hotel or destination.

- **URL**: https://apify.com/kaix/booking-hotel-scraper.md
- **Developed by:** [Kai](https://apify.com/kaix) (community)
- **Categories:** E-commerce, Travel, Real estate
- **Stats:** 2 total users, 2 monthly users, 74.3% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.08 / 1,000 hotels

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Booking Hotels

Search a destination or collect details for specific Booking.com hotels. Results
can include property information, photos, facilities, nearby places, guest
reviews, stay availability, rooms, and rates.

### Search hotels

For a normal hotel search, enter `destination` and `stay` dates. You do not
need a hotel URL. You can then choose the result limit, sort order, and filters.

If you already know the exact hotels, use `hotels` instead of `destination`.
Add one or more Booking.com hotel URLs or numeric IDs. Dates are optional unless
you need current availability.

Use either `destination` or `hotels`, not both. Set `results.includeReviews` to
`true` to collect individual guest reviews.

### Quick start

Search a destination with stay details and optional filters. Relative dates are
resolved when the run starts, so this example remains ready to use:

```json
{
  "destination": "Tokyo, Japan",
  "stay": {
    "checkIn": "60 days",
    "checkOut": "63 days",
    "adults": 2,
    "childrenAges": [],
    "rooms": 1,
    "currency": "JPY"
  },
  "results": {
    "maxHotels": 10,
    "sortBy": "guest_rating",
    "includeReviews": false
  },
  "filters": {
    "starRatings": ["4", "5"],
    "minimumReviewScore": 8,
    "propertyTypes": ["Hotels"],
    "hotelAmenities": ["Free WiFi"]
  }
}
```

Get specific hotels by URL or numeric ID:

```json
{
  "hotels": [
    "https://www.booking.com/hotel/jp/park-tokyo.html"
  ],
  "results": {
    "includeReviews": false
  }
}
```

### Input

The examples in this section are input fragments. Start with `destination` and
`stay` for a search, or use `hotels` for exact properties. Dates can be exact,
such as `2027-12-15`, or relative to the UTC run date, such as `60 days`.
The Store form prefills a Tokyo example; API calls do not add a destination or
stay unless you provide them.

#### Main fields

| Field | Type | API default | How to use it | Example |
| --- | --- | --- | --- | --- |
| `destination` | string | none | Enter a city, area, landmark, airport, or hotel name to search. Add `stay` and leave `hotels` empty. | `"Tokyo, Japan"` |
| `stay` | object | none | Set dates and guests for availability. It is required with `destination` and optional with `hotels`. | `{"checkIn":"60 days","checkOut":"63 days"}` |
| `hotels` | string\[] | none | Add Booking.com hotel URLs or numeric IDs when you already know the exact hotels. Leave `destination` empty; duplicate references are saved once. | `["179801"]` |
| `results` | object | shown below | Set search result limits, ordering, and review collection. With hotel URLs or IDs, change only the review settings. | `{"maxHotels":10,"includeReviews":true}` |
| `filters` | object | none | Narrow a text search. Do not use active filters with hotel URLs or IDs. | `{"starRatings":["4","5"]}` |
| `language` | string | `en-us` | Choose the locale for returned text and localized filter labels. Common values are `en-us`, `en-gb`, `fr`, `de`, `es`, `it`, and `ja`. | `"fr"` |
| `proxyConfiguration` | object | Apify Proxy enabled | Leave the default for normal runs. Change it only when your Apify account requires different connection settings. | `{"useApifyProxy":true}` |

Provide exactly one of `destination` or `hotels`. Filters,
`results.maxHotels`, and `results.sortBy` apply only to destination searches.
Unknown fields are rejected so misspelled options do not silently change the
run.

#### `stay`

| Field | Type | API default | How to use it | Example |
| --- | --- | --- | --- | --- |
| `checkIn` | string | none | Choose an exact date as `YYYY-MM-DD`, or a date relative to the UTC run date using days, weeks, months, or years. | `"60 days"` |
| `checkOut` | string | none | Choose a date after `checkIn`, using the same exact or relative format. Relative dates are resolved when the run starts. | `"63 days"` |
| `adults` | integer | `2` | Set the number of adult guests for the whole stay, from 1 to 30. | `2` |
| `childrenAges` | integer\[] | `[]` | Add one age, from 0 to 17, for each child. The Actor derives the child count from this list; do not add a separate `children` field. | `[4,9]` |
| `rooms` | integer | `1` | Set the total number of rooms, from 1 to 30. Guests apply to the stay as a whole, not to individual rooms. | `2` |
| `currency` | string | none | Request stay prices in a three-letter uppercase currency. Set it when using total-price filters. | `"JPY"` |

#### `results`

| Field | Type | API default | How to use it | Example |
| --- | --- | --- | --- | --- |
| `maxHotels` | integer | `20` | Limit a text search to this many hotels. Use `0` to continue until the available result pages end. Do not change it for hotel URLs or IDs. | `10` |
| `sortBy` | string | `recommended` | Order text-search results by `recommended`, `guest_rating`, `price_lowest`, `distance`, `stars_highest`, or `stars_lowest`. Do not change it for hotel URLs or IDs. | `"guest_rating"` |
| `includeReviews` | boolean | `false` | Set `true` to add individual reviews to each hotel record. This works for searches and specific hotels. | `true` |
| `maxReviewsPerHotel` | integer | `20` | When reviews are enabled, stop after this many reviews per hotel. Use `0` to collect all available reviews; larger values can make runs much longer. | `50` |

#### `filters`

All filters apply only to `destination` searches.

| Field | Type | API default | How to use it | Example |
| --- | --- | --- | --- | --- |
| `starRatings` | string\[] | `[]` | Keep hotels with any selected star rating. Values are strings from `1` through `5`; you can select more than one. | `["4","5"]` |
| `minimumTotalPrice` | number | none | Set the lowest total price for the full stay. Also set `maximumTotalPrice` and `stay.currency`. | `30000` |
| `maximumTotalPrice` | number | none | Set the highest total price for the full stay. It must be at least the minimum; also set `minimumTotalPrice` and `stay.currency`. | `60000` |
| `minimumReviewScore` | integer | none | Keep hotels with a guest score at or above this whole number, from 5 through 9. | `8` |
| `propertyTypes` | string\[] | `[]` | Keep selected property types. Use full labels available for the same destination, stay, and language. | `["Hotels"]` |
| `neighborhoods` | string\[] | `[]` | Limit results to named neighborhoods or districts available for the destination. | `["Shinjuku Ward"]` |
| `mealPlans` | string\[] | `[]` | Keep stays offering the selected meal plans. Use the full localized labels. | `["Breakfast included"]` |
| `hotelAmenities` | string\[] | `[]` | Keep properties with the selected hotel-wide amenities. | `["Free WiFi"]` |
| `roomAmenities` | string\[] | `[]` | Keep stays with the selected in-room amenities. | `["Balcony"]` |
| `bedPreferences` | string\[] | `[]` | Request the selected bed option when it is available for the destination and stay. | `["Double bed"]` |
| `brands` | string\[] | `[]` | Keep hotels from the selected chains or brands available at the destination. | `["Mitsui Garden"]` |
| `freeCancellation` | boolean | `false` | Set `true` to keep stays that offer a free-cancellation option. | `true` |
| `distanceFromCenter` | string | none | Set the maximum distance from the destination center: `1km`, `3km`, or `5km`. | `"3km"` |
| `sustainabilityCertified` | boolean | `false` | Set `true` to keep properties marked with a sustainability certification. | `true` |
| `minimumBedrooms` | integer | none | For apartments or homes, require at least this many bedrooms, from 1 to 10. | `2` |
| `minimumBeds` | integer | none | Require at least this many beds, from 1 to 10. | `2` |
| `travelPurpose` | string | none | Set the stay context to `business` or `leisure`. | `"business"` |

Property, neighborhood, meal, amenity, bed, and brand names depend on the
destination, stay, and selected `language`. Copy the full localized label shown
in Booking.com's filters for the same search, such as `Hotels` or `Free WiFi`.
Matching ignores capitalization and extra spaces. If a name is not available,
the run stops with a clear message instead of returning unfiltered results.

### What you get

The Actor saves one record for each returned hotel.

#### Identity and completeness

| Field | Meaning |
| --- | --- |
| `recordType` | Always `hotel`. |
| `status` | `complete` when all requested sections were collected; otherwise `partial`. |
| `failedSections` | Sections that could not be collected safely. Empty on a complete record. |
| `inputSource` | The URL, hotel ID, or destination search that produced the record. |
| `hotelId` | Numeric Booking.com hotel ID. |
| `name` | Hotel name. |
| `url` | Booking.com hotel URL when available. |
| `scrapedAt` | UTC timestamp for when the record was created. |

`failedSections` can contain `propertyInfo`, `reviewSummary`, `facilities`,
`photos`, `surroundings`, `food`, `availability`, `location`, or `reviews`.

#### Property

| Field | Meaning |
| --- | --- |
| `accommodationType` | Property type, such as hotel or apartment. |
| `address`, `city`, `countryCode` | Property location. |
| `latitude`, `longitude` | Geographic coordinates when available. |
| `starRating` | Rating value and rating symbol. |
| `preferredLevel` | Preferred-property level when provided. |
| `isTravelProud` | Whether the property is marked Travel Proud. |
| `isSustainable` | Whether the property has a sustainability marker. |
| `description`, `summary` | Property description and short summary. |
| `houseRules` | Check-in and check-out times. |
| `legalInfo` | Trader status and available company contact details. |
| `finePrints` | Important property notices and conditions. |

#### Amenities and guest feedback

| Field | Meaning |
| --- | --- |
| `facilities` | Hotel facilities, including charge information when available. |
| `photos` | Original-size photo URLs, captions, types, and tags. |
| `surroundings` | Nearby places grouped by category, with distance text. |
| `meals` | Available meal information. |
| `restaurants` | On-site restaurants and cuisines. |
| `reviewScore`, `reviewsCount` | Overall guest score and advertised review count. |
| `ratingScores` | Category scores such as cleanliness, comfort, and location. |
| `featuredReviews` | Review highlights included with the hotel profile. |
| `reviews` | Individual reviews when `results.includeReviews` is `true`. |
| `reviewsMetadata` | Advertised, returned, and completion details for review collection. |

Each individual review can include its score, title, positive and negative
text, Unix timestamp in seconds, guest name and country, language, review
URL, and avatar URL. `reviewsMetadata` contains `advertisedCount`,
`returnedCount`, `complete`, and `topicIds`. `returnedCount` always matches the
saved `reviews` array. `complete: true` means the requested limit was reached
or all available reviews were collected; `advertisedCount` can still be larger
when you requested a smaller limit.

#### Stay and availability

| Field | Meaning |
| --- | --- |
| `stayRequest` | The dates, guests, rooms, and requested currency used for the availability check. Dates are always returned as absolute `YYYY-MM-DD` values. |
| `availability` | Whether a matching stay exists, structured prices, cancellation availability, rate components, and the matching room configuration. |
| `pricing` | Display price and average nightly price when provided with the search result. |
| `availableRooms` | Matching room IDs, names, occupancy, bed counts, and bathroom counts when available. |

Structured money objects inside `availability` contain a decimal `amount`,
`currency`, and optional formatted text. The compact `pricing` fields and meal
prices are formatted strings. When dates are supplied, `availability` is
always present. On a `complete` record, `hasAvailability: false` means no
matching stay was found for those dates and guests. If availability cannot be
interpreted safely, the record is `partial` and `failedSections` includes
`availability`.

Optional fields appear only when they apply. For example, `reviews` and
`reviewsMetadata` require `includeReviews: true`; `stayRequest` and
`availability` require `stay`. A `null` value means the field applies but no
reliable value was returned. An empty array means no items were returned for
that section.

#### Verified output

This trimmed selection came from a real Actor run on July 31, 2026:

```json
{
  "recordType": "hotel",
  "status": "complete",
  "failedSections": [],
  "hotelId": 179801,
  "name": "Park Hotel Tokyo",
  "city": "Tokyo",
  "countryCode": "jp",
  "starRating": {
    "value": 4,
    "symbol": "STARS"
  },
  "reviewScore": 9,
  "reviewsCount": 3489,
  "stayRequest": {
    "checkIn": "2026-09-29",
    "checkOut": "2026-10-01",
    "adults": 2,
    "children": 0,
    "childrenAges": [],
    "rooms": 1,
    "currency": "JPY"
  },
  "availability": {
    "hasAvailability": true,
    "price": {
      "total": {
        "amount": "97988.9328",
        "currency": "JPY",
        "formatted": "¥97,989"
      },
      "originalTotal": null,
      "averagePerNight": null,
      "chargesText": [],
      "taxExceptionsText": []
    },
    "freeCancellationAvailable": true,
    "rateComponents": [
      {
        "roomId": "17980101",
        "occupancy": 2,
        "mealPlanId": 2,
        "policyGroupId": "366275015",
        "packageId": "0",
        "finalPrice": {
          "amount": "97988.9328",
          "currency": "JPY",
          "formatted": null
        },
        "originalPrice": {
          "amount": "97988.9328",
          "currency": "JPY",
          "formatted": null
        },
        "freeCancellationUntil": "2026-09-27T15:00:00.000Z"
      }
    ],
    "matchingUnitConfiguration": {
      "name": "Queen Room - Non Smoking - Above 27th floor",
      "area": null,
      "beds": 1,
      "bedrooms": 0,
      "livingRooms": 0,
      "kitchens": 0,
      "bathrooms": 0,
      "unitCount": 1,
      "units": [
        {
          "unitTypeId": 9,
          "name": "Queen Room - Non Smoking - Above 27th floor",
          "unitCount": 1
        }
      ]
    }
  },
  "scrapedAt": "2026-07-31T13:43:40.200Z"
}
```

### Limits and expectations

- `results.maxHotels: 0` and `results.maxReviewsPerHotel: 0` continue until the
  currently available pages end and can make a run much longer.
- Review arrays stay inside their hotel record. Collection stops safely and
  marks the record `partial` before the dataset item becomes too large.
- A valid destination, filter combination, or dated stay can return no matching
  hotel. Dated hotel records report this with
  `availability.hasAvailability: false`.
- Every hotel URL or ID must first have a valid format. If some well-formed
  references cannot later be found, the remaining hotels are still saved. The
  run fails when none of the requested hotels can be returned.
- Guest counts apply to the stay as a whole. Room-by-room guest allocation is
  not supported.
- Results do not include every bookable rate plan, complete payment and
  cancellation terms, every tax schedule, or a checkout flow.
- Booker country, platform-specific rates, and membership deals cannot be
  selected independently.
- Flexible dates and coordinate-radius search are not input options.
- Review sorting, traveler filters, topic filters, and review-text search are
  not input options.
- Optional sections can be temporarily unavailable. Check `status` and
  `failedSections` before treating a hotel record as complete.

# Actor input Schema

## `destination` (type: `string`):

Enter a city, area, landmark, airport, or hotel name. Then choose check-in and check-out below. You do not need a hotel URL.

## `stay` (type: `object`):

Required for a destination search. Choose exact dates or dates relative to the run date. Dates are optional for specific hotels.

## `hotels` (type: `array`):

Use this instead of Destination when you already know the exact hotels. Add one or more Booking.com hotel URLs or numeric IDs. Dates are optional.

## `results` (type: `object`):

Set search result limits, ordering, and review collection. With hotel URLs or IDs, change only the review settings.

## `filters` (type: `object`):

Use these only for a destination or hotel-name search. Text labels must be available for the same search, stay, and language; capitalization and extra spaces are ignored.

## `language` (type: `string`):

Choose the locale for returned text and localized filter labels. You can enter another supported locale instead of the suggested values.

## `proxyConfiguration` (type: `object`):

Leave the default for normal runs. Change it only when your Apify account requires different connection settings.

## Actor input object example

```json
{
  "destination": "Tokyo, Japan",
  "stay": {
    "checkIn": "60 days",
    "checkOut": "63 days",
    "adults": 2,
    "childrenAges": [],
    "rooms": 1,
    "currency": "EUR"
  },
  "hotels": [
    "https://www.booking.com/hotel/jp/park-tokyo.html"
  ],
  "results": {
    "maxHotels": 10,
    "sortBy": "guest_rating",
    "includeReviews": true,
    "maxReviewsPerHotel": 50
  },
  "filters": {
    "starRatings": [
      "4",
      "5"
    ],
    "minimumReviewScore": 8,
    "freeCancellation": true
  },
  "language": "fr",
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `results` (type: `string`):

Link to every saved result.

## `hotels` (type: `string`):

Link to the saved dataset using the hotel view.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "destination": "Tokyo, Japan",
    "stay": {
        "checkIn": "60 days",
        "checkOut": "63 days",
        "adults": 2,
        "childrenAges": [],
        "rooms": 1
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("kaix/booking-hotel-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "destination": "Tokyo, Japan",
    "stay": {
        "checkIn": "60 days",
        "checkOut": "63 days",
        "adults": 2,
        "childrenAges": [],
        "rooms": 1,
    },
}

# Run the Actor and wait for it to finish
run = client.actor("kaix/booking-hotel-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "destination": "Tokyo, Japan",
  "stay": {
    "checkIn": "60 days",
    "checkOut": "63 days",
    "adults": 2,
    "childrenAges": [],
    "rooms": 1
  }
}' |
apify call kaix/booking-hotel-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=kaix/booking-hotel-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/pW7h7RXiZlmEXax4f/builds/K3FizK9WEcFQr6g7i/openapi.json