Francesco Bartoli
bb4cd0bf69
Fix starlette event loop Fix starlette event loop Fix starlette event loop Fix starlette event loop Fix provider regression Make method public Make method public Move function to the helpers utility Add the CQL lifecycle for development Add CQL docs Fix flake8 Isolate import for starlette codepath
274 lines
8.1 KiB
ReStructuredText
274 lines
8.1 KiB
ReStructuredText
.. _ogcapi-features:
|
|
|
|
Publishing vector data to OGC API - Features
|
|
============================================
|
|
|
|
`OGC API - Features`_ provides geospatial data access functionality to vector data.
|
|
|
|
To add vector data to pygeoapi, you can use the dataset example in :ref:`configuration`
|
|
as a baseline and modify accordingly.
|
|
|
|
Providers
|
|
---------
|
|
|
|
pygeoapi core feature providers are listed below, along with a matrix of supported query
|
|
parameters.
|
|
|
|
.. csv-table::
|
|
:header: Provider, properties (filters), resulttype, bbox, datetime, sortby, properties (display), CQL
|
|
:align: left
|
|
|
|
CSV,❌,results/hits,❌,❌,❌,✅,❌
|
|
Elasticsearch,✅,results/hits,✅,✅,✅,✅,✅
|
|
GeoJSON,❌,results/hits,❌,❌,❌,❌,❌
|
|
MongoDB,✅,results,✅,✅,✅,❌,❌
|
|
OGR,✅,results/hits,✅,❌,❌,❌,❌
|
|
PostgreSQL,✅,results/hits,✅,❌,❌,❌,❌
|
|
SQLiteGPKG,✅,results/hits,✅,❌,❌,❌,❌
|
|
SensorThingsAPI,✅,results/hits,✅,✅,✅,✅,❌
|
|
|
|
|
|
Below are specific connection examples based on supported providers.
|
|
|
|
Connection examples
|
|
-------------------
|
|
|
|
CSV
|
|
^^^
|
|
|
|
To publish a CSV file, the file must have columns for x and y geometry
|
|
which need to be specified in ``geometry`` section of the ``provider``
|
|
definition.
|
|
|
|
.. code-block:: yaml
|
|
|
|
providers:
|
|
- type: feature
|
|
name: CSV
|
|
data: tests/data/obs.csv
|
|
id_field: id
|
|
geometry:
|
|
x_field: long
|
|
y_field: lat
|
|
|
|
|
|
GeoJSON
|
|
^^^^^^^
|
|
|
|
To publish a GeoJSON file, the file must be a valid GeoJSON FeatureCollection.
|
|
|
|
.. code-block:: yaml
|
|
|
|
providers:
|
|
- type: feature
|
|
name: GeoJSON
|
|
data: tests/data/file.json
|
|
id_field: id
|
|
|
|
.. _Elasticsearch:
|
|
|
|
Elasticsearch
|
|
^^^^^^^^^^^^^
|
|
|
|
.. note::
|
|
Elasticsearch 7 or greater is supported.
|
|
|
|
|
|
To publish an Elasticsearch index, the following are required in your index:
|
|
|
|
- indexes must be documents of valid GeoJSON Features
|
|
- index mappings must define the GeoJSON ``geometry`` as a ``geo_shape``
|
|
|
|
.. code-block:: yaml
|
|
|
|
providers:
|
|
- type: feature
|
|
name: Elasticsearch
|
|
data: http://localhost:9200/ne_110m_populated_places_simple
|
|
id_field: geonameid
|
|
time_field: datetimefield
|
|
|
|
This provider has the support for the CQL queries as indicated in the table above.
|
|
|
|
.. seealso::
|
|
:ref:`cql` for more details on how to use the Common Query Language to filter the collection with specific queries.
|
|
|
|
OGR
|
|
^^^
|
|
|
|
`GDAL/OGR <https://gdal.org>`_ supports a wide range of spatial file formats, such as shapefile, dxf, gpx, kml,
|
|
but also services such as WFS. Read the full list and configuration options at https://gdal.org/drivers/vector.
|
|
Additional formats and features are available via the `virtual format <https://gdal.org/drivers/vector/vrt.html#vector-vrt>`_,
|
|
use this driver for example for flat database files (CSV).
|
|
|
|
The OGR provider requires a recent (3+) version of GDAL to be installed.
|
|
|
|
.. code-block:: yaml
|
|
|
|
providers:
|
|
- type: feature
|
|
name: OGR
|
|
data:
|
|
source_type: ESRI Shapefile
|
|
source: tests/data/dutch_addresses_shape_4326/inspireadressen.shp
|
|
source_options:
|
|
ADJUST_GEOM_TYPE: FIRST_SHAPE
|
|
gdal_ogr_options:
|
|
SHPT: POINT
|
|
id_field: fid
|
|
layer: inspireadressen
|
|
|
|
|
|
.. code-block:: yaml
|
|
|
|
providers:
|
|
- type: feature
|
|
name: OGR
|
|
data:
|
|
source_type: WFS
|
|
source: WFS:https://geodata.nationaalgeoregister.nl/rdinfo/wfs?
|
|
source_options:
|
|
VERSION: 2.0.0
|
|
OGR_WFS_PAGING_ALLOWED: YES
|
|
OGR_WFS_LOAD_MULTIPLE_LAYER_DEFN: NO
|
|
gdal_ogr_options:
|
|
GDAL_CACHEMAX: 64
|
|
GDAL_HTTP_PROXY: (optional proxy)
|
|
GDAL_PROXY_AUTH: (optional auth for remote WFS)
|
|
CPL_DEBUG: NO
|
|
id_field: gml_id
|
|
layer: rdinfo:stations
|
|
|
|
|
|
MongoDB
|
|
^^^^^^^
|
|
|
|
.. todo:: add overview and requirements
|
|
|
|
.. code-block:: yaml
|
|
|
|
providers:
|
|
- type: feature
|
|
name: MongoDB
|
|
data: mongodb://localhost:27017/testdb
|
|
collection: testplaces
|
|
|
|
|
|
PostgreSQL
|
|
^^^^^^^^^^
|
|
|
|
.. todo:: add overview and requirements
|
|
|
|
.. code-block:: yaml
|
|
|
|
providers:
|
|
- type: feature
|
|
name: PostgreSQL
|
|
data:
|
|
host: 127.0.0.1
|
|
dbname: test
|
|
user: postgres
|
|
password: postgres
|
|
search_path: [osm, public]
|
|
id_field: osm_id
|
|
table: hotosm_bdi_waterways
|
|
geom_field: foo_geom
|
|
|
|
|
|
SQLiteGPKG
|
|
^^^^^^^^^^
|
|
|
|
.. todo:: add overview and requirements
|
|
|
|
SQLite file:
|
|
|
|
.. code-block:: yaml
|
|
|
|
providers:
|
|
- type: feature
|
|
name: SQLiteGPKG
|
|
data: ./tests/data/ne_110m_admin_0_countries.sqlite
|
|
id_field: ogc_fid
|
|
table: ne_110m_admin_0_countries
|
|
|
|
|
|
GeoPackage file:
|
|
|
|
.. code-block:: yaml
|
|
|
|
providers:
|
|
- type: feature
|
|
name: SQLiteGPKG
|
|
data: ./tests/data/poi_portugal.gpkg
|
|
id_field: osm_id
|
|
table: poi_portugal
|
|
|
|
|
|
SensorThings API
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
The STA provider is capable of creating feature collections from OGC SensorThings
|
|
API endpoints. Three of the STA entities are configurable: Things, Datastreams, and
|
|
Observations. For a full description of the SensorThings entity model, see
|
|
`here <http://docs.opengeospatial.org/is/15-078r6/15-078r6.html#figure_2>`_.
|
|
For each entity of ``Things``, pygeoapi will expand all entities directly related to
|
|
the ``Thing``, including its associated ``Location``, from which the
|
|
geometry for the feature collection is derived. Similarly, ``Datastreams`` are expanded to
|
|
include the associated ``Thing``, ``Sensor`` and ``ObservedProperty``.
|
|
|
|
The default id_field is ``@iot.id``. The STA provider adds one required field,
|
|
``entity``, and an optional field, ``intralink``. The ``entity`` field refers to
|
|
which STA entity to use for the feature collection. The ``intralink`` field controls
|
|
how the provider is acted upon by other STA providers and is by default, False.
|
|
If ``intralink`` is true for an adjacent STA provider collection within a
|
|
pygeoapi instance, the expanded entity is instead represented by an intra-pygeoapi
|
|
link to the other entity or it's ``uri_field`` if declared.
|
|
|
|
.. code-block:: yaml
|
|
|
|
providers:
|
|
- type: feature
|
|
name: SensorThings
|
|
data: https://sensorthings-wq.brgm-rec.fr/FROST-Server/v1.0/
|
|
uri_field: uri
|
|
entity: Datastreams
|
|
time_field: phenomenonTime
|
|
intralink: true
|
|
|
|
If all three entities are configured, the STA provider will represent a complete STA
|
|
endpoint as OGC-API feature collections. The ``Things`` features will include links
|
|
to the associated features in the ``Datastreams`` feature collection, and the
|
|
``Observations`` features will include links to the associated features in the
|
|
``Datastreams`` feature collection. Examples with three entities configured
|
|
are included in the docker examples for SensorThings.
|
|
|
|
Data access examples
|
|
--------------------
|
|
|
|
- list all collections
|
|
- http://localhost:5000/collections
|
|
- overview of dataset
|
|
- http://localhost:5000/collections/foo
|
|
- queryables
|
|
- http://localhost:5000/collections/foo/queryables
|
|
- browse features
|
|
- http://localhost:5000/collections/foo/items
|
|
- paging
|
|
- http://localhost:5000/collections/foo/items?startIndex=10&limit=10
|
|
- CSV outputs
|
|
- http://localhost:5000/collections/foo/items?f=csv
|
|
- query features (spatial)
|
|
- http://localhost:5000/collections/foo/items?bbox=-180,-90,180,90
|
|
- query features (attribute)
|
|
- http://localhost:5000/collections/foo/items?propertyname=foo
|
|
- query features (temporal)
|
|
- http://localhost:5000/collections/foo/items?datetime=2020-04-10T14:11:00Z
|
|
- query features (temporal) and sort ascending by a property (if no +/- indicated, + is assumed)
|
|
- http://localhost:5000/collections/foo/items?datetime=2020-04-10T14:11:00Z&sortby=+datetime
|
|
- query features (temporal) and sort descending by a property
|
|
- http://localhost:5000/collections/foo/items?datetime=2020-04-10T14:11:00Z&sortby=-datetime
|
|
- fetch a specific feature
|
|
- http://localhost:5000/collections/foo/items/123
|
|
|
|
.. _`OGC API - Features`: https://www.ogc.org/standards/ogcapi-features
|