XYZ Tile API

  • Updated on Jan 24, 2024
  • Published on Mar 10, 2020
  • 3 minute(s) read

XYZ Tile API

XYZ Tiles, also known as slippy map tiles, is a method of expressing map tile mosaics, indexed by (x,y) offsets and zoom levels (z).

Unlike WMTS, there is no formal Get Capabilities request to obtain meta data about a tile service, however we have an Imagery API endpoint that will return available layers with bounding box in JSON format

Most applications have in-built knowledge of the mosaic and how to access the correct tile to fulfil a view (For example, QGIS). XYZ Tiles uses a REST interface where a request for a tile includes the desired map layer, x, y and z values as part of the URL. URLs are typically of the format. You must replace the parameters shown in shown in [square brackets]

TMS vs XYZ

The different between XYZ and TMS is that the y-axis is flipped. XYZ can therefore convert from to TMS (and back again) using the following generic code statement to flip the y coordinate.

y = (2^z) - y - 1

https://api-v3.metromap.com.au/tiles/xyz/Australia_latest/{z}/{y}/{x}.png?key=[API KEY]

https://api-v3.metromap.com.au/tiles/xyz/[layername]/{z}/{y}/{x}.{format}?key=[API KEY]&contrastfilter=[contrastfilter]&brightnessfilter=[brightnessfilter]&unsharpmaskfilter=[unsharpmaskfilter]&contrast=[contrast]&brightness=[brightness]&umradius=[umradius]&umpercent=[umpercent]

XYZ Specification

Parameter Accept format Purpose Note
[layerid]* int or string the id of the required map layer This can also be the name of the layer (For example, Australia_latest)
{z}* int zoom level of the tile These parameters are not necessary to be change to see the images (most of the software will recognise the curly bracket and automatically substitute a number accordingly) See example below.
{y}* int vertical location offset of the tile (aka. row)
{x}* int horizontal location offset of the tile (aka. column)
{format}* str specify the format of the tile Available formats are:'webp', 'jpg', 'jpeg', 'png', 'jpgpng'
[API KEY]* string the API key A valid API key, otherwise a 401 Error will be given.
[contrastfilter] boolean Contrast filter is on or off
[brightnessfilter] boolean Brightness filter is on or off
[unsharpmaskfilter] boolean Unsharpmask filter is on or off
[contrast] float Amount of contrast enhancement
[brightness] float Amount of brightness enhancement
[um_radius] int Unsharp mask filter’s Blur Radius
[um_percent] int Unsharp mask filter’s Unsharp strength Value in percent

(star(*) indicates the parameter is mandatory)

  • Example in QGIS v3.xx

Create New Connection:
XYZ_QGIS1.png

Change Max. Zoom Level to 22 to get the best of MetroMap high resolution imagery
QGIS_XYZ_Tile_Zoom_Level_1.png



Appoint a name and URL to the connection:
XYZ_QGIS1.png

Note: substitute a valid API key to the URL after ‘key’ parameter and a valid layer id/name (see specification above)

Drag the service to the layer then the image will be shown on the map
XYZ_QGIS3.png

Your account must have permission to access this service, to request access please contact your MetroMap Account Manager or email MetroMap Support


Click to see previous version

REQUEST=GetCapabilities

https://api.metromap.com.au/metromapkey/wmts?key={api-key}&SERVICE=WMTS&REQUEST=GetCapabilities

REQUEST=GetTile

https://api.metromap.com.au/metromapkey/wmts?key={api-key}&SERVICE=WMTS&REQUEST={request}&LAYER={layer}&FORMAT={format}&TileMatrixSet={tilematrixset}&TileMatrix={tilematrix}&TileRow={row}&TileCol={col}

If REQUEST=GetTile, you must specify the following parameters:

Required Key Value
√ LAYER The Identifier of the tile. (e.g. Melbourne_2019_5_GM) If you are unsure, use REQUEST=GetCapabilities to get a XML file listing all avaliable tiles and the identifier of each tile.
√ FORMAT Format of the return tile image
  • image/jpeg
  • image/webp
  • image/png
Optional VERSION 1.0.0
Optional STYLE
  • default
√ TileMatrixSet
  • GoogleCRS84QuadExt:epsg:4326
  • GoogleMapsCompatibleExt:epsg:3857
  • OGC:1.0:GlobalCRS84Pixel
  • OGC:1.0:GoogleMapsCompatible
√ TileMatrix Value differ based on the TileMatrixSet you choose. For a list of accepted value of each of the TileMatrixSet, refer to the bottom section of the Capabilities XML
√ TileRow Row number of the tile
√ TileCol Column number of the tile

Example of a GetTile Request:

https://api.metromap.com.au/metromapkey/wmts?key={api-key}&REQUEST=GetTile&SERVICE=WMTS&LAYER=Melbourne_2019_5_GM&FORMAT=image/jpeg&TileMatrixSet=GoogleCRS84QuadExt:epsg:4326&TileMatrix=20&TileRow=643142&TileCol=947623

Responses

The following table describes the possible HTTP response status codes to the URL request and the surveys response fields:

Code Description
200 OK
400 Bad Request. Returned when the request is invalid. This means either the format is wrong, or a value is out of range.
401 Unauthorized. Returned when the API key is invalid.
403 Forbidden. Returned when not allowed to access the requested location.
404 Not Found. Returned when cannot find any surveys for the requested condition.
5XX Server Error. Returned when something is wrong in the server side.