XYZLayer

XYZ Layer

Quick start

The example below, running in the Mappia calculator - click it to run it live. Full-size picture

  1. Run it

    Click the picture: the map opens right here and runs the example. Nothing is saved, and nothing to install.

  2. Try it
    • Zoom in on the topographic map: more detailed OpenTopoMap tiles load at each zoom level.
    • Turn OpenTopoMap off with the eye button in the layer panel: the basemap shows underneath.
    • Replace url with another service’s ${z}/${x}/${y} address and run it again.
  3. Make it yours

    Copy the query, change it - the key parameters are below - and run it again in the playground, or paste it into the Mappia editor to save it as your map.

Key parameters

ParameterExampleWhat it does
sourcexyzMakes the layer fetch ready-made tiles, addressed by zoom, column and row, from url.
urlhttps://a.tile.opentopomap.org/${z}/${x}/${y}.pngThe tile address. ${z}, ${x} and ${y} are replaced by the zoom, column and row of each tile.
nameopentopomapA unique identifier for the layer: any text no other layer of the query uses.
opacity0.9From 0 (invisible) to 1 (solid); lower it to see the layers underneath.
visibilitytrueStarts the layer turned on. The user can still switch it in the layer panel.

Every parameter, with its type and default, is in the reference at the end of this page.

Complete example

The query 11 lines · runs as is 
// XYZ layer: tiles addressed by zoom/column/row; ${z}, ${x} and ${y} are replaced per tile.
[
  {
    title: "OpenTopoMap",
    name: "opentopomap",
    source: "xyz",
    url: "https://a.tile.opentopomap.org/${z}/${x}/${y}.png",
    visibility: true,
    opacity: 0.9,
  },
];

Customize it

Write the placeholders as ${z}, ${x}, ${y}

The dollar sign and the braces are both needed. Older examples wrote $z/$x/$y, which is not replaced, so every tile request fails. Put each placeholder where the service expects it - some services put the row before the column:

{
  title: "Satellite imagery",
  name: "esri_imagery",
  source: "xyz",
  url: "https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/${z}/${y}/${x}",
  visibility: true,
}

Which services work

Any service that serves square tiles in the usual web scheme - Web Mercator, row 0 at the top - the scheme of OpenStreetMap and most online basemaps. A TMS service that counts rows from the bottom shows its tiles in the wrong places.

Services that need a key

Put the key in url, as the service documents it. Anyone who opens the map can read the query and its key, so use a key restricted to your site. Check each service’s terms of use and attribution rules before publishing a map with it.

Use it offline

The tiles of an XYZ layer can be downloaded for use without a connection - see offline areas.

To offer several basemaps the user can switch between, see the background map picker. For vector data (points, lines, polygons) rather than images, use a file layer.

Real maps that use it

Simple XYZ Layer Example

Reference: the parameters used here

Generated from the platform source. Every entry, searchable, is in the API reference; the raw data is api.json. Open an entry for its description, parameters and example; # links to it.

Layer properties

LayersProperties1 entry
Keys of a layer object: which map it shows (name, source, styles), how it looks (title, opacity, visibility) and how its row and panel behave.

source

String= 'local'property# Defines the source from where the maps declared at the name will be loaded from.

Defines the source from where the maps declared at the name will be loaded from. The Source can be one of the following:

  • 'local': The maps in the name will be loaded from the CSR servers

  • 'calculate': The maps in the name gonna be used to calculate a new map in the expression() function and the result will be displayed as the Layer

  • 'file': The map will be loaded from a file or other custom source. For this, you need to define the file type in the 'type' property and the file where the map should be loaded. For example, for a JSON file, you also need to define the 'json' property.

  • 'xyz': The map will be loaded from an url by the XYZ protocol. The url property is required for this type of source. You can find more informations about the XYZ protocol at: https://developers.planet.com/docs/basemaps/tile-services/xyz/

// Example of how to load a map with the local source
[
  {
     title: 'Map rendered by a local source',
     color: '#666699',
     elements: [
        {
           title: 'Map with local source',
           name: 'CSR:paises',
           source: 'local',
           visibility: true,
        },
     ],
  },
]
// Example of how to load a map with the calculated source
[
  {
     title: 'Map rendered based on calculation',
     color: '#666699',
     elements: [
        {
           title: 'Filtering a part of the map',
           name: 'CSR:geologia',
           source: 'calculate',
           visibility: true,
           updateAutomatically: true,
           expression: function(layersVals, inputs) {
              // layerVals have the value of the legend applied in every pixel of the map
              let mapValue = layersVals[0];

              // Remove every type of relief that is not 'Mantiqueira'
              if(mapValue != 'Mantiqueira') { // If the pixel is not 'Mantiqueira'
                 return undefined; // Don't show the pixel
              }

              // If the pixel is 'Mantiqueira', return the value of the pixel
              return mapValue;
           },
        },
     ],
  },
]
// Example of how to load a map with the file source
[
  {
     title: 'Map rendered based on file source',
     color: '#FFA500',
     elements: [
        {
           title: 'Map with file source',
           name: 'example:map_file_source',
           source: 'file',
           visibility: true,
           // The map is rendered based on the GeoJSON below
           // The GeoJSON needs to be in EPSG:3857
           json: JSON.stringify(
              {
                 "type": "Polygon",
                 "crs": {
                    "type": "name",
                    "properties": {
                       "name": "EPSG:3857"
                    }
                 },
                 "coordinates": [
                    [
                       [
                          -625570.6,
                          6465993.0,
                       ],
                       [
                          -305006.9,
                          6696510.8,
                       ],
                       [
                          -546330.2,
                          6768547.6,
                       ],
                       [
                          -445478.6,
                          7053093.0,
                       ],
                       [
                          -279794.0,
                          7056694.8,
                       ],
                       [
                          -359034.5,
                          7337638.4,
                       ],
                       [
                          -211359.0,
                          7485313.8,
                       ],
                       [
                          62380.8,
                          6955843.3,
                       ],
                       [
                          220861.7,
                          6909019.4,
                       ],
                       [
                          91195.5,
                          6700112.6,
                       ],
                       [
                          213658.1,
                          6682103.4,
                       ],
                       [
                          -625570.6,
                          6465993.0,
                       ],
                    ],
                 ],
              }
           ),
        },
     ],
  },
]
// Example of how to load a map with the XYZ source
// The XYZ source is used to load a map from a URL that contains the {z}, {x} and {y} placeholders
// The {z} is the zoom level, {x} is the longitude and {y} is the latitude
[
  {
     title: 'Map rendered by a XYZ source',
     color: '#666699',
     elements: [
        {
           title: 'Base map loaded by XYZ source',
           // The name of the map that will be added. This name must be unique
           name: 'planet:planet',
           source: 'xyz',
           // The url of the map that will be loaded. The ${z}, ${x} and ${y} placeholders will be replaced by the map library
           url: 'https://tiles.planet.com/basemaps/v1/planet-tiles/planet_medres_visual_2021-09_mosaic/gmap/${z}/${x}/${y}.png?api_key=PLAK78456687760442eaa3d3da16aaac5f2d',
           visibility: true,
        },
     ],
  },
]

Tile layers (xyz)

XYZLayer1 entry
source: "xyz": tiles of a tile service, addressed by ${z}, ${x} and ${y} in url.
View complete tile layer documentation API here.

url

String# Defines the url where the map can be fetched from.

Defines the url where the map can be fetched from. Use the ${x} ${y} ${z} as placeholder for x, y and z coordinates.

"https://tiles.planet.com/basemaps/v1/planet-tiles/planet_medres_visual_2021-09_mosaic/gmap/${z}/${x}/${y}.png?api_key=b24ae87a99624d2cbd8ed6aeb9703280"