# Places, search, notifications and health

Read places with their coordinates, search a workspace, read and clear notifications, and get the tree health score.


## Places

Places are derived from your people and confirmed records. There is no place table, but every place has a stable, opaque `id`:

```bash
curl "https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/places?q=Brno" \
  -H "Authorization: Bearer kb_live_YOUR_KEY"
```

Each place carries `coordinates` (`{ lat, lng }` or `null`). A list never looks a place up on the map, so a place nobody has opened yet has `null` coordinates.

`GET .../places/{place_id}` returns one place with the people connected to it and the events there. If the place has no coordinates yet, it is looked up on the map once, now. That lookup counts against the same geocoding limit as the app, so this request can return `429` with `Retry-After`. `coordinates` stays `null` when the place cannot be found on a map.

`GET .../places/suggestions?q=Br` returns up to 20 place names already used in the workspace, as the app's place field suggests them.

## Search

```bash
curl "https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/search?q=Novak" \
  -H "Authorization: Bearer kb_live_YOUR_KEY"
```

This is the app's search box: up to 5 `people`, 5 `records` and 3 `places`. Names match ignoring case, accents and punctuation. A place found only on records that are not confirmed yet has no detail page until one of them is confirmed, so its `GET .../places/{place_id}` returns `404`.

## Notifications

The API shows the notifications the app shows in that workspace, plus account-wide ones (for example about credits), which appear in every workspace.

- `GET .../notifications` lists them newest first. Add `?unread=true` for unread only. A page holds at most 50.
- `GET .../notifications/unread-count` returns `{ "count": 3 }`.
- `POST .../notifications/read` marks them read, with `{"ids": [...]}` (up to 100) or `{"all": true}`.

The API never sends email.

## Tree health

```bash
curl https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/health \
  -H "Authorization: Bearer kb_live_YOUR_KEY"
```

You get the score from 0 to 100 (`overall`), its `band`, the three `pillars`, a `percentile` against other trees, and `quick_wins`: suggested next steps, each pointing at findings you can work on. A recent score is reused, as on the app's dashboard. `POST .../health/refresh` recomputes it now. All fields are `null`, and `quick_wins` is empty, while the workspace has no people.

Canonical: https://kleiobase.com/developers/docs/places-and-search