XYZ Tile API

24 Jan 2024
3 Minutes to read

Print
Share
Dark
Light
PDF

XYZ Tile API

Updated on 24 Jan 2024
3 Minutes to read

Print
Share
Dark
Light
PDF

Article Summary

Share feedback

Thanks for sharing your feedback!

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:

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

Appoint a name and URL to the connection:

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

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.

Was this article helpful?

What's Next

STAC

Table of contents

XYZ Tile API
Responses