XYZ Tile API
- 24 Jan 2024
- 3 Minutes to read
- Print
- DarkLight
- PDF
XYZ Tile API
- Updated on 24 Jan 2024
- 3 Minutes to read
- Print
- DarkLight
- PDF
Article summary
Did you find this summary helpful?
Thank you for 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
|
| Optional | VERSION | 1.0.0 |
| Optional | STYLE |
|
| √ | TileMatrixSet |
|
| √ | 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. |
