Writing features

Check access#

A read key returns 403 insufficient_scope on writes; a role without edit permission returns 403 forbidden. A collection you cannot see returns 404. Check orbgis.editable in its metadata before writing; every write still checks current permissions. The write limit is 60 requests/minute per key, with a batch counting as one request.

One feature at a time#

Use the collection’s column names in properties and the top-level id for the feature id. Unknown columns or invalid values return 422 features_rejected with an errors list; nothing is saved. Missing features return 404. Concurrent edits use last-write-wins.

For a layer with species and height_m columns, create a point:

curl --fail-with-body \
  -H "Authorization: Bearer $ORBGIS_API_KEY" \
  -H "Content-Type: application/geo+json" \
  -d '{"type":"Feature","geometry":{"type":"Point","coordinates":[18.07,59.33]},"properties":{"species":"Tilia","height_m":12}}' \
  "https://api.orbgis.se/v1/collections/COLLECTION_ID/items"

Replace COLLECTION_ID and choose properties from your layer’s queryables. POST accepts application/geo+json or application/json; use the batch route for multiple features.

Batch writes#

POST /v1/collections/{id}/items/batch applies delete, then update, then add in one transaction. Each list accepts up to 500 entries; the request body limit is 5 MiB (413 payload_too_large). Updates follow PATCH rules; additions follow POST rules.

{
  "delete": [17, 18],
  "update": [{"id": 1042, "properties": {"height_m": 14}}],
  "add": [{"type": "Feature", "id": 5001, "geometry": {"type": "Point", "coordinates": [18.07, 59.33]}, "properties": {"species": "Quercus"}}]
}

A successful response includes deleted, updated, inserted, objectids and links. objectids lists inserted ids in add order. Any rejected entry, including a missing feature, returns 422 features_rejected and rolls back the entire batch.

Coordinates#

Coordinates default to CRS84 longitude/latitude. Set Content-Crs: EPSG:3006 (or ?crs=) to use another system from the collection’s crs list. The server transforms coordinates into the storage system.

Point, MultiPoint, LineString, MultiLineString, Polygon and MultiPolygon are supported. GeometryCollection is rejected. Layers are 2D: a third ordinate is dropped. Rings must be closed; one geometry may contain at most 200 000 positions. Use geometry: null for attribute-only collections.

Retries#

Feature writes have no idempotency key. Repeating a create after a timeout can insert a duplicate. Use explicit feature ids where appropriate; if an id already exists, read the feature and compare it before treating the earlier request as successful.

Before retrying an uncertain write, re-read the affected features. Repeating the same PATCH values leaves the requested values in place; deleting an already absent feature returns 404. Account for edits made by other clients between requests.

Replace a dataset or rebuild overviews#

For a full refresh, upload a file, then send POST /v1/collections/{id}/replace with the body below. Add sourceLayer, sourceSrid or csv when needed. The collection keeps its id, styling and map references.

{"uploadId": "UPLOAD_ID_FROM_UPLOAD_RESPONSE"}

The response is 202 with job; repeating the same upload id returns the existing job with 200. Writes are blocked with 409 conflict during replacement or an overview rebuild. After many edits, POST /v1/collections/{id}/refresh-lod requests an overview rebuild for low-zoom tiles.

After a write#

A write updates the collection’s updated value and tile version. Re-fetch TileJSON to obtain the new tile URLs. A layer.data_changed webhook identifies the changed layer; events are coalesced over about ten seconds and contain no feature data.