1.. _raster.ogcapi:
2
3================================================================================
4OGCAPI -- OGC API Tiles / Maps / Coverage
5================================================================================
6
7.. versionadded:: 3.2
8
9.. shortname:: OGCAPI
10
11.. build_dependencies:: libcurl
12
13Access to server implementing OGC API - Tiles, OGC API - Maps or OGC API - Coverages.
14This driver has raster and vector capabilities.
15
16.. warning::
17
18    This driver is experimental, and has been developed to demonstrate work
19    related to the "Modular OGC API Workflows" initiative.
20    It implements non-finalized versions of OGC API - Tiles, - Maps and - Coverages.
21    Its interface may change at any time, or it might be removed.
22    It might also be eventually merged with the OGC API - Features driver.
23
24Driver capabilities
25-------------------
26
27.. supports_georeferencing::
28
29Dataset opening
30---------------
31
32The driver supports opening by:
33
34- passing a filename (with .moaw extension) containing a JSON document, like
35  the following, specifying a deferred processing
36
37  .. code-block:: json
38
39        {
40        "id" : "SampleRenderMapExecution",
41        "process" : "https://maps.ecere.com/ogcapi/processes/RenderMap",
42        "inputs" : [
43            { "id" : "transparent", "value" : false },
44            { "id" : "background", "value" : "navy" },
45            {
46                "id" : "layers",
47                "list" : [
48                    { "collection" : "https://maps.ecere.com/ogcapi/collections/NaturalEarth:physical:bathymetry" },
49                    { "collection" : "https://maps.ecere.com/ogcapi/collections/SRTM_ViewFinderPanorama" }
50                ]
51            }
52        ]
53        }
54
55- passing a string "OGCAPI:{url}" where {url} is the URL to a OGC API landing page
56  In that case the driver will return subdatasets with the different collections.
57
58- passing a string "OGCAPI:{url}" where {url} is the URL to a OGC API collection description
59
60
61When the driver opens a collection, for raster, it will look if tiles or maps
62API are advertized for it. It will use tiles API by default, and fallback to maps
63API when not available. It will also look at the image formats, and will prefer
64PNG When available.
65
66For vector collections, this driver handles the tiles API, with GeoJSON or
67Mapbox Vector tiles.
68
69When using the tiles API, the driver will use by default the WorldCRS84Quad tile
70matrix set when available
71
72Open options
73------------
74
75The following open options are available:
76
77- **API=AUTO/MAPS/TILES/COVERAGE/ITEMS**: Which API to use for data acquisition. Default is
78  AUTO. In AUTO mode, for raster access, coverage is used if available, and
79  fallback first to tiles and finally maps otherwise.
80  In AUTO mode, for vector access, tiles is used if available, and fallback to
81  GeoJSON items otherwise.
82
83- **IMAGE_FORMAT=AUTO/PNG/PNG_PREFERRED/JPEG/JPEG_PREFERRED**:
84  Which format to use for pixel acquisition, for tiles or map API.
85  Defaults to AUTO, which means
86  that PNG will be used if available, and fallback to JPEG otherwise.
87  If specifying PNG or JPEG, they must be available, otherwise the driver will
88  return an error. If specifying the one of the PNG_PREFERRED or JPEG_PREFERRED
89  value, the specified format will be used if available, and the driver will
90  fallback to the other format otherwise.
91
92- **VECTOR_FORMAT=AUTO/GEOJSON/GEOJSON_PREFERRED/MVT/MVT_PREFERRED**:
93  Which format to use for vector data acquisition. Defaults to AUTO, which means
94  that MVT (Mapbox Vector Tiles) will be used if available, and fallback to GEOJSON otherwise.
95  If specifying MVT or GEOJSON, they must be available, otherwise the driver will
96  return an error. If specifying the one of the MVT_PREFERRED or GEOJSON_PREFERRED
97  value, the specified format will be used if available, and the driver will
98  fallback to the other format otherwise.
99
100- **TILEMATRIXSET=id**:
101  Identifier of the required tile matrix set. Only used with the tiles API.
102  If this tile matrix set is not available, the driver will fail.
103  If this option is not specified, the driver will automatically select one of
104  the available tile matrix sets.
105  TILEMATRIXSET and PREFERRED_TILEMATRIXSET options are mutually exclusive.
106
107- **PREFERRED_TILEMATRIXSET=id**:
108  Identifier of the preferred tile matrix set. Only used with the tiles API.
109  If this tile matrix set is not available, or if this option is not specified,
110  the driver will automatically select one of the available tile matrix sets.
111  TILEMATRIXSET and PREFERRED_TILEMATRIXSET options are mutually exclusive.
112
113- **TILEMATRIX=id**: Identifier of a particular tile matrix (zoom level) of
114  the select tile matrix set. If not specified, all available tile matrix are
115  returned as overviews (for raster data), or layers (for vector data)
116
117- **CACHE=YES/NO**: Whether to enable block/tile caching. Only for tiles API,
118  and with raster data. Defaults to YES.
119
120- **MAX_CONNECTIONS=number**: Maximum number of connections for parallel tile
121  downloading. Only for tiles API, and with raster data. Defaults to 5.
122
123- **MINX/MINY/MAXX/MAXY=number**: Bounds in SRS of TileMatrixSet to which to
124  restrict the exposed dataset/layers.
125