.. Copyright (C) 2018-2024 SpaceKnow, Inc.

.. _api.geojsondb:

**************
GeoJSON DB API
**************

GeoJSON DB API provides an interface for storage of GeoJSON [#geojson]_
features.

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

.. include:: _private.rst

Create New Feature
==================

**Needed Permissions**: ``geojsondb.create.<collection>``

.. http: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**:

    .. sourcecode:: json

        {
            "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]
                    ]
                ]
                }
            }
            ]
        }

    :>json Array created: IDs of created features

    **Example response**:

    .. sourcecode:: json

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

Search Features
===============

GeoJSON DB search API is :ref:`paginated <api.mechanics.paging>`.

.. 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``

.. http:post:: /api/features/search

    Query documents in database.

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

    **Example request**:

    .. sourcecode:: json

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

    :>json list results: list of found ``Feature`` documents
    :>json int cursor: 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**:

    .. sourcecode:: json

      {
         "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``

.. http:post:: /api/features/aggregate

    Count documents in database. Request body is query JSON.

    **Example request**:

    .. sourcecode:: json

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

    :>json list results: count of matching features.

    **Example response**:

    .. sourcecode:: json

      {
         "count": 289
      }


Get Feature
===========

**Needed Permissions**: ``geojsondb.get.<collection>``

.. http:post:: /api/feature/get

    Get single feature from the database.

    **Example request**:

    .. sourcecode:: json

        {
            "id": "4a9ef36e0dd9ef847370ab07"
        }

    **Example response**:

    .. sourcecode:: json

        {
            "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>``

.. http:post:: /api/feature/delete

    Delete feature with given ID from database.

    **Example request**:

    .. sourcecode:: json

        {
            "id": "4a9ef36e0dd9ef847370ab07"
        }

    **Example response**:

    .. sourcecode:: json

        {}


**Needed Permissions**: ``geojsondb.modify.<collection>``

.. http: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**:

    .. sourcecode:: json

        {
            "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],
                    ]
                ]
            }
        }

    :>json string modified: ID of modified feature

    **Example response**:

    .. sourcecode:: json

        {
            "modified": "3b6ef36e3dd9ef847370cee5"
        }

Find Unique Property Values
===========================

**Needed Permissions**: ``geojsondb.search``

.. http:post:: /api/properties

    Find unique values of property for features matching query.

    :<json string property: property for which unique values should be
       returned.
    :<json object query: query to filter features.

    **Example request**:

    .. sourcecode:: json

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

    **Example response**:

    .. sourcecode:: json

        ["first_collection", "second_collection"]


.. rubric:: Footnotes

.. [#geojson] https://tools.ietf.org/html/rfc7946