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. Rating and media type can further restrict the cluster.
Authorizations
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.
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.
all, in_album, not_in_album Filter to assets where ALL of these people appear (intersection, not union), by a face or a body linked to them unless person_link says otherwise. 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 one media class (image or video). Omit to include both images and videos.
Which media class an asset belongs to.
Every image format is image and every video format is video. An asset's
class is fixed by the file originally uploaded, so an edited photo is still
image.
image, video Return assets whose effective rating is one of these exact values. Values must be integers from 0 through 5; 5 is a favorite. 0 matches every unrated form: an explicit zero, a null or legacy out-of-range effective rating, or an asset with no metadata. Accepts repeated ratings= parameters or one comma-delimited value. Omit the parameter for no rating filter.
0 <= x <= 5Only 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.