# WMTS -- OGC Web Map Tile Service

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

## 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 WTMS service :

      gdalinfo WMTSCapabilities.xml

- the URL to the GetCapabilities response of a WTMS service:

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

- the URL to the GetCapabilities response of a WTMS 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 URL (required), LAYER, TILEMATRIXSET, TILEMATRIX, ZOOM_LEVEL, STYLE, EXTENDBEYONDDATELINE.

      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.

## 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/WMTSCapabilities.xml</GetCapabilitiesUrl> | 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 .
<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</TileMatrix> | 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</InfoFormat> | 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)
<ExtendBeyondDateLine>false</ExtendBeyondDateLine> | 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, absent by default, but enabled in autogenerated XML)
<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)
<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.html)</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.html)").
<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/</Referer> | HTTP Referer string. Some servers might require it (optional).
<ZeroBlockHttpCodes>204,404</ZeroBlockHttpCodes> | 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> |

## 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.

## See Also:

- OGC WMTS Standard
- GDAL WMS driver documentation page