How layers work

Layer order is precedence order.

The default stack uses the Overture-backed base layer and the Open Places API community layer. Authenticated callers can also select account-owned layers or a saved preset. Higher layers win when they explicitly target a lower-layer place.

Rule The stack starts with base, then optional open, then account layers.

Explicit selection

Use `layers` for a specific ordered stack.

Use layers when a request needs deterministic layer membership. Account layers use the account:<layer_slug> token and come last.

Request URL layers

GET /v1/places?q=coffee&lat=40.7128&lon=-74.0060&layers=base,open,account:field-team

Presets

Use `layer_preset` for account defaults.

Presets are useful for production defaults, customer-specific views, or partner-managed records. A request can use layers or layer_preset, but not both.

Request URL preset

GET /v1/places?q=coffee&lat=40.7128&lon=-74.0060&layer_preset=production

Operations

Account layers can express product-specific changes.

Operation	Effect in search
Create place	Adds an account-only place with an account-scoped public ID.
Update place field	Patches selected fields on a targeted lower-layer place while preserving the public ID.
Suppress place	Removes a targeted lower-layer place from the effective result set.
Mark closed, moved, or duplicate	Represents product-specific status without mutating the shared base layer.

cURL layer stack

curl "https://api.openplacesapi.com/v1/places?q=coffee&lat=40.7128&lon=-74.0060&layers=base,open,account:client-a" \
  -H "Authorization: Bearer $OPEN_PLACES_API_KEY"

Management API

Use Control Plane Tokens for layer writes.

Public search API keys only authenticate /v1/places. External systems that create layers, write entries, run imports, save presets, manage grants, or update API-key layer defaults should use scoped Control Plane Tokens from the dashboard.

Scopes layers:read, layers:write, entries:write, imports:write, presets:write, grants:write, and api_keys:write_defaults.

Endpoint	Scope
`GET /v1/layers`	`layers:read`
`POST /v1/layers`, `PATCH /v1/layers/:id`, `POST /v1/layers/:id/archive`	`layers:write`
`POST /v1/layers/:id/entries`, `PATCH /v1/layers/:id/entries/:entryId`	`entries:write`
`POST /v1/layers/:id/imports`	`imports:write`
`POST/PATCH /v1/layer-presets`	`presets:write`
`POST /v1/layers/:id/grants`, `POST /v1/layer-grants/:id/revoke`	`grants:write`
`PATCH /v1/api-keys/:id/default-layer-preset`	`api_keys:write_defaults`

cURL list layers

curl https://app.openplacesapi.com/v1/layers \
  -H "Authorization: Bearer $OPEN_PLACES_API_CONTROL_TOKEN"

cURL create layer

curl https://app.openplacesapi.com/v1/layers \
  -H "Authorization: Bearer $OPEN_PLACES_API_CONTROL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Field team","slug":"field-team"}'