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 availability search, enter destination and stay dates. A destination without complete dates is accepted and completes without results. If both a destination and hotel references are present, the destination takes precedence, matching the original flat-input behavior.

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.

For the recommended nested input, use either destination or hotels, not both. Existing integrations that use the original flat API remain supported. 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
  }
}

Existing API clients can keep sending the original flat input without a migration. For example:

{
  "urls": ["179801", "not-a-booking-url"],
  "includeReviews": false,
  "maxReviews": 20,
  "language": "en-us"
}

Each value in urls is resolved independently. A malformed or unavailable reference does not reject valid siblings.

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. Partial or omitted dates are accepted; without both dates, no availability search is run.	{"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. Filters are ignored when destination search is not selected.	{"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}

For the recommended nested form, provide one of destination or hotels. Filters, results.maxHotels, and results.sortBy apply only to destination searches. Unknown fields are retained for forward compatibility. In the legacy flat form, search takes precedence when both search and urls are present, matching the original Actor behavior.

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 an exact or relative date. Relative dates are resolved when the run starts; date ordering remains upstream-owned for compatibility.	"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. A price filter without currency is ignored.	"JPY"

results

Field	Type	API default	How to use it	Example
maxHotels	integer	20	Limit a text search to at most 250 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, up to 1000. Use 0 to collect all available reviews.	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. The price filter is used only when both bounds and stay.currency are present.	30000
maximumTotalPrice	number	none	Set the highest total price for the full stay. Incomplete price filters are ignored.	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. Names that are unavailable or ambiguous are ignored without failing the run.

Legacy flat API compatibility

The following original top-level fields remain accepted for existing API and CLI integrations. New integrations may use the nested fields above.

Legacy field	Maps to	Legacy default
urls	Specific hotel references	none
search	Destination text	none
maxResults	Maximum search results; 0 means all available	20
checkIn, checkOut	Stay dates passed through to Booking.com	none
adults	Adult guests	2
children	Child count	0
childrenAges	Child ages	none
rooms	Room count	1
sortBy	relevance, rating_highest, rating_lowest, newest_first, or oldest_first	relevance
includeReviews	Include individual reviews	true
maxReviews	Reviews per hotel; 0 means all available	20
filterStarRating	Star-rating filter	none
filterPrice	{min,max,currency} total-price filter	none
filterReviewScore	Review-score bucket such as 8+	none
filterPropertyType	Property type IDs or values	none
filterNeighborhood	District IDs or values	none
filterMeals	Meal-plan IDs or values	none
filterFacilities	Hotel facility IDs or values	none
filterRoomFacilities	Room facility IDs or values	none
filterBedPreference	Bed preference IDs or values	none
filterBrands	Brand IDs or values	none
filterFreeCancellation	Require free cancellation	false
filterDistanceFromCenter	Maximum distance from center	none
filterSustainability	Require sustainability marker	false
filterNumberOfBedrooms	Minimum bedrooms	none
filterNumberOfBeds	Minimum beds	none
filterTravelPurpose	business or leisure	none
language	Result locale	en-us
proxyConfiguration	Apify connection settings	Apify Proxy enabled

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.
• Hotel URLs and IDs are handled independently. Malformed or unavailable references are skipped while valid siblings are still saved. If none can be returned, the run completes with zero records instead of discarding earlier work or changing a previously accepted input into a failed run.
• An omitted selection or an empty hotels/legacy urls list is a successful zero-work run that saves no records.
• 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.