--- title: "XYZ Tile API" slug: "xyztileapi" updated: 2024-01-24T00:27:45Z published: 2024-01-24T00:27:45Z canonical: "docs.metromap.com.au/xyztileapi" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.metromap.com.au/llms.txt > Use this file to discover all available pages before exploring further. # XYZ Tile API ## 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](https://cdn.document360.io/64eb4fa4-1b3d-47a1-871b-be0277fc940e/Images/Documentation/2XYZ_QGIS1%281%29.png) Change Max. Zoom Level to 22 to get the best of MetroMap high resolution imagery ![QGIS_XYZ_Tile_Zoom_Level_1.png](https://cdn.document360.io/64eb4fa4-1b3d-47a1-871b-be0277fc940e/Images/Documentation/QGIS_XYZ_Tile_Zoom_Level_1.png) Appoint a name and URL to the connection: ![XYZ_QGIS1.png](https://cdn.document360.io/64eb4fa4-1b3d-47a1-871b-be0277fc940e/Images/Documentation/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](https://cdn.document360.io/64eb4fa4-1b3d-47a1-871b-be0277fc940e/Images/Documentation/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](mailto:support@metromap.com.au) **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. | ---