Skip to content
getgeolens.com
GeoLens Docs

Create Feature

POST
/datasets/{dataset_id}/features/
 
curl --request POST \
  --url https://example.com/datasets/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/features/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "geometry": { "type": "GeometryCollection", "geometries": [ { "type": "Point", "coordinates": [ "example" ] } ] }, "properties": {} }'

Insert a new GeoJSON feature into a dataset.

Send the same Idempotency-Key on every attempt to create one feature, and Idempotency-Attempt numbering the attempts 1, 2, 3 and so on. A repeat from the same user on the same dataset never inserts a second feature. It answers with the feature as stored, with the same 201 status and body shape. If its attempt number is higher than any applied so far, it first applies its geometry and the properties it names to that feature, with the validation a create gets, unless anyone else has written the feature since the last attempt was applied: then it is refused with 409, the stored feature in detail.feature, and nothing is overwritten. If it is equal or lower, the stored feature comes back unchanged, so a request that arrives late cannot undo a later one. Two requests with one key never both insert. A key is honored for 24 hours. If the feature it created has been deleted since, or the dataset’s data has been replaced by a reupload or an overwrite, the repeat is refused with 409 rather than creating another. Without the key every request inserts, and an attempt number sent without one is ignored.

Authorizations

Section titled “ Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
dataset_id
required
Dataset Id
string format: uuid

Header Parameters

Section titled “ Header Parameters ”
Idempotency-Key
Idempotency-Key

Optional key that makes a retried create safe. Letters, digits and ._:-, up to 128 characters.

string
>= 1 characters <= 128 characters /^[A-Za-z0-9._:-]+$/

Optional key that makes a retried create safe. Letters, digits and ._:-, up to 128 characters.

Idempotency-Attempt
Idempotency-Attempt

Attempt number sent with Idempotency-Key, counting up by one each time the body is sent again. Counts as 1 when omitted.

integer
>= 1 <= 2147483647

Attempt number sent with Idempotency-Key, counting up by one each time the body is sent again. Counts as 1 when omitted.

Request Body required

Section titled “ Request Body required ”
Media type application/json
FeatureCreate

GeoJSON-style feature for insertion.

object
geometry
required
Any of:
GeoJSONGeometryCollection

A GeoJSON GeometryCollection (RFC 7946 §3.1.8).

Geometry collections carry geometries instead of coordinates. Only generic-geometry datasets accept them on write.

Nested collections are rejected because PostGIS cannot round-trip them through the GeoJSON boundary.

object
type
required
Type
string
Allowed value: GeometryCollection
geometries
required
Geometries
Array<object>
GeoJSONGeometry

A GeoJSON geometry object (RFC 7946).

object
type
required
Type
string
Allowed values: Point MultiPoint LineString MultiLineString Polygon MultiPolygon
coordinates
required
Coordinates
Array
properties
Any of:
object
key
additional properties
any

Responses

Section titled “ Responses ”

201

Section titled “ 201 ”

Successful Response

GeoJSONFeature

A written GeoJSON Feature, plus the dataset’s committed tile version.

object
type
Type
string
default: Feature
Allowed value: Feature
id
required
Id
integer
geometry
Any of:
GeoJSONGeometryCollection

A GeoJSON GeometryCollection (RFC 7946 §3.1.8).

Geometry collections carry geometries instead of coordinates. Only generic-geometry datasets accept them on write.

Nested collections are rejected because PostGIS cannot round-trip them through the GeoJSON boundary.

object
type
required
Type
string
Allowed value: GeometryCollection
geometries
required
Geometries
Array<object>
GeoJSONGeometry

A GeoJSON geometry object (RFC 7946).

object
type
required
Type
string
Allowed values: Point MultiPoint LineString MultiLineString Polygon MultiPolygon
coordinates
required
Coordinates
Array
properties
required
Properties
object
key
additional properties
any
table_id
Any of:
string
tile_cache_version
Any of:
integer
Example 
{
  "type": "Feature",
  "geometry": {
    "type": "GeometryCollection",
    "geometries": [
      {
        "type": "Point"
      }
    ]
  }
}

400

Section titled “ 400 ”

Bad request — invalid payload

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string
Example 
{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

401

Section titled “ 401 ”

Unauthorized — missing or invalid credentials

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string
Example 
{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

403

Section titled “ 403 ”

Forbidden — caller lacks write access

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string
Example 
{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

404

Section titled “ 404 ”

Not found

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string
Example 
{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

409

Section titled “ 409 ”

Conflict — resource state prevents the operation

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string
Example 
{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

422

Section titled “ 422 ”

Validation error

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string
Example 
{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

429

Section titled “ 429 ”

Too many requests — retry after the advertised interval

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string
Example 
{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

Headers

Section titled “ Headers ”
Retry-After
integer

Seconds until the request may be retried

500

Section titled “ 500 ”

Internal server error

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string
Example 
{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

503

Section titled “ 503 ”

Service unavailable — the database could not serve the request

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string
Example 
{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}
Privacy Apache 2.0 getgeolens.com