fix list formatting in docs
This commit is contained in:
Tom Kralidis
@@ -6,9 +6,9 @@ Administration
|
||||
Now that you have pygeoapi installed and a basic configuration setup, it's time to complete
|
||||
the administrative steps required before starting up the server. The remaining steps are:
|
||||
|
||||
- create OpenAPI document
|
||||
- validate OpenAPI document
|
||||
- set system environment variables
|
||||
* create OpenAPI document
|
||||
* validate OpenAPI document
|
||||
* set system environment variables
|
||||
|
||||
Creating the OpenAPI document
|
||||
-----------------------------
|
||||
|
||||
@@ -263,6 +263,7 @@ For collections, at the level of items, the default JSON-LD representation adds:
|
||||
The optional configuration options for collections, at the level of an item of items, are:
|
||||
|
||||
- If ``uri_field`` is specified, JSON-LD will be updated such that the ``@id`` has the value of ``uri_field`` for each item in a collection
|
||||
|
||||
.. note::
|
||||
While this is enough to provide valid RDF (as GeoJSON-LD), it does not allow the *properties* of your items to be
|
||||
unambiguously interpretable.
|
||||
|
||||
+6
-6
@@ -9,9 +9,9 @@ Limitations
|
||||
The support to CQL is limited to `Simple CQL filter <https://portal.ogc.org/files/96288#cql-core>`_ and thus it allows to query with the
|
||||
following predicates:
|
||||
|
||||
- comparison predicates
|
||||
- spatial predicates
|
||||
- temporal predicates
|
||||
* comparison predicates
|
||||
* spatial predicates
|
||||
* temporal predicates
|
||||
|
||||
Formats
|
||||
-------
|
||||
@@ -28,9 +28,9 @@ Queries
|
||||
|
||||
The following type of queries are supported right now:
|
||||
|
||||
- ``between`` predicate query
|
||||
- Logical ``and`` query with ``between`` and ``eq`` expression
|
||||
- Spatial query with ``bbox``
|
||||
* ``between`` predicate query
|
||||
* Logical ``and`` query with ``between`` and ``eq`` expression
|
||||
* Spatial query with ``bbox``
|
||||
|
||||
Examples
|
||||
^^^^^^^^
|
||||
|
||||
@@ -84,22 +84,22 @@ The `xarray`_ provider plugin reads and extracts `NetCDF`_ and `Zarr`_ data.
|
||||
Data access examples
|
||||
--------------------
|
||||
|
||||
- list all collections
|
||||
- http://localhost:5000/collections
|
||||
- overview of dataset
|
||||
- http://localhost:5000/collections/foo
|
||||
- coverage rangetype
|
||||
- http://localhost:5000/collections/foo/coverage/rangetype
|
||||
- coverage domainset
|
||||
- http://localhost:5000/collections/foo/coverage/domainset
|
||||
- coverage access via CoverageJSON (default)
|
||||
- http://localhost:5000/collections/foo/coverage?f=json
|
||||
- coverage access via native format (as defined in ``provider.format.name``)
|
||||
- http://localhost:5000/collections/foo/coverage?f=GRIB
|
||||
- coverage access with comma-separated range-subset
|
||||
- http://localhost:5000/collections/foo/coverage?range-subset=1,3
|
||||
- coverage access with subsetting
|
||||
- http://localhost:5000/collections/foo/coverage?subset=lat(10,20)&subset=long(10,20)
|
||||
* list all collections
|
||||
* http://localhost:5000/collections
|
||||
* overview of dataset
|
||||
* http://localhost:5000/collections/foo
|
||||
* coverage rangetype
|
||||
* http://localhost:5000/collections/foo/coverage/rangetype
|
||||
* coverage domainset
|
||||
* http://localhost:5000/collections/foo/coverage/domainset
|
||||
* coverage access via CoverageJSON (default)
|
||||
* http://localhost:5000/collections/foo/coverage?f=json
|
||||
* coverage access via native format (as defined in ``provider.format.name``)
|
||||
* http://localhost:5000/collections/foo/coverage?f=GRIB
|
||||
* coverage access with comma-separated range-subset
|
||||
* http://localhost:5000/collections/foo/coverage?range-subset=1,3
|
||||
* coverage access with subsetting
|
||||
* http://localhost:5000/collections/foo/coverage?subset=lat(10,20)&subset=long(10,20)
|
||||
|
||||
.. _`OGC API - Coverages`: https://github.com/opengeospatial/ogcapi-coverages
|
||||
.. _`rasterio`: https://rasterio.readthedocs.io
|
||||
|
||||
@@ -64,16 +64,16 @@ The `xarray-edr`_ provider plugin reads and extracts `NetCDF`_ and `Zarr`_ data
|
||||
Data access examples
|
||||
--------------------
|
||||
|
||||
- list all collections
|
||||
- http://localhost:5000/collections
|
||||
- overview of dataset
|
||||
- http://localhost:5000/collections/foo
|
||||
- dataset position query
|
||||
- http://localhost:5000/collections/foo/position?coords=POINT(-75%2045)
|
||||
- dataset position query for a specific parameter
|
||||
- http://localhost:5000/collections/foo/position?coords=POINT(-75%2045)¶meter-name=SST
|
||||
- dataset position query for a specific parameter and time step
|
||||
- http://localhost:5000/collections/foo/position?coords=POINT(-75%2045)¶meter-name=SST&datetime=2000-01-16
|
||||
* list all collections
|
||||
* http://localhost:5000/collections
|
||||
* overview of dataset
|
||||
* http://localhost:5000/collections/foo
|
||||
* dataset position query
|
||||
* http://localhost:5000/collections/foo/position?coords=POINT(-75%2045)
|
||||
* dataset position query for a specific parameter
|
||||
* http://localhost:5000/collections/foo/position?coords=POINT(-75%2045)¶meter-name=SST
|
||||
* dataset position query for a specific parameter and time step
|
||||
* http://localhost:5000/collections/foo/position?coords=POINT(-75%2045)¶meter-name=SST&datetime=2000-01-16
|
||||
|
||||
|
||||
.. _`xarray`: https://xarray.pydata.org
|
||||
|
||||
@@ -76,8 +76,8 @@ Elasticsearch
|
||||
|
||||
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``
|
||||
* indexes must be documents of valid GeoJSON Features
|
||||
* index mappings must define the GeoJSON ``geometry`` as a ``geo_shape``
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
@@ -245,29 +245,29 @@ 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
|
||||
* 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
|
||||
|
||||
@@ -52,26 +52,26 @@ Putting it all together
|
||||
|
||||
To summarize how pygeoapi processes and managers work together::
|
||||
|
||||
- process plugins implement the core processing / workflow functionality
|
||||
- manager plugins control and manage how processes are executed
|
||||
* process plugins implement the core processing / workflow functionality
|
||||
* manager plugins control and manage how processes are executed
|
||||
|
||||
Processing examples
|
||||
-------------------
|
||||
|
||||
- list all processes
|
||||
- http://localhost:5000/processes
|
||||
- describe the ``hello-world`` process
|
||||
- http://localhost:5000/processes/hello-world
|
||||
- show all jobs for the ``hello-world`` process
|
||||
- http://localhost:5000/processes/hello-world/jobs
|
||||
- execute a job for the ``hello-world`` process
|
||||
- ``curl -X POST "http://localhost:5000/processes/hello-world/execution" -H "Content-Type: application/json" -d "{\"inputs\":{\"name\": \"hi there2\"}}"``
|
||||
- execute a job for the ``hello-world`` process with a raw response (default)
|
||||
- ``curl -X POST "http://localhost:5000/processes/hello-world/execution" -H "Content-Type: application/json" -d "{\"inputs\":{\"name\": \"hi there2\"}}"``
|
||||
- execute a job for the ``hello-world`` process with a response document
|
||||
- ``curl -X POST "http://localhost:5000/processes/hello-world/execution" -H "Content-Type: application/json" -d "{\"inputs\":{\"name\": \"hi there2\"},\"response\":\"document\"}"``
|
||||
- execute a job for the ``hello-world`` process in asynchronous mode
|
||||
- ``curl -X POST "http://localhost:5000/processes/hello-world/execution" -H "Content-Type: application/json" -d "{\"mode\": \"async\", \"inputs\":{\"name\": \"hi there2\"}}"``
|
||||
* list all processes
|
||||
* http://localhost:5000/processes
|
||||
* describe the ``hello-world`` process
|
||||
* http://localhost:5000/processes/hello-world
|
||||
* show all jobs for the ``hello-world`` process
|
||||
* http://localhost:5000/processes/hello-world/jobs
|
||||
* execute a job for the ``hello-world`` process
|
||||
* ``curl -X POST "http://localhost:5000/processes/hello-world/execution" -H "Content-Type: application/json" -d "{\"inputs\":{\"name\": \"hi there2\"}}"``
|
||||
* execute a job for the ``hello-world`` process with a raw response (default)
|
||||
* ``curl -X POST "http://localhost:5000/processes/hello-world/execution" -H "Content-Type: application/json" -d "{\"inputs\":{\"name\": \"hi there2\"}}"``
|
||||
* execute a job for the ``hello-world`` process with a response document
|
||||
* ``curl -X POST "http://localhost:5000/processes/hello-world/execution" -H "Content-Type: application/json" -d "{\"inputs\":{\"name\": \"hi there2\"},\"response\":\"document\"}"``
|
||||
* execute a job for the ``hello-world`` process in asynchronous mode
|
||||
* ``curl -X POST "http://localhost:5000/processes/hello-world/execution" -H "Content-Type: application/json" -d "{\"mode\": \"async\", \"inputs\":{\"name\": \"hi there2\"}}"``
|
||||
|
||||
.. todo:: add more examples once OAProc implementation is complete
|
||||
|
||||
|
||||
@@ -36,8 +36,8 @@ ElasticsearchCatalogue
|
||||
|
||||
To publish an Elasticsearch index, the following are required in your index:
|
||||
|
||||
- indexes must be documents of valid `OGC API - Records GeoJSON Features`_
|
||||
- index mappings must define the GeoJSON ``geometry`` as a ``geo_shape``
|
||||
* indexes must be documents of valid `OGC API - Records GeoJSON Features`_
|
||||
* index mappings must define the GeoJSON ``geometry`` as a ``geo_shape``
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
@@ -57,7 +57,7 @@ TinyDBCatalogue
|
||||
|
||||
To publish a TinyDB index, the following are required in your index:
|
||||
|
||||
- indexes must be documents of valid `OGC API - Records GeoJSON Features`_
|
||||
* indexes must be documents of valid `OGC API - Records GeoJSON Features`_
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
@@ -72,28 +72,28 @@ To publish a TinyDB index, the following are required in your index:
|
||||
Metadata search examples
|
||||
------------------------
|
||||
|
||||
- overview of record collection
|
||||
- http://localhost:5000/collections/metadata-records
|
||||
- queryables
|
||||
- http://localhost:5000/collections/foo/queryables
|
||||
- browse records
|
||||
- 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 records (spatial)
|
||||
- http://localhost:5000/collections/foo/items?bbox=-180,-90,180,90
|
||||
- query records (attribute)
|
||||
- http://localhost:5000/collections/foo/items?propertyname=foo
|
||||
- query records (temporal)
|
||||
- http://localhost:5000/collections/my-metadata/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/my-metadata/items?datetime=2020-04-10T14:11:00Z&sortby=datetime
|
||||
- query features (temporal) and sort descending by a property
|
||||
- http://localhost:5000/collections/my-metadata/items?datetime=2020-04-10T14:11:00Z&sortby=-datetime
|
||||
- fetch a specific record
|
||||
- http://localhost:5000/collections/my-metadata/items/123
|
||||
* overview of record collection
|
||||
* http://localhost:5000/collections/metadata-records
|
||||
* queryables
|
||||
* http://localhost:5000/collections/foo/queryables
|
||||
* browse records
|
||||
* 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 records (spatial)
|
||||
* http://localhost:5000/collections/foo/items?bbox=-180,-90,180,90
|
||||
* query records (attribute)
|
||||
* http://localhost:5000/collections/foo/items?propertyname=foo
|
||||
* query records (temporal)
|
||||
* http://localhost:5000/collections/my-metadata/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/my-metadata/items?datetime=2020-04-10T14:11:00Z&sortby=datetime
|
||||
* query features (temporal) and sort descending by a property
|
||||
* http://localhost:5000/collections/my-metadata/items?datetime=2020-04-10T14:11:00Z&sortby=-datetime
|
||||
* fetch a specific record
|
||||
* http://localhost:5000/collections/my-metadata/items/123
|
||||
|
||||
.. _`OGC API - Records`: https://www.ogc.org/standards/ogcapi-records
|
||||
.. _`OGC API - Records GeoJSON Features`: https://raw.githubusercontent.com/opengeospatial/ogcapi-records/master/core/openapi/schemas/recordGeoJSON.yaml
|
||||
|
||||
@@ -11,8 +11,8 @@ object storage). To integrate tiles from a local data source, it is assumed
|
||||
that a directory tree of static tiles has been created on disk. Examples of
|
||||
tile generation software include (but are not limited to):
|
||||
|
||||
- `MapProxy`_
|
||||
- `tippecanoe`_
|
||||
* `MapProxy`_
|
||||
* `tippecanoe`_
|
||||
|
||||
Providers
|
||||
---------
|
||||
@@ -58,16 +58,16 @@ The MVT provider plugin provides access to `Mapbox Vector Tiles`_.
|
||||
Data access examples
|
||||
--------------------
|
||||
|
||||
- list all collections
|
||||
- http://localhost:5000/collections
|
||||
- overview of dataset
|
||||
- http://localhost:5000/collections/foo
|
||||
- overview of dataset tiles
|
||||
- http://localhost:5000/collections/foo/tiles
|
||||
- tile matrix metadata
|
||||
- http://localhost:5000/collections/lakes/tiles/WorldCRS84Quad/metadata
|
||||
- tiles URI template
|
||||
- `http://localhost:5000/collections/lakes/tiles/{tileMatrixSetId}/{tileMatrix}/{tileRow}/{tileCol}?f=mvt <http://localhost:5000/collections/lakes/tiles/{tileMatrixSetId}/{tileMatrix}/{tileRow}/{tileCol}?f=mvt>`_
|
||||
* list all collections
|
||||
* http://localhost:5000/collections
|
||||
* overview of dataset
|
||||
* http://localhost:5000/collections/foo
|
||||
* overview of dataset tiles
|
||||
* http://localhost:5000/collections/foo/tiles
|
||||
* tile matrix metadata
|
||||
* http://localhost:5000/collections/lakes/tiles/WorldCRS84Quad/metadata
|
||||
* tiles URI template
|
||||
* `http://localhost:5000/collections/lakes/tiles/{tileMatrixSetId}/{tileMatrix}/{tileRow}/{tileCol}?f=mvt <http://localhost:5000/collections/lakes/tiles/{tileMatrixSetId}/{tileMatrix}/{tileRow}/{tileCol}?f=mvt>`_
|
||||
|
||||
|
||||
.. _`OGC API - Tiles`: https://github.com/opengeospatial/ogcapi-tiles
|
||||
|
||||
@@ -51,8 +51,8 @@ ESRI Shapefile publishing requires to specify all required component file extens
|
||||
Data access examples
|
||||
--------------------
|
||||
|
||||
- STAC root page
|
||||
- http://localhost:5000/stac
|
||||
* STAC root page
|
||||
* http://localhost:5000/stac
|
||||
|
||||
From here, browse the filesystem accordingly.
|
||||
|
||||
|
||||
@@ -5,5 +5,5 @@ Further Reading
|
||||
|
||||
The following list provides information on pygeoapi and OGC API efforts.
|
||||
|
||||
- `Default pygeoapi presentation <https://pygeoapi.io/presentations/default>`_
|
||||
- `OGC API <https://ogcapi.ogc.org>`_
|
||||
* `Default pygeoapi presentation <https://pygeoapi.io/presentations/default>`_
|
||||
* `OGC API <https://ogcapi.ogc.org>`_
|
||||
|
||||
@@ -8,54 +8,54 @@ Introduction
|
||||
Features
|
||||
--------
|
||||
|
||||
- out of the box modern OGC API server
|
||||
- certified OGC Compliant and Reference Implementation for OGC API - Features
|
||||
- additionally implements
|
||||
- OGC API - Coverages
|
||||
- OGC API - Tiles
|
||||
- OGC API - Processes
|
||||
- OGC API - Environmental Data Retrieval
|
||||
- SpatioTemporal Asset Library
|
||||
- out of the box data provider plugins for rasterio, GDAL/OGR, Elasticsearch, PostgreSQL/PostGIS
|
||||
- easy to use OpenAPI / Swagger documentation for developers
|
||||
- supports JSON, GeoJSON, HTML and CSV output
|
||||
- supports data filtering by spatial, temporal or attribute queries
|
||||
- easy to install: install a full implementation via ``pip`` or ``git``
|
||||
- simple YAML configuration
|
||||
- easy to deploy: via UbuntuGIS or the official Docker image
|
||||
- flexible: built on a robust plugin framework to build custom data connections, formats and processes
|
||||
- supports any Python web framework (included are Flask [default], Starlette)
|
||||
- supports asynchronous processing and job management (OGC API - Processes)
|
||||
* out of the box modern OGC API server
|
||||
* certified OGC Compliant and Reference Implementation for OGC API - Features
|
||||
* additionally implements
|
||||
* OGC API - Coverages
|
||||
* OGC API - Tiles
|
||||
* OGC API - Processes
|
||||
* OGC API - Environmental Data Retrieval
|
||||
* SpatioTemporal Asset Library
|
||||
* out of the box data provider plugins for rasterio, GDAL/OGR, Elasticsearch, PostgreSQL/PostGIS
|
||||
* easy to use OpenAPI / Swagger documentation for developers
|
||||
* supports JSON, GeoJSON, HTML and CSV output
|
||||
* supports data filtering by spatial, temporal or attribute queries
|
||||
* easy to install: install a full implementation via ``pip`` or ``git``
|
||||
* simple YAML configuration
|
||||
* easy to deploy: via UbuntuGIS or the official Docker image
|
||||
* flexible: built on a robust plugin framework to build custom data connections, formats and processes
|
||||
* supports any Python web framework (included are Flask [default], Starlette)
|
||||
* supports asynchronous processing and job management (OGC API - Processes)
|
||||
|
||||
Standards Support
|
||||
-----------------
|
||||
|
||||
Standards are at the core of pygeoapi. Below is the project's standards support matrix.
|
||||
|
||||
- Implementing: implements standard (good)
|
||||
- Compliant: conforms to OGC compliance requirements (great)
|
||||
- Reference Implementation: provides a reference for the standard (awesome!)
|
||||
* Implementing: implements standard (good)
|
||||
* Compliant: conforms to OGC compliance requirements (great)
|
||||
* Reference Implementation: provides a reference for the standard (awesome!)
|
||||
|
||||
.. csv-table::
|
||||
:header: "Standard", "Support"
|
||||
:align: left
|
||||
:widths: 20, 20
|
||||
|
||||
`OGC API - Features`_,Reference Implementation
|
||||
`OGC API - Coverages`_,Implementing
|
||||
`OGC API - Tiles`_,Implementing
|
||||
`OGC API - Processes`_,Implementing
|
||||
`OGC API - Records`_,Implementing
|
||||
`OGC API - Environmental Data Retrieval`_,Implementing
|
||||
`OGC API * Features`_,Reference Implementation
|
||||
`OGC API * Coverages`_,Implementing
|
||||
`OGC API * Tiles`_,Implementing
|
||||
`OGC API * Processes`_,Implementing
|
||||
`OGC API * Records`_,Implementing
|
||||
`OGC API * Environmental Data Retrieval`_,Implementing
|
||||
`SpatioTemporal Asset Catalog`_,Implementing
|
||||
|
||||
|
||||
.. _`pygeoapi`: https://pygeoapi.io
|
||||
.. _`OGC API`: https://ogcapi.ogc.org
|
||||
.. _`OGC API - Features`: https://www.ogc.org/standards/ogcapi-features
|
||||
.. _`OGC API - Coverages`: https://github.com/opengeospatial/ogcapi-coverages
|
||||
.. _`OGC API - Tiles`: https://github.com/opengeospatial/ogcapi-tiles
|
||||
.. _`OGC API - Processes`: https://github.com/opengeospatial/ogcapi-processes
|
||||
.. _`OGC API - Records`: https://github.com/opengeospatial/ogcapi-records
|
||||
.. _`OGC API - Environmental Data Retrieval`: https://github.com/opengeospatial/ogcapi-environmental-data-retrieval
|
||||
.. _`OGC API * Features`: https://www.ogc.org/standards/ogcapi-features
|
||||
.. _`OGC API * Coverages`: https://github.com/opengeospatial/ogcapi-coverages
|
||||
.. _`OGC API * Tiles`: https://github.com/opengeospatial/ogcapi-tiles
|
||||
.. _`OGC API * Processes`: https://github.com/opengeospatial/ogcapi-processes
|
||||
.. _`OGC API * Records`: https://github.com/opengeospatial/ogcapi-records
|
||||
.. _`OGC API * Environmental Data Retrieval`: https://github.com/opengeospatial/ogcapi-environmental-data-retrieval
|
||||
.. _`SpatioTemporal Asset Catalog`: https://stacspec.org
|
||||
|
||||
+16
-16
@@ -36,27 +36,27 @@ There are 2 ways to affect the language of the results returned by pygeoapi, bot
|
||||
Notes
|
||||
^^^^^
|
||||
|
||||
- If pygeoapi cannot find a good match to the requested language, the response is returned in the default language (US English mostly).
|
||||
* If pygeoapi cannot find a good match to the requested language, the response is returned in the default language (US English mostly).
|
||||
The default language is the *first* language defined in pygeoapi's server configuration YAML (see `maintainer guide`_).
|
||||
|
||||
- Even if pygeoapi *itself* supports the requested language, provider plugins may not support that particular language or perhaps don't even
|
||||
* Even if pygeoapi *itself* supports the requested language, provider plugins may not support that particular language or perhaps don't even
|
||||
support any language at all. In that case the provider will reply in its own "unknown" language, which may not be the same language
|
||||
as the default pygeoapi server language set in the ``Content-Language`` HTTP response header.
|
||||
|
||||
- It is up to the creator of the provider to properly define at least 1 supported language in the provider configuration, as described
|
||||
* It is up to the creator of the provider to properly define at least 1 supported language in the provider configuration, as described
|
||||
in the `developer guide`_. This will ensure that the ``Content-Language`` HTTP response header is always set properly.
|
||||
|
||||
- If pygeoapi found a match to the requested language, the response will include a ``Content-Language`` HTTP header,
|
||||
* If pygeoapi found a match to the requested language, the response will include a ``Content-Language`` HTTP header,
|
||||
set to the best-matching server language code. This is the default behavior for most pygeoapi requests. However, note that some responses
|
||||
(e.g. exceptions) always have a ``Content-Language: en-US`` header, regardless of the requested language.
|
||||
|
||||
- For results returned by a **provider**, the ``Content-Language`` HTTP header will be set to the best-matching
|
||||
* For results returned by a **provider**, the ``Content-Language`` HTTP header will be set to the best-matching
|
||||
provider language or the best-matching pygeoapi server language if the provider is not language-aware.
|
||||
|
||||
- If the provider supports a requested language, but pygeoapi does *not* support that same language, the ``Content-Language``
|
||||
* If the provider supports a requested language, but pygeoapi does *not* support that same language, the ``Content-Language``
|
||||
header will contain both the provider language *and* the best-matching pygeoapi server language.
|
||||
|
||||
- Please note that the ``Content-Language`` HTTP response header only *indicates the language of the intended audience*.
|
||||
* Please note that the ``Content-Language`` HTTP response header only *indicates the language of the intended audience*.
|
||||
It does not necessarily mean that the content is actually written in that particular language.
|
||||
|
||||
|
||||
@@ -94,14 +94,14 @@ Next, you will have to provide translations for the configured languages. This i
|
||||
Notes
|
||||
^^^^^
|
||||
|
||||
- The **first** language you define in the configuration determines the default language, i.e. the language that pygeoapi will
|
||||
* The **first** language you define in the configuration determines the default language, i.e. the language that pygeoapi will
|
||||
use if no other language was requested or no best match for the requested language could be found.
|
||||
|
||||
- It is not possible to **disable** language support in pygeoapi. The functionality is always on and a ``Content-Language``
|
||||
* It is not possible to **disable** language support in pygeoapi. The functionality is always on and a ``Content-Language``
|
||||
HTTP response header is always set. If results should be available in a single language, you'd have to set that language only
|
||||
in the pygeoapi configuration.
|
||||
|
||||
- Results returned from a provider may be in a different language than pygeoapi's own server language. The "raw" requested language
|
||||
* Results returned from a provider may be in a different language than pygeoapi's own server language. The "raw" requested language
|
||||
is always passed on to the provider, even if pygeoapi itself does not support it. For more information, see the `end user guide`_
|
||||
and the `developer guide`_.
|
||||
|
||||
@@ -248,20 +248,20 @@ This is all that is required. The pygeoapi API class will make sure that the cor
|
||||
Notes
|
||||
^^^^^
|
||||
|
||||
- If your provider implements any of the aforementioned ``query``, ``get`` and ``get_metadata`` methods,
|
||||
* If your provider implements any of the aforementioned ``query``, ``get`` and ``get_metadata`` methods,
|
||||
it **must** add a ``**kwargs`` or ``language=None`` parameter, even if it does not need to use the language parameter.
|
||||
|
||||
- Contrary to the pygeoapi server configuration, adding a ``language`` or ``languages`` (both are supported) property to the
|
||||
* Contrary to the pygeoapi server configuration, adding a ``language`` or ``languages`` (both are supported) property to the
|
||||
provider definition is **not** required and may be omitted. In that case, the passed-in ``language`` parameter language-aware provider methods
|
||||
(``query``, ``get``, etc.) will be set to ``None``. This results in the following behavior:
|
||||
|
||||
- HTML responses returned from the providers will have the ``Content-Language`` header set to the best-matching pygeoapi server language.
|
||||
- JSON(-LD) responses returned from providers will **not** have a ``Content-Language`` header if ``language`` is ``None``.
|
||||
* HTML responses returned from the providers will have the ``Content-Language`` header set to the best-matching pygeoapi server language.
|
||||
* JSON(-LD) responses returned from providers will **not** have a ``Content-Language`` header if ``language`` is ``None``.
|
||||
|
||||
- If the provider supports a requested language, the passed-in ``language`` will be set to the best matching
|
||||
* If the provider supports a requested language, the passed-in ``language`` will be set to the best matching
|
||||
`Babel Locale instance <http://babel.pocoo.org/en/latest/api/core.html#babel.core.Locale>`_.
|
||||
Note that this may be the provider default language if no proper match was found.
|
||||
No matter the output format, API responses returned from providers will always contain a best-matching ``Content-Language``
|
||||
header if one ore more supported provider languages were defined.
|
||||
|
||||
- For general information about building plugins, please visit the :ref:`plugins` page.
|
||||
* For general information about building plugins, please visit the :ref:`plugins` page.
|
||||
|
||||
Reference in New Issue
Block a user