Clustering
Summarizing dense map viewports into hex-grid (H3) markers instead of a flat list.
For dense map viewports, the search can summarize stays into hex-grid (H3) markers instead of returning a flat list. Clustering is off by default.
Modes
Set the cluster parameter:
cluster | Behavior | Use case |
|---|---|---|
false (or omitted) | Flat list of stays | Default; lists and simple grids |
auto | Server clusters dense viewports into H3 markers when it judges clustering useful | Map UIs that want automatic behavior |
true | Forces H3 clustering whenever geometrically possible; on tight viewports clamps to the deepest resolution (r8, ~460 m hexes) | Map UIs that always want markers |
top | Returns ONE representative stay (the best-rated) per H3 cell in results[] (each tagged with cellId), paginated over cells. Unlike auto/true, it keeps clustering at tight zoom instead of falling back to a flat list | A lightweight "top stays per area" overview |
precision optionally overrides the H3 cell size for cluster=top; it is ignored (not validated) for other modes. Range 4 (~22 km hexes) to 8 (~460 m hexes). When omitted, the server derives a sensible resolution from the viewport (one step coarser than count-clustering); an explicit value also forces top mode on tight viewports that would otherwise return a flat list. meta.clustering.mode reports which mode ran (for example, top for a cluster=top request).
Clustered responses
auto/true responses include a separate clusters[] array; sparse stays continue to flow through results[], and a stay never appears in both. Each cluster includes count, location.bounds, location.coordinates, and a pre-built _links.expand URL for drilling into that cluster's area.
Structural blockers — ID lookups, center+radius searches without a bounding box, and requests without a resolvable viewport — always return a flat list even with cluster=true or cluster=top.
What to read next
- Pagination — paging clustered results and
meta.total - Response & supplier model —
clusters[]vsresults[] - Search Accommodation — the
clusterandprecisionparams