XYZ Basemap Tile Service

last updated: December 06, 2023

XYZ Protocol Overview

The XYZ protocol describes how a mapping client, often from within a browser or GIS application, can access tiled imagery. This is the same protocol that Planet Explorer uses to display tiled imagery. It provides a pyramid of tiles at 16 zoom levels so that it can efficiently be displayed in web browsers. As with other XYZ tiling services, Planet XYZ tiles have the following attributes:

  • Tiles are 256 x 256 pixels.
  • Tiles use the Web Mercator coordinate reference system (EPSG:3857).
  • Tiles are available between zoom levels 0 and 18, depending on the mosaic. If you request tiles that are a higher zoom level, you will receive oversampled tiles.
  • Tiles are rendered in the PNG format with an alpha channel for transparency.
  • Grid is a rectangle with 2z rows and 2z columns, where z is the zoom level.
  • The grid uses 0,0 as the top, left corner of the grid.
  • Tiles are found at the path z/x/y.png, where z is the zoom level, and x and y are the positions in the tile grid.

XYZ Basemap Tile Service Request Structure

https://tiles{0-3}.planet.com/basemaps/v1/planet-tiles/{mosaic_name}/gmap/{z}/{x}/{y}.png?api_key={api-key}

Enter your API key in your client to support these. If you are an individual making requests, leave out {0-3}. For continuous streaming, do not change z, x, y. They are dynamically updated as you pan across the area.

For example, enter this URL for all of these valid URLs:

https://tiles.planet.com/basemaps/v1/planet-tiles/global_monthly_2016_04_mosaic/gmap/13/77/28.png?api_key=FAKE1234567ABCAPIKEY

Using NumpyTiles

Another output option is using a numpy n-dimensional array using NumpyTiles for full bit depth streaming of Planet's data. It works similar to XYZ, but instead of the final output as a PNG, it is a numpy array. Web browsers only display 8 bits per pixel. When we display raster imagery in the browser, we are limited to eight bits of data that define a color. This is called a true or natural color because it conforms to visual expectations-the colors you see in the world. For example, green grass or gray pavement. However, for advanced band-analysis, you might need more information and in cases like those, so numpy tiles are helpful.

NumpyTiles is an open specification that Planet published on GitHub, designed to be both easy to serve and easy to parse on the client. “NumpyTiles” is a portmanteau of both “NumPy,” the popular Python numerical library, and “Tiles,” which refers to slippy-map tiles. Each NumpyTile is a NumpyArray which is 256 columns wide, 256 rows long, with any number of bands represented as additional dimensions to the array. NumpyTiles is compatible with any slippy map specification (WMTS, XYZ, TileJSON, OGC API - Tiles, etc), as it is just an alternate output format, like PNG or JPEG.

Numpy is valuable for ML applications too, because it removes one step of converting an image format to numpy. This returns a PNG file when there are blank tiles. Check the output to make sure it is a numpy array.

To add the XYZ Layer to QGIS, follow the instructions at Using Georeferenced Layers in QGIS.