geopython · tomkralidis · Oct 27, 2025 · Sep 19, 2025 · Sep 19, 2025 · Sep 19, 2025
diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
@@ -219,21 +219,25 @@ default.
                   end: 2007-10-30T08:57:29Z  # end datetime in RFC3339
                   trs: http://www.opengis.net/def/uom/ISO-8601/0/Gregorian  # TRS
           providers:  # list of 1..n required connections information
-              # provider name
-              # see pygeoapi.plugin for supported providers
-              # for custom built plugins, use the import path (e.g. mypackage.provider.MyProvider)
-              # see Plugins section for more information
-              - type: feature # underlying data geospatial type: (allowed values are: feature, coverage, record, tile, edr)
-                default: true  # optional: if not specified, the first provider definition is considered the default
-                name: CSV
+              - type: feature # underlying data geospatial type. Allowed values are: feature, coverage, record, tile, edr
+                name: CSV # required: plugin name or import path. See Plugins section for more information.
                 data: tests/data/obs.csv  # required: the data filesystem path or URL, depending on plugin setup
                 id_field: id  # required for vector data, the field corresponding to the ID
-                uri_field: uri # optional field corresponding to the Uniform Resource Identifier (see Linked Data section)
-                time_field: datetimestamp  # optional field corresponding to the temporal property of the dataset
-                title_field: foo # optional field of which property to display as title/label on HTML pages
-                properties:  # optional: only return the following properties, in order
+
+                # optional fields
+                uri_field: uri # field corresponding to the Uniform Resource Identifier (see Linked Data section)
+                time_field: datetimestamp  # field corresponding to the temporal property of the dataset
+                title_field: foo # field of which property to display as title/label on HTML pages
+                default: true  # if not specified, the first provider definition is considered the default
+                properties:  # if specified, return only the following properties, in order
                     - stn_id
                     - value
+                format: # default format
+                    name: GeoJSON  # required: format name
+                    mimetype: application/json  # required: format mimetype
+                options:  # optional options to pass to provider (i.e. GDAL creation)
+                    option_name: option_value
+                include_extra_query_parameters: false  # include extra query parameters that are not part of the collection properties (default: false)
                 # editable transactions: DO NOT ACTIVATE unless you have setup access control beyond pygeoapi
                 editable: true  # optional: if backend is writable, default is false
                 # coordinate reference systems (CRS) section is optional
@@ -245,12 +249,7 @@ default.
                     - http://www.opengis.net/def/crs/EPSG/0/4326
                 storage_crs: http://www.opengis.net/def/crs/OGC/1.3/CRS84 # optional CRS in which data is stored, default: as 'crs' field
                 storage_crs_coordinate_epoch: : 2017.23 # optional, if storage_crs is a dynamic coordinate reference system
-                format:  # optional default format
-                    name: GeoJSON  # required: format name
-                    mimetype: application/json  # required: format mimetype
-                options:  # optional options to pass to provider (i.e. GDAL creation)
-                    option_name: option_value
-                include_extra_query_parameters: false  # include extra query parameters that are not part of the collection properties (default: false)
+                always_xy: false # optional should CRS respect axis ordering
 
       hello-world:  # name of process
           type: process  # REQUIRED (collection, process, or stac-collection)

diff --git a/docs/source/crs.rst b/docs/source/crs.rst
@@ -3,42 +3,95 @@
 CRS support
 ===========
 
-pygeoapi supports the complete specification: `OGC API - Features - Part 2: Coordinate Reference Systems by Reference corrigendum`_.
-The specified CRS-related capabilities are available for all Feature data Providers.
+pygeoapi supports multiple Coordinate Reference Systems (CRS). 
+This enables the import and export of any data according to dedicated projections.
+A "projection" is specified with a CRS identifier.
+In particular CRS support allows for the following:
+
+* to specify the CRS in which the data is stored, in pygeoapi the `storage_crs` config option
+* to specify the list of valid CRS representations, in pygeoapi the `crs` config option
+* to publish these in the collection metadata
+* the `bbox-crs=` query parameter to indicate that the `bbox=` parameter is encoded in that CRS
+* the `crs=` query parameter for a collection or collection item
+* the HTTP response header `Content-Crs` denotes the CRS of the Feature(s) in the data returned
+
+Although GeoJSON mandates WGS84 in longitude, latitude order, the client and server may still agree on other CRSs.
+
+
+Background
+----------
+
+pygeoapi implements the complete specification: 
+`OGC API - Features - Part 2: Coordinate Reference Systems by Reference corrigendum`_.
+Under the hood, pygeoapi uses the well-known `pyproj`_ Python wrapper to the `PROJ`_ library.
+For information on implementing CRS on custom plugins, see `Implementation`_.
+
+CRS support exists for the following OGC APIs:
+
+.. csv-table::
+   :header: OGC API, bbox-crs, filter-crs, crs
+   :align: left
+
+   :ref:`OGC API - Features<ogcapi-features>`,✅,✅,✅
+   :ref:`OGC API - Maps<ogcapi-maps>`,✅,❌,❌
+   :ref:`OGC API - Coverages<ogcapi-coverages>`,✅,❌,❌
 
 Configuration
 -------------
 
-For details visit the :ref:`configuration` section for Feature Providers. At this moment only the 'URI' CRS notation format is supported.
+The CRS of a collection is defined in the provider block of your resource.
+The configuration controls how the `crs` related query parameters behave.
 
 
-* `crs` - list of CRSs supported
-* `storage_crs` - CRS in which the data is stored (must be in `crs` list)
-* `storage_crs_coordinate_epoch` - epoch of `storage_crs` for a dynamic coordinate reference system
+* ``crs`` - list of CRSs supported
+* ``storage_crs`` - CRS in which the data is stored (must be in `crs` list)
+* ``storage_crs_coordinate_epoch`` - epoch of `storage_crs` for a dynamic coordinate reference system
+* ``always_xy`` - CRS should ignore authority on axis order, disobeying `ISO-19111`_ (default: false) 
 
+.. note::
+    bbox-crs and filter-crs are used to convert the request geometry to the configured ``storage_crs``.
+    An error will be returned for any interaction with CRS not included in the configured ``crs`` list.
 
-These per-Provider configuration fields are all optional. Default for CRS-values is `http://www.opengis.net/def/crs/OGC/1.3/CRS84`, so "WGS84" with lon/lat axis ordering.
-If the storage CRS of the spatial feature collection is a dynamic coordinate reference system,
-`storage_crs_coordinate_epoch` configures the coordinate epoch of the coordinates.
+The per-Provider configuration fields are all optional,
+with the following as default configuration:
+
+.. code-block:: yaml
+
+    crs:
+        - http://www.opengis.net/def/crs/OGC/1.3/CRS84
+        - http://www.opengis.net/def/crs/OGC/1.3/CRS84h
+    storage_crs: http://www.opengis.net/def/crs/OGC/1.3/CRS84
+
+.. note::
+    Configuration is done with URI formats like http://www.opengis.net/def/crs/OGC/1.3/CRS84. 
+    Both `URI` and `URN` CRS notation format are supported.
+    The `EPSG:` format like EPSG:4326 is outside the scope of the OGC standard.
 
-There is also support for CRSs that support height like `http://www.opengis.net/def/crs/OGC/1.3/CRS84h`. In that case
-bbox parameters (see below) may contain 6 coordinates.
 
 Metadata
 --------
 
-The conformance class `http://www.opengis.net/spec/ogcapi-features-2/1.0/conf/crs` is present as a `conformsTo` field
-in the root landing page response.
+The conformance class http://www.opengis.net/spec/ogcapi-features-2/1.0/conf/crs is
+present as a `conformsTo` field in the root landing page response.
 
 The configured CRSs, or their defaults, `crs` and `storageCrs` and optionally `storageCrsCoordinateEpoch` will be present in the "Describe Collection" response.
 
+.. note::
+    If the storage CRS of the spatial feature collection is a dynamic coordinate reference system,
+    `storage_crs_coordinate_epoch` configures the coordinate epoch of the coordinates.
+
+.. note::
+    There is also support for CRSs that support height like `http://www.opengis.net/def/crs/OGC/1.3/CRS84h`. In that case
+    bbox parameters (see below) may contain 6 coordinates.
+
 Parameters
 ----------
 
 The `items` query supports the following parameters:
 
-* `crs` - the CRS in which Features coordinates should be returned, also for the 'get single item' request
-* `bbox-crs` - the CRS of the `bbox` parameter (only for Providers that support the `bbox` parameter)
+* ``crs`` - the CRS in which Features coordinates should be returned, also for the 'get single item' request
+* ``bbox-crs`` - the CRS of the `bbox` parameter (for Providers that support the `bbox` parameter)
+* ``filter-crs`` - the CRS of the CQL filter expression (for Providers that support `CQL` filters)
 
 If any or both of these parameters are specified, their CRS-value should be from the advertised CRS-list in the Collection metadata (see above).
 
@@ -52,21 +105,29 @@ Note that the values of these parameters may need to be URL-encoded.
 Implementation
 --------------
 
-CRS and BBOX CRS support is implemented for all Feature Providers. Some details may help understanding (performance) implications.
+CRS and BBOX CRS support is implemented for all Feature Providers.
+Some details may help understanding (performance) implications.
 
-BBOX CRS Parameter
+bbox-crs Parameter
 ^^^^^^^^^^^^^^^^^^
 
-The `bbox-crs` parameter is handled at the common level of pygeoapi, thus transparent for Feature Providers.
-Obviously the Provider should support `bbox`.
-A transformation of the `bbox` parameter is performed
+The ``bbox-crs`` parameter is handled at the common level of pygeoapi.
+A transformation of the request `bbox` parameter is performed
 according to the `storage_crs` configuration. Then the (transformed) `bbox` is passed with the
 other query parameters to the Provider instance.
 
-CRS Parameter
+filter-crs Parameter
+^^^^^^^^^^^^^^^^^^^^
+
+The ``filter-crs`` parameter is handled at the common level of pygeoapi.
+A transformation of the request `CQL` filter is performed
+according to the `storage_crs` configuration. Then the (transformed) `filter` is passed with the
+other query parameters to the Provider instance.
+
+crs Parameter
 ^^^^^^^^^^^^^
 
-When the value of the `crs` parameter differs from the Provider data Storage CRS, the response Feature coordinates
+When the value of the ``crs`` parameter differs from the Provider data Storage CRS, the response Feature coordinates
 need to be transformed to that CRS. As some Feature Providers like PostgreSQL or OGR may support native
 coordinate transformation, pygeoapi delegates transformation to those Providers, passing the `crs` with the other query parameters.
 
@@ -245,4 +306,7 @@ Or you may specify both `crs` and `bbox-crs` and thus `bbox` in that CRS `http:/
     .
     .
 
+.. _`ISO-19111`: http://docs.opengeospatial.org/as/18-005r5/18-005r5.html
 .. _`OGC API - Features - Part 2: Coordinate Reference Systems by Reference corrigendum`: https://docs.opengeospatial.org/is/18-058r1/18-058r1.html
+.. _`PROJ`: https://proj.org/
+.. _`pyproj`: https://pyproj4.github.io/pyproj/stable
diff --git a/docs/source/plugins.rst b/docs/source/plugins.rst
@@ -7,6 +7,9 @@ In this section we will explain how pygeoapi provides plugin architecture for da
 
 Plugin development requires knowledge of how to program in Python as well as Python's package/module system.
 
+.. seealso::
+   :ref:`publishing` for configuration of default plugins.
+
 Overview
 --------
 

diff --git a/docs/source/publishing/ogcapi-coverages.rst b/docs/source/publishing/ogcapi-coverages.rst
@@ -77,7 +77,7 @@ The `Xarray`_ provider plugin reads and extracts `NetCDF`_ and `Zarr`_ data.
          time_field: time
          # optionally specify the coordinate reference system of your dataset
          # else pygeoapi assumes it is WGS84 (EPSG:4326).
-         storage_crs: 4326
+         storage_crs: http://www.opengis.net/def/crs/OGC/1.3/CRS84
          format:
             name: netcdf
             mimetype: application/x-netcdf

diff --git a/docs/source/publishing/ogcapi-edr.rst b/docs/source/publishing/ogcapi-edr.rst
@@ -59,7 +59,7 @@ The `xarray-edr`_ provider plugin reads and extracts `NetCDF`_ and `Zarr`_ data
          time_field: time
          # optionally specify the coordinate reference system of your dataset
          # else pygeoapi assumes it is WGS84 (EPSG:4326).
-         storage_crs: 4326
+         storage_crs: http://www.opengis.net/def/crs/OGC/1.3/CRS84
          format:
             name: netcdf
             mimetype: application/x-netcdf
@@ -94,11 +94,6 @@ The `xarray-edr`_ provider plugin reads and extracts `NetCDF`_ and `Zarr`_ data
    S3 URL. Any parameters required to open the dataset using fsspec can be added
    to the config file under `options` and `s3`, as shown above.
 
-.. note::
-   When providing a `storage_crs` value in the EDR configuration, specify the 
-   coordinate reference system using any valid input for 
-   `pyproj.CRS.from_user_input`_. 
-
 
 SensorThingsEDR
 ^^^^^^^^^^^^^^^
@@ -147,5 +142,4 @@ Data access examples
 .. _`xarray`: https://docs.xarray.dev/en/stable/
 .. _`NetCDF`: https://en.wikipedia.org/wiki/NetCDF
 .. _`Zarr`: https://zarr.readthedocs.io/en/stable
-.. _`pyproj.CRS.from_user_input`: https://pyproj4.github.io/pyproj/stable/api/crs/coordinate_system.html#pyproj.crs.CoordinateSystem.from_user_input
 .. _`OGC Environmental Data Retrieval (EDR) (API)`: https://ogcapi.ogc.org/edr
diff --git a/docs/source/publishing/ogcapi-features.rst b/docs/source/publishing/ogcapi-features.rst
@@ -37,19 +37,13 @@ parameters.
    `TinyDB`_,✅/✅,results/hits,✅,✅,✅,✅,✅,❌,✅,✅
 
 .. note::
-
-   * All Providers that support `bbox` also support the `bbox-crs` parameter. `bbox-crs` is handled within pygeoapi core.
-   * All Providers support the `crs` parameter to reproject (transform) response data. Some, like PostgreSQL and OGR, perform this natively.
+   For more information on CRS transformations, see :ref:`crs`.
 
 
 Connection examples
 -------------------
 
 Below are specific connection examples based on supported providers.
-To support `crs` on queries, one needs to configure both a list of supported CRSs, and a 'Storage CRS'.
-See also :ref:`crs` and :ref:`configuration`. When no CRS information is configured the
-default CRS/'Storage CRS' value http://www.opengis.net/def/crs/OGC/1.3/CRS84 is assumed.
-That is: WGS84 with lon,lat axis-ordering as in standard GeoJSON.
 
 CSV
 ^^^