WMTS -- OGC Web Map Tile Service

Driver short name

WMTS

Added in version 2.1.

Build dependencies

libcurl

Access to WMTS layers is possible with the GDAL WMTS client driver (needs Curl support). It support both RESTful and KVP protocols.

Driver capabilities

Supports Georeferencing

This driver supports georeferencing

Supports VirtualIO

This driver supports virtual I/O operations (/vsimem/, etc.)

Open syntax

The WMTS driver can open :

a local service description XML file, whose syntax is described in the below section :
```
gdalinfo gdal_wmts.xml
```

the content of a description XML file provided as filename :

gdalinfo "<GDAL_WMTS><GetCapabilitiesUrl>http://maps.wien.gv.at/wmts/1.0.0/WMTSCapabilities.xml</GetCapabilitiesUrl><Layer>lb</Layer></GDAL_WMTS>"

a local GetCapabilities response of a WMTS service :
```
gdalinfo WMTSCapabilities.xml
```

the URL to the GetCapabilities response of a WMTS service:

gdalinfo "http://maps.wien.gv.at/wmts/1.0.0/WMTSCapabilities.xml"

the URL to the GetCapabilities response of a WMTS service, prefixed with WMTS:, and possibly with optional layer, tilematrixset, tilematrix/zoom_level, style and extendbeyonddateline parameters, with the following syntax WMTS:url[,layer=layer_id][,tilematrixset=tms_id][,tilematrix=tm_id|,zoom_level=level][,style=style_id][,extendbeyonddateline=yes/no].
```
gdalinfo "WMTS:http://maps.wien.gv.at/wmts/1.0.0/WMTSCapabilities.xml"
```
```
gdalinfo "WMTS:http://maps.wien.gv.at/wmts/1.0.0/WMTSCapabilities.xml,layer=lb"
```

the WMTS: prefix with open options

gdalinfo WMTS: -oo URL=http://maps.wien.gv.at/wmts/1.0.0/WMTSCapabilities.xml -oo LAYER=lb

In any of the above syntaxes, if several layers are present and no layer disambiguation was done with the layer parameter/open option, or if a layer has more than one style or a tile matrix set, a list of subdatasets will be returned. If there is only one layer, it will be opened on the default style and the first tile matrix set listed.

Starting with GDAL 3.10, specifying the -if WMTS option to command line utilities accepting it, or WMTS as the only value of the papszAllowedDrivers of GDALOpenEx(), also forces the driver to recognize the passed filename/URL, when it is not using subdataset syntax (it can typically be used to force open a HDF5 file that would be nominally recognized by the HDF5 driver).

Open options

The following open options are available:

URL=value: URL (or filename for local files) to GetCapabilities response document. Required if not specified in the connection string (e.g if using "WMTS:" only)
LAYER=value: Layer identifier
TILEMATRIXSET=value: Tile Matrix Set identifier, which determines the CRS into which the layer will be exposed. Must be one of the listed tile matrix for the layer.
TILEMATRIX=value: Tile Matrix identifier. Must be one of the listed tile matrix of the select tile matrix set for the layer. Mutually exclusive with ZOOM_LEVEL. If not specified the last tile matrix, i.e. the one with the best resolution, is selected.
ZOOM_LEVEL=value: Index of the maximum zoom level tile matrix to use for the full resolution GDAL dataset (lower zoom levels will be used for overviews). The first one (ie the one of lower resolution) is indexed 0. Mutually exclusive with TILEMATRIX. If not specified the last tile matrix, i.e. the one with the best resolution, is selected.
STYLE=value: Style identifier. Must be one of layer.
EXTENDBEYONDDATELINE=[YES/N]: Whether to make the extent go over dateline and warp tile requests. See ExtendBeyondDateLine parameter of the local service description XML file described below for more details.
EXTENT_METHOD=[AUTO/LAYER_BBOX/TILE_MATRIX_SET/MOST_PRECISE_TILE_MATRIX]: Defaults to AUTO. GDAL needs to retrieve an extent for the layer. Different sources are possible. WGS84BoundingBox element at the Layer level, BoundingBox elements with potentially several CRS at the Layer level, BoundingBox of the TileMatrixSet definitions shared by all layers, and TileMatrixLimit definitions at the Layer level. By default (AUTO), GDAL will try first with a WGS84BoundingBox/BoundingBox corresponding to the CRS implied by the select TileMatrixSet. If not available, if will fallback to a BoundingBox in another CRS and reproject it to the selected CRS. If not available, it will fallback to the most precise tile matrix of the selected TileMatrixSet and will clip it with the bounding box implied by the most precise zoom level of the TileMatrixLimit of the layer. If LAYER_BBOX is specified, only WGS84BoundingBox/BoundingBox elements are considered. If TILE_MATRIX_SET is specified, the BoundingBox element of the selected TileMatrixSet will be used. If MOST_PRECISE_TILE_MATRIX is specified, the implicit extent of the most precise tile matrix will be used.
CLIP_EXTENT_WITH_MOST_PRECISE_TILE_MATRIX=[YES/NO]: (GDAL >= 3.4.2) Whether to use the implied bounds of the most precise TileMatrix to clip the layer extent (defaults to NO if the layer bounding box is used, YES otherwise)
CLIP_EXTENT_WITH_MOST_PRECISE_TILE_MATRIX_LIMITS=[YES/NO]: (GDAL >= 3.4.2) Whether to use the implied bounds of the most precise TileMatrixLimit to clip the layer extent (defaults to NO if the layer bounding box is used, YES otherwise)

Local service description XML file

It is important that there be no spaces or other content before the <GDAL_WMTS> element.

<GDAL_WMTS>
<GetCapabilitiesUrl>http://foo/WM TSCapabilities.xml</GetCapabiliti esUrl>	URL (or filename for local files) to GetCapabilities response document (required). For a KVP only server, will be like http://end_point?SERVICE=WMTS&amp ;REQUEST=GetCapabilities .
<ExtraQueryParameters>foo=bar&	URL query parameters to add to all requests (GetCapabilities, GetTile, GetFeatureInfo) (added in GDAL 3.5.1)
<Layer>layer_id</Layer>	Layer identifier (optional, but may be needed to disambiguate between several layers)
<Style>style_id</Style>	Style identifier. Must be one of the listed styles for the layer. (optional, but may be needed to disambiguate between several styles)
<TileMatrixSet>tile_matrix_set_id </TileMatrixSet>	Tile Matrix Set identifier. Must be one of the listed tile matrix set for the layer. (optional, but may be needed to disambiguate between several tile matrix sets)
<TileMatrix>tile_matrix_id</TileM atrix>	Tile Matrix identifier. Must be one of the listed tile matrix of the select tile matrix set for the layer. (optional, GDAL >= 2.2. Exclusive with ZoomLevel. If not specified the last tile matrix, ie the one with the best resolution, is selected)
<ZoomLevel>int_value</ZoomLevel>	Index of the maximum zoom level / tile matrix to use. The first one (ie the one of lower resolution) is indexed 0. (optional, GDAL >= 2.2. Exclusive with TileMatrix. If not specified the last tile matrix, ie the one with the best resolution, is selected)
<Format>image/png</Format>	Tile format, used by GetTile requests. Must be one of the listed Format for the layer. (optional, but may be needed to disambiguate between several Format)
<InfoFormat>application/xml</Info Format>	Info format, used by GetFeatureInfo requests. Must be one of the listed InfoFormat for the layer. (optional, but may be needed to disambiguate between several InfoFormat)
<DataWindow>	Define extents of the data. (optional, when not specified the driver will query the declared extent of the layer, and if not present fallback to the extent of the select tile matrix set, taking into account potential tile matrix set limits)
<UpperLeftX>-180.0</UpperLeftX>	X (longitude/easting) coordinate of upper-left corner, in the SRS of the tile matrix set. (required if DataWindow is present)
<UpperLeftY>90.0</UpperLeftY>	Y (latitude/northing) coordinate of upper-left corner, in the SRS of the tile matrix set. (required if DataWindow is present)
<LowerRightX>180.0</LowerRightX>	X (longitude/easting) coordinate of lower-right corner, in the SRS of the tile matrix set. (required if DataWindow is present)
<LowerRightY>-90.0</LowerRightY>	Y (latitude/northing) coordinate of lower-right corner, in the SRS of the tile matrix set. (required if DataWindow is present)
</DataWindow>
<Projection>EPSG:4326</Projection >	Declared projection, in case the one of the TileMatrixSet is not desirable (optional, defaults to value of the TileMatrixSet)
<BandsCount>4</BandsCount>	Number of bands/channels, 1 for grayscale data, 3 for RGB, 4 for RGBA. (optional, defaults to 4)
<DataType>Byte</DataType>	Band data type, one of: Byte, Int16, UInt16, Int32, UInt32, Float32, Float64, etc.. (optional, defaults to Byte)
<ExtendBeyondDateLine>false</Exte ndBeyondDateLine>	Whether to make the extent go over dateline and warp tile requests. Only appropriate when the 2 following conditions are met (optional, defaults to false): for a geodetic SRS or EPSG:3857, with tile matrix sets such as the whole [-180,180] range of longitude is entirely covered by an integral number of tiles (e.g. GoogleMapsCompatible). AND when the layer BoundingBox in the SRS of the tile matrix set covers the whole [-180,180] range of longitude, and that there is another BoundingBox in another SRS that is centered around longitude 180. If such alternate BoundingBox is not present in the GetCapabilities document, DataWindow must be explicitly specified OR when the layer BoundingBox in the SRS of the tile matrix set extends beyond the dateline.
<Cache>	Enable local disk cache. Allows for offline operation. (optional, cache is disabled when absent, but it is present in the autogenerated XML, can be overridden with GDAL_ENABLE_WMS_CACHE=NO
<Path>./gdalwmscache</Path>	Location where to store cache files. It is safe to use same cache path for different data sources. (optional, defaults to ./gdalwmscache if GDAL_DEFAULT_WMS_CACHE_PATH configuration option is not specified) /vsimem/ paths are supported allowing for temporary in-memory cache
<Type>file</Type>	Cache type. Now supported only 'file' type. In 'file' cache type files are stored in file system folders. (optional, defaults to 'file')
<Depth>2</Depth>	Number of directory layers. 2 will result in files being written as cache_path/A/B/ABCDEF... (optional, defaults to 2)
<Extension>.jpg</Extension>	Append to cache files. (optional, defaults to none)
</Cache>
<MaxConnections>2</MaxConnections >	Maximum number of simultaneous connections. (optional, defaults to 2)
<Timeout>300</Timeout>	Connection timeout in seconds. (optional, defaults to 300)
<OfflineMode>true</OfflineMode>	Do not download any new images, use only what is in cache. Useful only with cache enabled. (optional, defaults to false)
<UserAgent>GDAL WMS driver (http://www.gdal.org/frmt_wms.htm l)</UserAgent>	HTTP User-agent string. Some servers might require a well-known user-agent such as "Mozilla/5.0" (optional, defaults to "GDAL WMS driver (http://www.gdal.org/frmt_wms.htm l)").
<Accept>mimetype>/Accept>	HTTP Accept header to specify the MIME type of the expected output of the server. Empty by default. (added in GDAL 3.5.1)
<UserPwd>user:password</UserPwd>	User and Password for HTTP authentication (optional).
<UnsafeSSL>true</UnsafeSSL>	Skip SSL certificate verification. May be needed if server is using a self signed certificate (optional, defaults to false, but set to true in autogenerated XML).
<Referer>http://example.foo/</Ref erer>	HTTP Referer string. Some servers might require it (optional).
<ZeroBlockHttpCodes>204,404</Zero BlockHttpCodes>	Comma separated list of HTTP response codes that will be interpreted as a 0 filled image (i.e. black for 3 bands, and transparent for 4 bands) instead of aborting the request. (optional, defaults to non set, but set to 204,404 in autogenerated XML)
<ZeroBlockOnServerException>true< /ZeroBlockOnServerException>	Whether to treat a Service Exception returned by the server as a 0 filled image instead of aborting the request. (optional, defaults to false, but set to true in autogenerated XML)
</GDAL_WMTS>

Starting with GDAL 2.3, additional HTTP headers can be sent by setting the GDAL_HTTP_HEADER_FILE configuration option to point to a filename of a text file with “key: value” HTTP headers.

GetFeatureInfo request

WMTS layers can be queried (through a GetFeatureInfo request) with the gdallocationinfo utility, or with a GetMetadataItem("Pixel_iCol_iLine", "LocationInfo") call on a band object.

gdallocationinfo my_wmts.xml -geoloc -11547071.455 5528616 -xml -b 1

Generation of WMTS service description XML file

The WMTS service description XML file can be generated manually, or created as the output of the CreateCopy() operation of the WMTS driver, only if the source dataset is itself a WMTS dataset. Said otherwise, you can use gdal_translate with as source dataset any of the above syntax mentioned in "Open syntax" and as output an XML file. For example:

gdal_translate "WMTS:http://maps.wien.gv.at/wmts/1.0.0/WMTSCapabilities.xml,layer=lb" wmts.xml -of WMTS

generates the following file:

<GDAL_WMTS>
  <GetCapabilitiesUrl>http://maps.wien.gv.at/wmts/1.0.0/WMTSCapabilities.xml</GetCapabilitiesUrl>
  <Layer>lb</Layer>
  <Style>farbe</Style>
  <TileMatrixSet>google3857</TileMatrixSet>
  <DataWindow>
    <UpperLeftX>1800035.8827671</UpperLeftX>
    <UpperLeftY>6161931.622311067</UpperLeftY>
    <LowerRightX>1845677.148953537</LowerRightX>
    <LowerRightY>6123507.385072636</LowerRightY>
  </DataWindow>
  <BandsCount>4</BandsCount>
  <Cache />
  <UnsafeSSL>true</UnsafeSSL>
  <ZeroBlockHttpCodes>404</ZeroBlockHttpCodes>
  <ZeroBlockOnServerException>true</ZeroBlockOnServerException>
</GDAL_WMTS>

The generated file will come with default values that you may need to edit.

Caching

Caching of remote pixel data is possible by setting a <Cache> element in the WMS (or WMTS) configuration file.

Before GDAL 3.9, if the <Path> sub-element of <Cache> was not specified, the directory of the cache was ./gdalwmscache (that is to say a gdalwmscache subdirectory of the current directory), unless the GDAL_DEFAULT_WMS_CACHE_PATH configuration option is specified.

Starting with GDAL 3.9, the directory of the cache is set according to the following logic (first listed criterion is prioritary over following ones):

Value of the <Path> sub-element of <Cache>, if specified.
${GDAL_DEFAULT_WMS_CACHE_PATH} if GDAL_DEFAULT_WMS_CACHE_PATH is set.
${XDG_CACHE_HOME}/gdalwmscache if the XDG_CACHE_HOME configuration option is set.
On Unix, ${HOME}/.cache/gdalwmscache if the HOME configuration option is set.
On Windows, ${USERPROFILE}/.cache/gdalwmscache if the USERPROFILE configuration option is set.
${CPL_TMPDIR}/gdalwmscache_${USER} if CPL_TMPDIR and USER configuration options are set.

If CPL_TMPDIR is not set, then TMPDIR is used, or TEMP

If USER is not set, USERNAME is used if set. If neither USERNAME or USER are set, the md5sum of the filename of the configuration file is used)
./gdalwmscache_{md5sum(filename)} if none of the above mentioned configuration options are set.

Note that if the <Unique> element is set to true (which is its default value), a subdirectory whose name is the md5sum of the filename of the configuration file is appended to the caching directory.

The actual caching directory can be got by querying the CACHE_PATH metadata item on the dataset.

Configuration options

Configuration options can be specified in command-line tools using the syntax --config <NAME>=<VALUE> or using functions such as CPLSetConfigOption() (C) or gdal.config_options (Python). The following configuration options are available:

GDAL_MAX_CONNECTIONS=<integer>: (GDAL >= 3.2) Defaults to 2. Set the maximum number of simultaneous connections.
GDAL_ENABLE_WMS_CACHE=[YES/NO]: Defaults to YES. Can be set to NO to disable caching of pixel data.
GDAL_DEFAULT_WMS_CACHE_PATH=<string>: Sets the WMS/WMTS cache path is the <Cache> element is included in the WMS/WMTS configuration file without a <Path> element.