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). A viewport whose min_longitude exceeds max_longitude (crossing the antimeridian) returns no cells — split it into two requests client-side. To list the individual assets behind a cell, call list_assets with a tighter bounding box over the same filters.
Query Parameters
Map viewport as 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 (antimeridian-crossing) returns no cells — split it client-side.
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.
Return only assets that are in the album with this ID.
Return only assets containing a face belonging to this person.
Only include assets captured strictly after this instant (ISO 8601; exclusive). Same awareness/offset semantics as on list_assets.
Only include assets captured strictly before this instant (ISO 8601; exclusive). Same awareness/offset semantics as on list_assets.
Which set of assets to cluster: live (default — excludes trashed assets), trashed (only trashed assets), or all (both).
live, trashed, all Response
Successful Response
Non-empty grid cells within the requested viewport. Not paginated: the list is capped at 1000 cells and a denser viewport returns 422 instead — coarsen cell_size or zoom in.