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.
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 live (non-trashed) library; required when they have multiple.
Library to cluster assets from. Optional if the user has a single live (non-trashed) 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.
Which assets to include, based on album membership: in_album returns assets filed into at least one album; not_in_album returns assets in no album at all — the ones still waiting to be organized; all returns both.
Filter by album membership in general, rather than by membership of one specific album. This filter is independent of album_id, but combining not_in_album with album_id is contradictory and returns 422. Defaults to all.
Filter to 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).
Filter to 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