Places

Fields marked * are required. Updates keep every field they are not given. An AI app can ask vritto_describe for the same details, filtered to what its connection may use.

Place`place`

A saved place in the user's atlas. The same operations reach custom lists of places (type 'list') and logged visits to saved places (type 'visit').

places_findFindthrough vritto_find

Read Places: one place by placeKey (with its revision and visits), saved places filtered by text, category, list, role or favorite, several placeKeys, places near coordinates, the custom lists (type 'list'), or visits (type 'visit') by place, trip, dates or rating. No filter gives the saved places and lists.

Note: One placeKey returns the place with its revision and visits. type 'list' reads the custom lists; type 'visit' reads visits by place, trip, dates or rating.

Field	Type	Description
type	one of place, list, visit	Which records to read: 'place' (default), 'list' or 'visit'.
placeKey	string	One place, with its logged visits; with type 'visit', that place's visits.
placeKeys	list of string	Resolve several places to display summaries; missing or archived ones are flagged.
query	string	Text to match a place's name, label, address or tags.
category	one of medical, dining, grocery, shopping, property, automotive, lodging, travel, personal, event, entertainment, general	Place category, derived from the capturing module (multi-valued on a place).
listId	string	Only places in this custom list.
role	one of home, work	Only home or work.
favorite	boolean	Only favorites.
moduleId	string	Recents captured by this module (in-context picker).
archived	boolean	List archived/removed places.
coordinates	object	Saved places near here, nearest first.
coordinates.lat*	number	Latitude.
coordinates.lng*	number	Longitude.
radiusMeters	number	With coordinates: search radius in meters (default 2000).
tripId	string	Type 'visit': only this trip's visits.
from	string	Type 'visit': earliest visit date, inclusive.
to	string	Type 'visit': latest visit date, inclusive. ALWAYS pass from/to when the question concerns a period.
minRating	number	Type 'visit': only visits rated at least this.
limit	integer	Max results.

Example input

{
  "query": "coffee",
  "category": "dining"
}

places_addCreate or Updatethrough vritto_create or vritto_update

Add one record: a visit to a saved place (type 'visit': placeKey, visitedOn, rating only when stated; an id updates that visit), a custom list (type 'list': name, emoji), or a private place Google doesn't know (name, address). Resolve or save the place first; save Google places with places_upsertPlaceFromProvider.

Note: Google places are saved in the app; this adds a private place (name, address), a custom list (type 'list'), or a visit to a saved place (type 'visit').

Field	Type	Description
type	one of place, list, visit	Record type: 'place' (default) a saved place in the atlas; 'list' a custom list of places; 'visit' a logged visit to a saved place.
name	string	A place's or list's name. Required for those.
address	object	Type 'place': its address.
address.formatted*	string	Full formatted address.
address.locality	string	City/locality.
address.region	string	State/region.
address.postalCode	string
address.countryCode	string	ISO 3166-1 alpha-2, e.g. US.
coordinates	object	Type 'place': where it is.
coordinates.lat*	number	Latitude.
coordinates.lng*	number	Longitude.
emoji	string	Type 'list': an emoji.
description	string	Type 'list': what it collects.
id	string	Type 'visit': an existing visit to update. Omit to log a new one.
placeKey	string	Type 'visit': the saved place visited.
visitedOn	string	Type 'visit': local date YYYY-MM-DD ('yesterday' resolves against the user's timezone). Required to log one.
kind	one of see, do, shop, other	Type 'visit': defaults to 'see'.
rating	number	Type 'visit': 1–5, halves allowed, ONLY when the user stated it.
note	string
photoAssetIds	list of string	Type 'visit': Files asset IDs of photos from the visit.
tripId	string	Type 'visit': resolve via trips_find.
personIds	list of string	Type 'visit': companion People IDs.
journalEntryId	string	Type 'visit': Journal entry ID this visit links to.

Example input

{
  "type": "visit",
  "placeKey": "google:ChIJN1t_tDeuEmsRUsoyG83frY4",
  "visitedOn": "2026-09-20",
  "kind": "see",
  "rating": 4.5
}

places_changeUpdatethrough vritto_update

Change one place by placeKey with its expectedRevision from places_find: label (null clears), favorite, role home or work (null clears), tags (REPLACES the set), archived, or listId with member to add it to or take it off a list. Type 'visit' changes a visit by its id.

Note: A place change needs its expectedRevision from places_find. tags replaces the whole set; read the place first.

Field	Type	Description
type	one of place, list, visit	Record type: 'place' (default) a saved place in the atlas; 'list' a custom list of places; 'visit' a logged visit to a saved place.
placeKey	string	The place to change; for a visit, its place.
expectedRevision	integer	Required for a place: its current revision from places_find.
label	string	The place's own label, which wins over the provider name; null clears it.
favorite	boolean
role	one of	The user's home or work (the previous holder is released); null clears it.
tags	list of string	Full replacement list of tags; [] clears them.
archived	boolean	Archive (remove) or restore the place without deleting it.
listId	string	A custom list, with member.
member	boolean	With listId: true adds the place to the list, false takes it off.
id	string	Type 'visit': the visit to change.
visitedOn	string	Type 'visit': local date YYYY-MM-DD ('yesterday' resolves against the user's timezone). Required to log one.
kind	one of see, do, shop, other	Type 'visit': defaults to 'see'.
rating	number	Type 'visit': 1–5, halves allowed, ONLY when the user stated it.
note	string
photoAssetIds	list of string	Type 'visit': Files asset IDs of photos from the visit.
tripId	string	Type 'visit': resolve via trips_find.
personIds	list of string	Type 'visit': companion People IDs.
journalEntryId	string	Type 'visit': Journal entry ID this visit links to.

Example input

{
  "placeKey": "google:ChIJN1t_tDeuEmsRUsoyG83frY4",
  "favorite": true,
  "expectedRevision": 3
}

places_removeDeletethrough vritto_delete

Remove one record on an explicit ask: a visit by id (archived), or a place by placeKey with its expectedRevision (archived, restorable with places_change). Get ids from places_find.

Note: A visit by id; a place by placeKey and expectedRevision is archived, restorable with places_change.

Field	Type	Description
type	one of place, list, visit	Record type: 'place' (default) a saved place in the atlas; 'list' a custom list of places; 'visit' a logged visit to a saved place.
id	string	The visit to remove.
visitId	string	Older name for id.
placeKey	string	The place to archive.
expectedRevision	integer	With placeKey: the place's current revision.

Kept in the Vritto app

places_searchSuggestions: Google Maps content may only be shown with a Google map, inside the app.
places_getPlaceDetails: Google Maps content may only be shown with a Google map, inside the app.
places_upsertPlaceFromProvider: Google Maps content may only be shown with a Google map, inside the app.
places_geocode: Google Maps content may only be shown with a Google map, inside the app.
places_reverseGeocode: Google Maps content may only be shown with a Google map, inside the app.
places_getTimeZone: Google Maps content may only be shown with a Google map, inside the app.
places_estimateTravelTime: Google Maps content may only be shown with a Google map, inside the app.
places_listPlaceReferences: Internal links between records that each module keeps in step itself.

Places

Placeplace

Kept in the Vritto app

Place`place`