Conventions

A handful of rules hold across the whole API. Read these once and the rest of the docs make more sense.

Owned-only: the API only touches maps you own

The API is owned-only. A key reaches exactly the maps its account owns — resolved from ZeeMaps ownership records, not from sharing.

Maps shared with your account (even at admin level) are not reachable through the API. They won’t appear in GET /maps, and any {map_id} your account doesn’t own returns 404.
Because map_id and marker_id are sequential, enumerable integers, “not owned” is deliberately reported as 404 NOT_FOUND (not 403) so the API never confirms the existence of another account’s resources.
The same rule covers async jobs: GET /jobs/{job_id} returns a job only if its map is owned by the caller, otherwise 404.

If you need to operate on a map owned by someone else, have them transfer ownership to your account.

“Map” and “marker” are the only object names

The API speaks in maps and markers:

A map is the user-facing container you create, share, and render.
A marker is a single point, region, or circle on a map.

These are the only nouns in requests, responses, and errors. (Internally ZeeMaps uses different legacy names, but those never appear in the API — don’t expect or send them.)

Identifiers

map_id and marker_id are positive integers — the underlying ZeeMaps record IDs — and are returned as JSON numbers, not strings.
share_id is the integer id of a share. job_id is an opaque string.

Units

Distances for circle / pinned_circle markers and near= search use radius_unit, one of miles (default) or km.
Kilometre inputs are normalized to miles internally, so a circle’s stored radius reflects the converted value. Send radius_unit: "km" and the API does the conversion for you.
near=lat,lng,radius_km in marker search takes its radius in kilometres (it’s named radius_km).

All timestamps are RFC 3339 / ISO 8601 strings in UTC, e.g. 2026-06-30T17:00:00Z. A map’s updated_at reflects the last time its markers or regions changed (falling back to created_at for a map with no writes yet).

Data formats

Request and response bodies are JSON (Content-Type: application/json), except bulk import, which also accepts text/csv and multipart/form-data.
PATCH requests are partial updates — send only the fields you want to change.
A marker’s color is a palette color name (e.g. "blue", "Hot Pink"), never a hex value. See Recipes → Categories and colors.

Errors · Authentication · Recipes