# Places endpoints

Places derived from a workspace's people and confirmed records: list them, read one with its people and events, and get place-name suggestions.

Paths are relative to https://kleiobase.com/api/v1. Request and response schemas are in the OpenAPI document at https://kleiobase.com/api/v1/openapi.json.

## List places

`GET /workspaces/{workspace_id}/places`

Derived from people and confirmed records. Ordered by name. A place's id is stable and opaque. coordinates come from the geocode cache only: a list never geocodes, so a place not geocoded yet has null coordinates.

Parameters:

- `workspace_id` (path, required): The workspace (project) id.
- `limit` (query, optional): Page size. Default 25, max 100.
- `cursor` (query, optional): The next_cursor of the previous page. Opaque.
- `q` (query, optional): Place name filter (max 200 characters).

Responses:

- `200`: A page of places.
- `401`: Missing, malformed, unknown or revoked API key.
- `403`: The account has no paid plan.
- `404`: The workspace does not exist or is not visible to this key's owner.
- `422`: Invalid limit, cursor or q.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

## Get a place

`GET /workspaces/{workspace_id}/places/{place_id}`

The place, who is connected to it and the events there. When the place is not in the geocode cache yet it is geocoded once now, which also counts against the app's geocoding rate limit (429 with Retry-After when it is reached). coordinates is null when the place cannot be found on the map.

Parameters:

- `workspace_id` (path, required): The workspace (project) id.
- `place_id` (path, required): The place id, as returned by GET .../places or GET .../search. Opaque.

Responses:

- `200`: The place.
- `401`: Missing, malformed, unknown or revoked API key.
- `403`: The account has no paid plan.
- `404`: The workspace does not exist or is not visible to this key's owner. Also: The place id is invalid or the place is not in this workspace.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

## Suggest place names

`GET /workspaces/{workspace_id}/places/suggestions`

Place names already used in the workspace that match q, as the app's place field suggests them: matches at the start of a word first. At most 20. Not paginated: next_cursor is always null.

Parameters:

- `workspace_id` (path, required): The workspace (project) id.
- `q` (query, optional): What was typed so far (1 to 100 characters). Matching ignores case and accents.

Responses:

- `200`: Suggestions.
- `401`: Missing, malformed, unknown or revoked API key.
- `403`: The account has no paid plan.
- `404`: The workspace does not exist or is not visible to this key's owner.
- `422`: q is missing or longer than 100 characters.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

Canonical: https://kleiobase.com/developers/docs/reference/places