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 JSON Object:

query (dict) – query to filter features.
fields (list) – optional; Select fields to render in results. If present then all other properties will be omitted from results.
cursor (int) – optional; Use to retrieve more data if the results do not fit into response of one endpoint call.

Example request:

{
    "query": {
        "name": "Prague"
    },
    "fields": ["collection", "name", "geometry"],
    "cursor": 123
}

Response JSON Object:

results (list) – list of found Feature documents
cursor (int) – optional; If a cursor is present in the response, it signifies that there is more data available. Use this cursor value as a parameter in the next API call to retrieve additional data.

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]
               ]
            ]
         }
      }
   ],
   "cursor": 123
}

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