assets

Cluster assets by map location

Changed on

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.

get/api/assets/geo-clusters

Request

  • Base URL: https://api.gumnut.ai
  • URL: https://api.gumnut.ai/api/assets/geo-clusters
  • Auth: one of:
    • HTTP bearer
    • HTTP bearer

Query parameters

bboxstring required

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.

cell_sizenumber required

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_idstring nullable

Library to cluster assets from. Optional if the user has a single live (non-trashed) library; required when they have multiple.

album_idstring nullable

Return only assets in this album — the album's album_ ID, not its name.

album_filter'all' | 'in_album' | 'not_in_album'

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.

person_idsstring[] nullable

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).

media_type'image' | 'video'

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.

Filter to one media class (image or video). Omit to include both images and videos.

ratingsinteger[] nullable

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.

local_datetime_afterstring date-time nullable

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.

local_datetime_beforestring date-time nullable

Only include assets captured strictly before this instant (ISO 8601; exclusive). Same conversion requirement and awareness/offset semantics as local_datetime_after.

state'live' | 'trashed' | 'all'

Which set of assets to cluster: live (default — excludes trashed assets), trashed (only trashed assets), or all (both).

Response

Successful Response

Changes

  • 7c2860d9eb88Revision changes
    • info

      added the new optional query request parameter media_type

    • info

      added the new optional query request parameter ratings

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

  • ea5b49a160c8Revision changes
    • info

      added the new optional query request parameter album_filter