Places

A place is a spot the user named — home, work, the gym. They set its centre and radius on their Places page; you never see either.

What you receive is identity only:

{ "id": "9f2c…", "label": "Home", "kind": "home" }

No lat, no lon, no radiusM, anywhere in the API. This is the mechanism behind the product's central claim: your app can ask "are they home?" and act on the answer without ever learning where home is.

kind is one of home, work, school, gym, other, or null. Treat it as a hint for iconography, not as a guarantee — most users leave it unset.

You only see what was shared

Place visibility is per connection. When a user connects your app with a place-using scope, they tick which places you may ask about. They can change that set later from the connection detail, without re-minting your token — so your visible set can shrink between one call and the next.

There is no endpoint to list a user's places. You discover them by asking current-place and seeing what comes back, or by holding an id you were given earlier.

A place that wasn't shared with you is invisible in every direction: presence returns 404, current-place never names it, visits never label with it, and a rule pointed at it fails with 404. That's the same response you'd get for an id that doesn't exist, which is the point — you can't enumerate.

Archiving

Users archive places rather than deleting them. An archived place:

• stops matching new fixes immediately — current-place won't return it, presence starts answering 404, and rules pointed at it go quiet,
• but keeps its label on past visits, so the user's history stays readable rather than decaying into anonymous time windows.

From your side an archived place looks exactly like an unshared one. If you've cached a place_id and it starts 404ing, drop it — don't retry.

Designing around this

Cache labels, not meaning. A user can rename a place. The id is stable; the label is not, and re-reading it is how you stay in sync.

Never require a specific place. Users may share none, one, or ten. An onboarding flow that says "share your Home place to continue" will strand people who called theirs something else, or who don't want to. Ask current-place, show what you get, and let no_place be an ordinary state.

Don't try to reconstruct geometry. Correlating visit timestamps against other signals to infer where a place is defeats the entire arrangement, and the per-connection budgets exist partly to make it impractical. If your product needs coordinates, ask for the sensitive tier honestly and justify it.