Booking Hotels

Search Booking.com by destination, or collect details for known hotels by URL or ID. Each Dataset item can include property details, photos, facilities, reviews, nearby places, rooms, availability, and rates.

Choose how to find hotels

Your starting point	Use	The Actor returns
A city, area, landmark, airport, or hotel name	destination and stay	Matching properties and, when available, rooms and rates for the stay
One or more known properties	hotels	The exact properties identified by Booking.com URL or numeric ID

Use one route in a new run. If you provide both, the destination search takes precedence.

Search a destination and check a stay

Use exact dates in YYYY-MM-DD format, or dates relative to the UTC run date. Relative dates keep a saved input useful for later runs.

{
  "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"]
  }
}

The filters in this example keep four- and five-star hotels with a guest score of at least 8 and free Wi-Fi.

Collect known hotels

Use a Booking.com URL or numeric hotel ID when you do not need a destination search:

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

Add stay when you also need current availability. Add results.includeReviews: true when you need individual guest reviews.

Check one known hotel with prices and reviews

{
  "hotels": [
    "https://www.booking.com/hotel/jp/park-tokyo.html"
  ],
  "stay": {
    "checkIn": "60 days",
    "checkOut": "63 days",
    "adults": 2,
    "childrenAges": [4, 9],
    "rooms": 1,
    "currency": "JPY"
  },
  "results": {
    "includeReviews": true,
    "maxReviewsPerHotel": 10
  },
  "language": "en-us"
}

Settings such as maxHotels and sortBy apply only to destination searches.

Search for one named hotel

A hotel name can also be a destination. This route can return the availableRooms field shown in the output reference.

{
  "destination": "Park Hotel Tokyo, Tokyo",
  "stay": {
    "checkIn": "60 days",
    "checkOut": "63 days",
    "adults": 2,
    "childrenAges": [],
    "rooms": 1,
    "currency": "JPY"
  },
  "results": {
    "maxHotels": 1,
    "sortBy": "recommended",
    "includeReviews": false,
    "maxReviewsPerHotel": 20
  },
  "language": "en-us"
}

Input reference

Use a destination search or a list of exact hotels. Choose one method for a new run. Dates can be exact, such as 2027-12-15, or relative to the UTC run date, such as 60 days.

New runs in Apify Console start with the Tokyo destination and stay values from the first destination example. API calls do not add a destination or stay.

Complete destination-search input

Select only the filters that match your search. A narrow combination can return no hotels.

{
  "destination": "Tokyo, Japan",
  "stay": {
    "checkIn": "60 days",
    "checkOut": "63 days",
    "adults": 2,
    "childrenAges": [],
    "rooms": 1,
    "currency": "JPY"
  },
  "results": {
    "maxHotels": 1,
    "sortBy": "guest_rating",
    "includeReviews": false,
    "maxReviewsPerHotel": 20
  },
  "filters": {
    "starRatings": [
      "4",
      "5"
    ],
    "minimumTotalPrice": 30000,
    "maximumTotalPrice": 60000,
    "minimumReviewScore": 8,
    "freeCancellation": true,
    "distanceFromCenter": "3km",
    "propertyTypes": [
      "Hotels"
    ],
    "neighborhoods": [
      "Shinjuku Ward"
    ],
    "mealPlans": [
      "Breakfast included"
    ],
    "hotelAmenities": [
      "Free WiFi"
    ],
    "roomAmenities": [
      "Balcony"
    ],
    "bedPreferences": [
      "Double bed"
    ],
    "brands": [
      "Mitsui Garden"
    ],
    "sustainabilityCertified": true,
    "minimumBedrooms": 1,
    "minimumBeds": 1,
    "travelPurpose": "business"
  },
  "language": "en-us",
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}

Main fields

Field	Type	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. Repeated entries are processed in input order and can produce repeated records.	["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	{"useApifyProxy":true}	Optional connection settings for the run.	{"useApifyProxy":true}

For the recommended nested form, provide one of destination or hotels. If you provide both, destination search takes precedence and hotels is not used. Filters, results.maxHotels, and results.sortBy apply only to destination searches. Unknown fields are accepted, but they do not affect the run. In the legacy flat form, search takes precedence when both search and urls are present, so the URL list is not used for that request.

stay

Field	Type	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 checkout date. 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. A price filter without currency is ignored.	"JPY"

results

Field	Type	Default	How to use it	Example
maxHotels	integer	20	Limit a text search to at most 250 hotels. Use 0 to collect all available results. 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	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.

Hotel record reference

The Actor saves one Dataset record for each returned hotel. Optional sections appear only when they apply. A null value means that Booking.com did not return a value. An empty array means that the section returned no items.

The examples shorten long arrays to one item. Review objects can contain the guestName and guestAvatarUrl keys. The JSON examples omit both keys because their values can identify individual guests. The exact keys remain in the field reference, so the shortened JSON is not an all-fields record.

Hotel details and rates

This example includes property details, rates, facilities, photos, food, reviews, and stay availability.

Room availability from a search

The direct-hotel record above did not contain availableRooms, and its matchingUnitConfiguration was null. This destination-search example shows both fields.

{
  "hotelId": 179801,
  "name": "Park Hotel Tokyo",
  "availability": {
    "price": {
      "originalTotal": {
        "amount": "189789.09090909088",
        "currency": "JPY",
        "formatted": "¥189,789"
      }
    },
    "matchingUnitConfiguration": {
      "name": "Twin Room - Non Smoking - Above 26th floor",
      "area": null,
      "beds": 2,
      "bedrooms": 0,
      "livingRooms": 0,
      "kitchens": 0,
      "bathrooms": 0,
      "unitCount": 1,
      "units": [
        {
          "unitTypeId": 8,
          "name": "Twin Room - Non Smoking - Above 26th floor",
          "unitCount": 1
        }
      ]
    }
  },
  "availableRooms": [
    {
      "roomId": "17980105",
      "name": "Twin Room - Non Smoking - Above 26th floor",
      "occupancy": 2,
      "beds": 2,
      "bathrooms": 0
    }
  ]
}

Retained hotel projection

This selected-field projection matches retained Actor output captured on 31 July 2026. The shown values are unchanged. That run had results.includeReviews: false, so review fields are absent.

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

Top-level field reference

Field	Type	Meaning
recordType	string	Always hotel.
status	string	complete when all requested sections succeeded; otherwise partial.
failedSections	string[]	Requested sections that did not complete.
inputSource	string	The URL, hotel ID, or destination that produced the record.
hotelId	integer	Booking.com hotel ID.
name	string	Hotel name.
url	string or null	The hotel URL from your input. A numeric hotel ID gives https://www.booking.com/hotel/<id>. Search results have null.
accommodationType	string or null	Property type.
address, city, countryCode	string or null	Property address data.
latitude, longitude	number or null	Property coordinates.
starRating	object or null	Star value and symbol.
preferredLevel	string or null	Booking.com preferred-property level.
isTravelProud, isSustainable	boolean	Property markers.
description, summary	string or null	Property description and summary.
reviewScore, reviewsCount	number or null	Overall guest score and advertised review count.
ratingScores	object[]	Scores for categories such as cleanliness and location.
houseRules	object or null	Check-in and check-out times.
facilities	object[]	Hotel facilities and charge information.
photos	object[]	Original photo URLs, text, types, and tags.
surroundings	object or null	Nearby places grouped by category.
meals	object[]	Available meal details.
restaurants	object[]	On-site restaurants and cuisines.
legalInfo	object or null	Trader and company contact data.
finePrints	string[]	Important notices and conditions.
languagesSpoken	string[]	Spoken languages. This list can be empty.
featuredReviews	object[]	Reviews selected for the hotel profile.
reviews	object[]	Requested individual reviews. Present only when reviews are enabled.
reviewsMetadata	object	Review count and completion data. Present only when reviews are enabled.
stayRequest	object	Resolved dates, guests, rooms, and currency. Present when complete dates are supplied.
availability	object	Structured stay availability and rates. Present when complete dates are supplied.
pricing	object	Compact price data from the hotel or search result.
availableRooms	object[]	Matching rooms from a destination result when Booking.com supplies them.
scrapedAt	string	UTC time when the record was created.

Possible failedSections values are propertyInfo, reviewSummary, facilities, photos, surroundings, food, availability, location, and reviews.

Nested field reference

Path	JSON type and presence	Child contract
starRating	object or null	value: number; symbol: string
ratingScores	object array	Each item has string name and translation, plus number value and reviewsCount.
houseRules	object or null	checkinFrom, checkinUntil, checkoutFrom, and checkoutUntil are strings or null.
facilities	object array	id and groupId: number; title: string; chargeMode: string or null
photos	object array	id: number; url: string; altText and type: string or null; tags: object array
photos[].tags	object array	Each item has number id and string name.
surroundings	object or null	Category keys map to arrays of {name: string, distance: string}.
meals	object array	mealType: string; price, style, and cuisine: string or null
restaurants	object array	name: string; cuisines: string array
legalInfo	object or null	isTrader: boolean; companyName, email, and phone: string or null
featuredReviews	object array	Each item uses the review contract below.
reviews	optional object array	Present only when reviews are enabled. Each item uses the review contract below.
Review item	object	score and date: number; positiveText and negativeText: string; reviewUrl, title, guestName, guestCountry, language, guestAvatarUrl, and guestCountryName: string or null; isTranslatable: boolean or null
reviewsMetadata	optional object	advertisedCount: number or null; returnedCount: number; complete: boolean; topicIds: string array
stayRequest	optional object	checkIn and checkOut: string; adults, children, and rooms: number; childrenAges: number array; currency: string or null
availability	optional object	hasAvailability: boolean; price: object or null; freeCancellationAvailable: boolean or null; rateComponents: object array; matchingUnitConfiguration: object or null
availability.price	object or null	total: money object; originalTotal and averagePerNight: money object or null; chargesText and taxExceptionsText: string array
Money object	object	amount and currency: string; formatted: string or null
availability.rateComponents	object array	roomId: string; occupancy: number; mealPlanId: number or null; policyGroupId, packageId, and freeCancellationUntil: string or null; finalPrice: money object; originalPrice: money object or null
availability.matchingUnitConfiguration	object or null	name: string; area: string or null; beds, bedrooms, livingRooms, kitchens, bathrooms, and unitCount: number; units: object array
availability.matchingUnitConfiguration.units	object array	unitTypeId and unitCount: number; name: string
pricing	optional object	displayPrice, currency, and averagePricePerNight: string; showFreeCancellation: boolean
availableRooms	optional object array	Each item has string roomId and name, plus number occupancy, beds, and bathrooms.

reviewsMetadata.returnedCount equals the saved reviews.length. reviewsMetadata.complete is true when the requested review limit was reached or all reviews made available by Booking.com were collected. The advertised review count can still be higher than returnedCount.

The surroundings keys depend on the property. The example includes landmarks, restaurants, cafeBars, supermarkets, beaches, skiLifts, bus, metro, train, and airports. Empty arrays are valid. Search prices and room lists also depend on the selected dates and Booking.com availability.

Availability and result behaviour

• results.maxHotels: 0 and results.maxReviewsPerHotel: 0 collect all currently available results and can make a run much longer.
• Review arrays stay inside their hotel record. If a record becomes too large, review collection stops and the record is marked partial.
• 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.
• 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.
• The Actor does not verify that checkout is after check-in.
• 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.
• Booking.com can change or remove public values. Prices, room availability, ratings, and review totals are point-in-time results.