Search assets

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

Natural-language search text. It runs independently through dense visual retrieval and authoritative-metadata full-text retrieval, then the ranked lists are fused. Concrete visual concepts work well in the dense stage, while exact metadata terms can match through full-text search.

Resolve album and people names to IDs and pass them as album_id and person_ids; convert date phrases like 'in 2023' into ISO 8601 bounds on local_datetime_after/local_datetime_before (here, 2023-01-01 and 2024-01-01). None of those belong in query.

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

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.

Center point of a radius location filter: two comma-separated decimal-degree numbers longitude,latitude, e.g. -77.05,38.95. Supply with radius.

Radius of the center location filter, in meters (greater than 0, at most 50,000).

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.

1-indexed page number; increment it to fetch subsequent pages. search_assets pages by number rather than by cursor. A search with a content criterion ranks a fixed top-200 candidate population by relevance, so pages beyond that population are empty. A structured-filter-only search (album, people, date range — no content criterion) returns the full matching set newest-first, paginated without that cap.

Maximum number of results per page (1–200). Defaults to 20.