.. _ogcapi-maps:

Publishing maps to OGC API - Maps
=================================

`OGC API - Maps`_ provides geospatial data as web maps.

To add 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, bbox, width/height, crs, bbox-crs
   :align: left

   `MapScript`_,✅,✅,✅,✅
   `WMSFacade`_,✅,✅,✅,✅


Below are specific connection examples based on supported providers.

Connection examples
-------------------

MapScript
^^^^^^^^^

MapScript (`see website`_) is MapServer's scripting interface to map rendering.

To publish a map via MapScript, the path to data is required, as well as
the layer type (`options.type`).  To style the data, set `options.style`. If
no style is specified, the layer will be rendered with defaults.

MapServer layer types (`options.type`):

- `MS_LAYER_POINT`
- `MS_LAYER_LINE`
- `MS_LAYER_POLYGON`
- `MS_LAYER_RASTER`

Currently supported style files (`options.style`):

- OGC Styled Layer Descriptor (SLD)
- MapServer CLASS includes (i.e. file snippets with CLASS definitions)

.. code-block:: yaml

   providers:
       - type: map
         name: MapScript
         data: /path/to/data.shp
         options:
             type: MS_LAYER_POINT
             layer: foo_name
             style: ./foo.sld
         format:
            name: png
            mimetype: image/png
         storage_crs: http://www.opengis.net/def/crs/EPSG/0/4326

Projections are supported through EPSG codes (`options.projection`):        

.. code-block:: yaml

           options:
             type: MS_LAYER_POINT
             layer: foo_name
             projection: 32631

This parameter is optional, defaulting to WGS84 (4236).

This provider also supports `tile indexing <https://mapserver.org/optimization/tileindex.html>`_,
which lets MapScript create a mosaic on the fly, piecing together a set of files. 
In order to enable it, set `options.tileindex` to `True` and set the location of the index file on the `data` path.

.. code-block:: yaml

        providers:
          - type: map
            name: MapScript
            data: /data/index.shp
            options:
                type: MS_LAYER_RASTER
                tileindex: True
                layer: index
            format:
                name: png
                mimetype: image/png
            storage_crs: http://www.opengis.net/def/crs/EPSG/0/4326

The `options.tileindex` parameter is optional, defaulting to `False`.

WMSFacade
^^^^^^^^^

To publish a WMS via pygeoapi, the WMS base URL (`data`) and layer name (`options.layer`) is
required.  An optional style name can be defined via `options.style`.

.. code-block:: yaml

   providers:
       - type: map
         name: WMSFacade
         data: https://demo.mapserver.org/cgi-bin/msautotest
         options:
             layer: world_latlong
             style: default
             version: 1.3.0
         format:
               name: png
               mimetype: image/png
         storage_crs: http://www.opengis.net/def/crs/EPSG/0/4326

.. note::
  According to the `Standard <https://docs.ogc.org/is/20-058/20-058.html#_5df53b56-5468-4c9d-acac-6abfddd83ccf>`_, OGC API - Maps
  supports a `crs` and `bbox-crs` parameters, expressed as an uri or a CURIE. Currently, this provider supports CRS84 and various CRS from the EPSG namespace; for a matter of convenience, they can be expressed
  also as unsafe CURIEs.

  - `http://www.opengis.net/def/crs/EPSG/0/4326`
  - `[EPSG:4326]`
  - `EPSG:4326` (unsafe)
  - `CRS:84` (unsafe, for compatibility with WMS)
  - `OGC:CRS84` (unsafe)

  If `crs` is not provided, the server will default to the `storage_crs`; in case it does not exist, the default is `CRS84`.
  If `crs-bbox` is not provided, it will default to `CRS84`. If the `bbox` is not provided, it will default to `-180, -90, 180, 90`.
  
  The response headers will always contain the `Content-Crs` and `Content-Bbox`. Examples:

  - Content-Bbox: -180.0,-90.0,180.0,90.0
  - Content-Crs: http://www.opengis.net/def/crs/EPSG/0/4326
 
Data visualization examples
---------------------------

* list all collections

  * http://localhost:5000/collections
* overview of dataset

  * http://localhost:5000/collections/foo
* map (default format)

  * http://localhost:5000/collections/foo/map
* map with bbox subset

  * http://localhost:5000/collections/foo/map?bbox=-142,42,-52,84
* map with bbox and temporal subset

  * http://localhost:5000/collections/foo/map?bbox=-142,42,-52,84&datetime=2020-04-10T14:11:00Z
* map with bbox and bbox-crs

  * http://localhost:5000/collections/foo/map?bbox-crs=http%3A%2F%2Fwww.opengis.net%2Fdef%2Fcrs%2FEPSG%2F0%2F3857&bbox=4.022369384765626%2C50.690447870569436%2C4.681549072265626%2C51.00260125274477&width=800&height=600&transparent

* map with vertical subset  (``extents.vertical`` must be set in resource level config)

  * http://localhost:5000/collections/foo/map?bbox=-142,42,-52,84&subset=vertical(435)

.. _`OGC API - Maps`: https://ogcapi.ogc.org/maps
.. _`see website`: https://mapserver.org/mapscript/index.html