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:

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

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

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