Cluster assets by map location
Clusters geotagged assets in a map viewport (bounding box) onto a grid of square cells and returns one entry per non-empty cell — its centroid, asset count, and a representative cover asset. Use this to render a clustered map or to count how many photos fall in each part of a viewport at a chosen zoom granularity.
The result is a single un-paginated list capped at 1000 cells; a viewport that is too dense at the given cell_size returns 422 (coarsen cell_size or zoom in). To list the individual assets behind a cell, call list_assets with a tighter bounding box over the same filters. Album and person filters compose using AND. person_id is a deprecated alias for one person_ids value; do not supply both person parameters.
Query parameters
Bounding-box (map viewport) location filter: four comma-separated decimal-degree numbers min_longitude,min_latitude,max_longitude,max_latitude (west,south,east,north), e.g. -77.1,38.9,-77.0,39.0. A box whose min_longitude exceeds max_longitude crosses the antimeridian: it selects the band running east from min_longitude over ±180° to max_longitude, so there is no need to split it client-side. Longitude order is therefore significant — transposed corners read as a crossing viewport, not as an error. A viewport 360° or wider must be sent as the full range -180,...,180,..., which the wrapped form cannot express.
Bounding-box (map viewport) location filter: four comma-separated decimal-degree numbers min_longitude,min_latitude,max_longitude,max_latitude (west,south,east,north), e.g. -77.1,38.9,-77.0,39.0. A box whose min_longitude exceeds max_longitude crosses the antimeridian: it selects the band running east from min_longitude over ±180° to max_longitude, so there is no need to split it client-side. Longitude order is therefore significant — transposed corners read as a crossing viewport, not as an error. A viewport 360° or wider must be sent as the full range -180,...,180,..., which the wrapped form cannot express.
Grid cell edge in decimal degrees — the clustering granularity. Larger values give coarser clusters; the client maps map-zoom to cell_size. Must be at least 0.0001 (~11 m).
Grid cell edge in decimal degrees — the clustering granularity. Larger values give coarser clusters; the client maps map-zoom to cell_size. Must be at least 0.0001 (~11 m).
Library to cluster assets from. Optional if the user has a single library; required when they have multiple.
Library to cluster assets from. Optional if the user has a single library; required when they have multiple.
Return only assets in this album — the album's album_ ID, not its name.
Return only assets in this album — the album's album_ ID, not its name.
Deprecated compatibility alias for a single person_ids value.
Deprecated compatibility alias for a single person_ids value.
Cluster only assets containing faces belonging to ALL of these people (intersection, not union). Accepts up to 200 IDs across repeated person_ids= query params or comma-delimited values. Person IDs are carried by the entries of an asset's people field (returned with include=people).
Cluster only assets containing faces belonging to ALL of these people (intersection, not union). Accepts up to 200 IDs across repeated person_ids= query params or comma-delimited values. Person IDs are carried by the entries of an asset's people field (returned with include=people).
Only include assets captured strictly after this instant (ISO 8601; exclusive). Convert a relative or natural-language date phrase ('in 2023') into an explicit bound before sending. local_datetime is the photo's wall-clock time in the device's own timezone. Naive values compare directly against local_datetime. Timezone-aware values: assets with a known offset are compared in UTC (local_datetime - offset); assets without an offset fall back to wall-clock comparison against local_datetime.
Only include assets captured strictly after this instant (ISO 8601; exclusive). Convert a relative or natural-language date phrase ('in 2023') into an explicit bound before sending. local_datetime is the photo's wall-clock time in the device's own timezone. Naive values compare directly against local_datetime. Timezone-aware values: assets with a known offset are compared in UTC (local_datetime - offset); assets without an offset fall back to wall-clock comparison against local_datetime.
Only include assets captured strictly before this instant (ISO 8601; exclusive). Same conversion requirement and awareness/offset semantics as local_datetime_after.
Only include assets captured strictly before this instant (ISO 8601; exclusive). Same conversion requirement and awareness/offset semantics as local_datetime_after.
Which set of assets to cluster: live (default — excludes trashed assets), trashed (only trashed assets), or all (both).
Which set of assets to cluster: live (default — excludes trashed assets), trashed (only trashed assets), or all (both).
Response
Successful Response