Booking.com Market Supply & Facet Census

Get a complete, structured picture of the accommodation supply in any Booking.com market. Give it a city, a region, a district, an airport, a landmark or a coordinate pair, and you get back every labelled option Booking.com publishes for that market — star ratings, review-score bands, property types, neighbourhoods, brands, facilities, room features, meal plans, reservation policies, payment options, sustainability certification and accessibility — each one with the number of properties behind it and its share of the market. It is the market-structure dataset that hotel revenue teams, short-let operators, investors and analysts normally assemble by hand, and it lands in one pass per market.

What you can do with it

• Size a market before you enter it. How many 4-star hotels, apartments and vacation homes compete in Austin — and what fraction of the market each segment actually is.
• Benchmark quality and price positioning. Compare the review-score band distribution of 50 cities at once, and see which markets are dominated by 8-and-above supply.
• Map brand and chain penetration. Which hotel brands are present in each market, and how many properties each of them runs there.
• Track supply over time. Schedule it weekly with the same stay window and watch new supply, neighbourhood shifts and the free-cancellation share move.
• Find where the supply actually is. Neighbourhood and distance-from-centre breakdowns show you which parts of a city carry the inventory.
• Build filters and taxonomies for your own product. Every option arrives with the exact identifier Booking.com uses for it, so you can drive your own segmented searches from this dataset.

What you get

Two kinds of row. One per option in every group:

{
  "recordType": "facetOption",
  "destination": "Austin",
  "destinationType": "CITY",
  "checkIn": "2026-09-10",
  "checkOut": "2026-09-12",
  "nights": 2,
  "leadTimeDays": 42,
  "adults": 2,
  "rooms": 1,
  "children": 0,
  "facetGroup": "class",
  "facetCategory": "class",
  "facetTitle": "Property rating",
  "optionId": "class=4",
  "optionValue": "4",
  "optionLabel": "4 stars",
  "count": 371,
  "countNotAutoextended": 0,
  "sharePctOfMarket": 57.43,
  "discoveredUnder": null,
  "destinationTotalProperties": 646,
  "currency": "USD",
  "actorRunId": "PBs4Xk2mZq7vN9Ld",
  "scrapedAt": "2026-09-01T09:14:22.531Z"
}

And one rollup row per market, from the same pass, abridged here:

{
  "recordType": "marketSummary",
  "destination": "Austin",
  "destinationType": "CITY",
  "checkIn": "2026-09-10",
  "checkOut": "2026-09-12",
  "totalProperties": 646,
  "facetGroupsReturned": 24,
  "facetOptionsReturned": 130,
  "emptyFacetGroups": ["price"],
  "starClassMix": [
    { "optionId": "class=3", "label": "3 stars", "count": 143, "sharePct": 22.14 },
    { "optionId": "class=4", "label": "4 stars", "count": 371, "sharePct": 57.43 },
    { "optionId": "class=5", "label": "5 stars", "count": 10, "sharePct": 1.55 }
  ],
  "reviewScoreBands": [
    { "optionId": "review_score=90", "label": "Wonderful: 9+", "count": 221, "sharePct": 34.21 },
    { "optionId": "review_score=80", "label": "Very Good: 8+", "count": 363, "sharePct": 56.19 }
  ],
  "propertyTypeMix": [
    { "optionId": "ht_id=204", "label": "Hotels", "count": 204, "sharePct": 31.58 },
    { "optionId": "ht_id=220", "label": "Vacation Homes", "count": 236, "sharePct": 36.53 }
  ],
  "districtMix": [
    { "optionId": "di=4838", "label": "South Austin", "count": 89, "sharePct": 13.78 }
  ],
  "freeCancellationShare": 90.87,
  "freeCancellationCount": 587,
  "availableOnlyCount": 646,
  "brandsReturned": 20,
  "topBrands": [
    { "chainCode": "1851", "brandName": "Hampton by Hilton", "count": 9 },
    { "chainCode": "2117", "brandName": "Hilton Garden Inn", "count": 8 }
  ],
  "currency": "USD",
  "scrapedAt": "2026-09-01T09:14:22.531Z"
}

Input reference

Setting	Type	Default	What it does
Destinations	list of text	["Austin"]	The markets to profile. Place names (Austin, Lisbon, Bali) or coordinate pairs (30.2672,-97.7431). Up to 200 entries.
Destination type	choice	City	How to read your place names: City, Region, Country, District, Airport, Landmark or Coordinates. A coordinate pair is always read as coordinates.
Check-in date	date	45 days out	First night of the stay the market is profiled for. Left empty, it rolls forward from the day the run starts, so a schedule never drifts into the past.
Check-out date	date	check-in + 2 days	Last day of the stay.
Adults	integer	2	Party size the counts are conditioned on. Max 30.
Rooms	integer	1	Rooms the counts are conditioned on. Max 30.
Children	integer	0	Children in the party. Max 10.
Children's ages	list of text	[]	One age per child, 0–17. Booking.com decides availability by a child's age, so fill this in whenever Children is above zero.
Only these option groups	list of text	[] (all)	Leave empty for every group Booking.com publishes. Narrow the dataset by naming groups such as class, review_score, ht_id, di, chaincode, hotelfacility, mealplan, fc. Up to 24.
Expand truncated option lists	boolean	false	Booking.com trims long lists to their leading entries. Switch this on to profile each market again inside the segments below, which brings more of the tail into view.
Segments used to expand the tail	list of text	["class=3","class=4","class=5"]	Segments each market is re-profiled inside, written as group=value. Up to 12.
Add a rollup row per market	boolean	true	Adds the one-row market summary shown above. It comes out of the same pass, so it is free.
Maximum markets per run	integer	100	Safety cap on how many markets one run profiles. Max 500.
Maximum lookups per run	integer	600	Hard budget for the run. One market needs one lookup, plus one more per segment when tail expansion is on. The run stops cleanly once the budget is spent. Max 6000.
Markets in parallel	integer	4	How many markets are profiled at the same time. Max 8.
Currency	text	USD	Three-letter code the market is read in.
Language	text	en-us	Language of the option labels. Labels outside English come back as Booking.com writes them.
Browse from country	text	""	Country to appear to browse from, as a two-letter code.

Output fields

Option rows (recordType: "facetOption")

Field	Type	Meaning
destination	text	The market as you entered it
destinationType	text	How it was read (CITY, REGION, LATLONG …)
checkIn, checkOut, nights, leadTimeDays	date / number	The stay window the counts are conditioned on
adults, rooms, children	number	The party the counts are conditioned on
facetGroup	text	Group identifier, e.g. class, ht_id, chaincode
facetCategory	text	Booking.com's own grouping label
facetTitle	text	Human-readable group name, e.g. "Property rating"
optionId	text	The exact identifier for the option, e.g. chaincode=1851
optionValue	text	Just the value part, e.g. 1851
optionLabel	text	The published label, e.g. "Hampton by Hilton"
count	number	Properties in this market carrying the option
countNotAutoextended	number	Booking.com's stricter count for the same option, published as-is
sharePctOfMarket	number	count as a percentage of the market total; null when the total is unknown
discoveredUnder	text	null for the market-wide pass; otherwise the segment that surfaced the option, and the count is a count within that segment
destinationTotalProperties	number	Properties listed in this market when the market was read
currency, actorRunId, scrapedAt	text	Run provenance

Market rollup rows (recordType: "marketSummary")

Field	Type	Meaning
totalProperties	number	Properties listed in the market for your stay window
facetGroupsReturned, facetOptionsReturned	number	How much structure the market published
facetGroupNames, emptyFacetGroups	list	Every group present, and which of them published no options
starClassMix	list	Star rating → count and share
reviewScoreBands	list	Review-score band → count and share
propertyTypeMix	list	Hotels, apartments, vacation homes … → count and share
districtMix	list	Neighbourhood → count and share
bedroomCountMix, mealPlanMix	list	Bedroom counts and meal arrangements → count and share
freeCancellationShare, freeCancellationCount, freeCancellationOptionId	number / text	Share of the market offering free cancellation, and the option it was measured from
availableOnlyCount, availableOnlyOptionId	number / text	Properties Booking.com counts as available for your dates
brandsReturned, topBrands	number / list	Brands present, biggest first, with their identifier and property count
tailPreFiltersApplied	list	Segments used for tail expansion on this market
currency, actorRunId, scrapedAt	text	Run provenance

Pricing

Pay per result. There is one charge, and it applies each time a row is written to the dataset — an option row or a market rollup row, at the same price. There is no second, more expensive tier, because there is nothing behind one that would cost more: an entire market's structure, roughly 110 to 130 rows of it, is produced in a single pass. Single-tier pricing is deliberate here, and it makes this the cheapest row in the family.

Charge	Applies when	Price
Result row	Any option row or market rollup row is written	$0.0003 per row ( $0.30 per 1,000 rows )

Worked example. 100 markets, roughly 110 rows each, is about 11,000 rows — around $3.30 for a full 100-city supply census. Turning on tail expansion with three segments profiles each market four times, so budget accordingly.

Limits and what this actor cannot do

• Counts are conditioned on the dates and the party you choose. Booking.com only counts properties that can actually host your stay, so a census for a peak-season weekend is a different (and smaller) market than the same city mid-week. Keep the stay window fixed when you compare markets or track one over time.
• Booking.com's own market total moves between identical searches. We have seen the same city report 632, 646 and 647 within minutes. Treat totalProperties as a snapshot observation, not an audited figure — and treat small movements between runs as noise.
• Long option lists are truncated by Booking.com. Brands, neighbourhoods and property types are published as a leading slice, not a full list. Tail expansion recovers more of it, but it cannot be proven exhaustive — no complete list of every brand in a market is available.
• No price bands. Price is a slider on Booking.com, not a list of options, so the group is published with nothing in it. It is reported in emptyFacetGroups and produces no rows. If you need prices, use a price-oriented actor instead.
• Brand identifiers are market-local. They were confirmed in one market only, so join on brandName and treat chainCode as a convenience within that market.
• This profiles markets, not single properties. There is no way to point it at one hotel: a single-property lookup on Booking.com returns an identity and no market structure at all, so that destination type is deliberately not offered.
• A market that has no availability for your dates publishes nothing. That is reported in the log as an empty market, and it is a real answer, not a failure.
• Speed depends on the size of the job and on how quickly Booking.com answers. No fixed throughput is promised.
• Booking.com's terms restrict automated access. You are responsible for using this data lawfully and in line with the source site's own terms.

FAQ

Do I need a Booking.com account? No. No account, no login, no personal details — set your destinations and run it.

How many rows should I expect per market? Around 110 to 130 for a mid-sized city, plus one rollup row. Small markets publish fewer groups and fewer options, large ones publish more.

Can I schedule it? Yes. Pin the check-in and check-out dates if you want a like-for-like series, or leave them empty and every run will profile the same rolling window (45 days out, two nights), which is usually what you want for a supply trend.

Is the data complete? The set of groups is complete — you get every group Booking.com publishes for the market. The options inside the long groups are not: Booking.com trims them. Tail expansion recovers more of the tail and labels where each option came from, but neither we nor anyone else can prove a brand or neighbourhood list is exhaustive.

Why is a share sometimes null instead of 0? Because a 0 would look like a finding. When the market total is unknown or zero, the share is genuinely unknowable, and the field says so rather than inventing a number.

What does discoveredUnder mean? It is null for the market-wide pass, where count is a count across the whole market. When it names a segment, that row was found while profiling that segment and its count is a count within the segment — the two are not interchangeable.

Can I profile a whole country? Yes — set the destination type to Country. Bear in mind that the counts are still availability-conditioned, and that very large markets truncate their long option lists more aggressively than cities do.