GeoJSON DB API

GeoJSON DB API provides an interface for storage of GeoJSON [1] features.

URL: https://api.spaceknow.com/geojsondb

For SpaceKnow internal usage

Following parts of the API are utilized internally by SpaceKnow and are not meant for external usage as we may introduce backward incompatible changes without prior warning.

Please contact us in case you find the APIs useful.

Create New Feature

Needed Permissions: geojsondb.create.<collection>

POST /api/features/create

Request body is GeoJSON. Each feature from GeoJSON is stored as individual entity with unique and deterministic ID. The endpoint is idempotent, i.e. each feature is created in the database just once. Individual features to create cannot contain field id as it will be generated by the endpoint.

Example request:

{
    "type": "FeatureCollection",
    "features": [
    {
        "type": "Feature",
        "properties": {
        "collection": "cities",
        "name": "Berlin"
        },
        "geometry": {
        "type": "Polygon",
        "coordinates": [
            [
                [13.1396484375, 52.3688917060255],
                [13.6614990234375, 52.3688917060255],
                [13.6614990234375, 52.63973017532399],
                [13.1396484375, 52.63973017532399],
                [13.1396484375, 52.3688917060255],
            ]
        ]
        }
    },
    {
        "type": "Feature",
        "properties": {
        "collection": "cities",
        "name": "Prague"
        },
        "geometry": {
        "type": "Polygon",
        "coordinates": [
            [
                [14.271240234375, 49.96712261825979],
                [14.6722412109375, 49.96712261825979],
                [14.6722412109375, 50.169861746007314],
                [14.271240234375, 50.169861746007314],
                [14.271240234375, 49.96712261825979]
            ]
        ]
        }
    }
    ]
}

Response JSON Object:

created (Array) – IDs of created features

Example response:

{
    "created": ["5a9ef36e0dd9ef847370cee5", "4a9ef36e0dd9ef847370ab07"]
}

Search Features

GeoJSON DB search API is paginated.

Warning

Note, that when the _fields parameter is present and geometry property is not part of the fields, the output won’t be formally valid GeoJSON features.

Needed Permissions: geojsondb.search

POST /api/features/search

Query documents in database. Request body is query JSON. Optionally you can pass _fields parameter with a list of fields which you are interested in. The rest of the fields in documents will be omitted.

Request JSON Object:

_fields (Array) – optional; Select fields to render in results.

Example request:

{
    "name": "Prague",
    "_fields": ["collection", "name", "geometry"]
}

Response JSON Object:

results (list) – list of found Feature documents

Example response:

{
   "results": [
      {
         "type": "Feature",
         "id": "4a9ef36e0dd9ef847370ab07",
         "properties": {
            "collection": "cities",
            "name": "Prague"
         },
         "geometry": {
            "type": "Polygon",
            "coordinates": [
               [
                  [14.271240234375, 49.96712261825979],
                  [14.6722412109375, 49.96712261825979],
                  [14.6722412109375, 50.169861746007314],
                  [14.271240234375, 50.169861746007314],
                  [14.271240234375, 49.96712261825979]
               ]
            ]
         }
      }
   ]
}

Aggregate Features

In case you need to get summary information about your search query without need of getting full data, you should use aggregate endpoint. Currently only count aggregation is available.

Needed Permissions: geojsondb.search

POST /api/features/aggregate

Count documents in database. Request body is query JSON.

Example request:

{
    "aggregation": "count",
    "query": {
        "collection": "administrative",
        "country:ISO3166-1": "US",
        "admin_level": 6
    }
}

Response JSON Object:

results (list) – count of matching features.

Example response:

{
   "count": 289
}

Get Feature

Needed Permissions: geojsondb.get.<collection>

POST /api/feature/get

Get single feature from the database.

Example request:

{
    "id": "4a9ef36e0dd9ef847370ab07"
}

Example response:

{
    "type": "Feature",
    "id": "4a9ef36e0dd9ef847370ab07",
    "properties": {
        "collection": "cities",
        "name": "Prague"
    },
    "geometry": {
        "type": "Polygon",
        "coordinates": [
            [
                [14.271240234375, 49.96712261825979],
                [14.6722412109375, 49.96712261825979],
                [14.6722412109375, 50.169861746007314],
                [14.271240234375, 50.169861746007314],
                [14.271240234375, 49.96712261825979]
            ]
        ]
    }
}

Delete Feature

Needed Permissions: geojsondb.delete.<collection>

POST /api/feature/delete

Delete feature with given ID from database.

Example request:

{
    "id": "4a9ef36e0dd9ef847370ab07"
}

Example response:

{}

Needed Permissions: geojsondb.modify.<collection>

POST /api/features/modify

Modify a single feature stored in the database.

Request body is a GeoJSON Feature which must contain id field of previously stored feature. Old feature is removed from the database and will not be accessible. Response contains newly generated id which can be used to access the feature later.

Example request:

{
    "id": "5a9ef36e0dd9ef847370cee5",
    "type": "Feature",
    "properties": {
        "collection": "cities",
        "name": "Berlin",
        "project": "Gentrification"
    },
    "geometry": {
        "type": "Polygon",
        "coordinates": [
            [
                [13.1396484375, 52.3688917060255],
                [13.6614990234375, 52.3688917060255],
                [13.6614990234375, 52.63973017532399],
                [13.1396484375, 52.63973017532399],
                [13.1396484375, 52.3688917060255],
            ]
        ]
    }
}

Response JSON Object:

modified (string) – ID of modified feature

Example response:

{
    "modified": "3b6ef36e3dd9ef847370cee5"
}

Find Unique Property Values

Needed Permissions: geojsondb.search

POST /api/properties

Find unique values of property for features matching query.

Request JSON Object:

property (string) – property for which unique values should be returned.
query (object) – query to filter features.

Example request:

{
   "property": "collection",
   "query": {}
}

Example response:

["first_collection", "second_collection"]

Footnotes