XYZ Basemap Tile Service

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 multiple 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 than what is available in the mosaic, you will receive oversampled tiles.
By default, tiles are rendered in the PNG format with an alpha channel for transparency.
Grid is a rectangle with 2^z rows and 2^z 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¶

Most XYZ webtile clients expect a URL template. Here is the template for Planet's services (note that you'll always need to fill out mosaic_name):

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.

If you wanted to request a single specific PNG webtile (z=13, x=77, y=28) for the mosaic global_monthly_2016_04, then you'd make a request for:

https://tiles.planet.com/basemaps/v1/planet-tiles/global_monthly_2016_04_mosaic/gmap/13/77/28.png?api_key={api-key}

JPEG and WEBP format tiles can also be requested via the format argument. For example, to set up a XYZ connection for global_monthly_2016_04_mosaic that uses JPEG tiles instead of PNG, use:

https://tiles.planet.com/basemaps/v1/planet-tiles/global_monthly_2016_04_mosaic/gmap/{z}/{x}/{y}.png?api_key={api-key}&format=JPEG

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

Performing Pixel Provenance¶

The tile service supports a pixel provenance endpoint to determine the specific origin scene of a specific pixel within a basemap. The /pixprov endpoint gives UTFGrid responses of the contributing scene information. The keys attribute in the response maps to URLs from the Data API that correspond to the scene that the given pixel came from.

Use the following URL with mosaic_name replaced with the actual mosaic name to retrieve the origin scene.

https://tiles.planet.com/basemaps/v1/pixprov/{mosaic_name}/{z}/{x}/{y}.json?api_key={api-key}

Missing Tile Behavior¶

By default, the Tile Service returns an empty PNG file when data does not exist for a given webtile. This is for compatibility with some clients that do not properly handle 404 responses from an XYZ service and expect data to always exist globally. However, when using a different format this can be inconvenient. In those cases, a 404 response from the service is more appropriate and more easily handled by most clients than an empty tile in an unexpected file format. The empty=404 parameter controls the behavior of the Tile Service when there is no quad present at the requested webtile location. If it is specified, the result will be a 404 response with no content rather than a 200 response with an empty PNG. This parameter should always be used when requesting full bit depth tiles.

Using Full Bit Depth 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.

To retrieve numpy tiles, use a .npy extension along with format=npy and either proc=off for all bands or proc=<index> for pre-calculation of a specific index. To see the set of supported pre-calculated indices, visit the Remote Sensing Indices. Be sure to specify empty=404 as well, otherwise tiles with no data will return an empty PNG even with format=npy.

For example, to request all bands as a .npy format numpy array for a single tile (z=8, x=62, y=101) for the standard biweekly SR mosaic named ps_biweekly_sen2_normalized_analytic_subscription_2023-10-02_2023-10-16_mosaic use:

https://tiles.planet.com/basemaps/v1/planet-tiles/ps_biweekly_sen2_normalized_analytic_subscription_2023-10-02_2023-10-16_mosaic/gmap/8/62/101.npy?proc=off&format=npy&empty=404&api_key={api-key}

To request that same individual tile as floating point NDVI values in numpy format, use:

https://tiles.planet.com/basemaps/v1/planet-tiles/ps_biweekly_sen2_normalized_analytic_subscription_2023-10-02_2023-10-16_mosaic/gmap/8/62/101.npy?proc=ndvi&format=npy&empty=404&api_key={api-key}

Full Bit Depth GeoTIFF Tiles¶

Full bit depth GeoTIFF tiles are also supported. These allow full bit depth streaming of the same data you would retrieve via download into clients that support tif XYZ tiles (GDAL, QGIS, ArcGIS). To access these use format=geotiff, a .tif extension, and either proc=off for all bands or proc=<index> for pre-calculation of a particular remote sensing index. To see the set of supported pre-calculated indices, see Remote Sensing Indices.

To request all bands as a GeoTIFF tile for a single tile (z=8, x=62, y=101) use:

https://tiles.planet.com/basemaps/v1/planet-tiles/ps_biweekly_sen2_normalized_analytic_subscription_2023-10-02_2023-10-16_mosaic/gmap/8/62/101.tif?proc=off&format=geotiff&empty=404&api_key={api-key}

To request the same tile as NDVI values in a floating point GeoTIFF, use:

https://tiles.planet.com/basemaps/v1/planet-tiles/ps_biweekly_sen2_normalized_analytic_subscription_2023-10-02_2023-10-16_mosaic/gmap/8/62/101.tif?proc=ndvi&format=geotiff&empty=404&api_key={api-key}

To use GeoTIFF tiles in GDAL to allow full bit depth streaming into GIS platforms or programmatically access the data, you can configure an XML description of the tile server and use open that as a single dataset in GDAL or add it to QGIS or ArcPro (ArcPro will require renaming the .xml to a .tif extension).

The advantage of using full bit depth streaming in your desktop GIS is that you get the raw values that would be accessed via download, but without needing to download and merge individual quads. This also means you will need to use your GIS software to choose how to display the data (again, identically to what would happen if you downloaded the data). Similarly, you can analyze the overall dataset programmatically without needing to download data.

For example, to stream full bit depth data into QGIS (or work with it via gdal or rasterio) for a NICFI mosaic, you'd create an XML file similar to the following (changing the mosaic name as needed - this example is using planet_medres_normalized_analytic_2024-07_mosaic). Note that you'll need to either fill in your API key explicitly, or drop the api_key parameter from the URL and set GDAL_HTTP_USERPWD={your-api-key}: (note the trailing colon) in the environment:

<GDAL_WMS>
        <Service name="TMS">
        <ServerUrl>https://tiles.planet.com/basemaps/v1/planet-tiles/planet_medres_normalized_analytic_2024-07_mosaic/gmap/${z}/${x}/${y}.tif?api_key={api-key}&amp;empty=404&amp;format=geotiff&amp;proc=off</ServerUrl>
        </Service>
        <DataWindow>
            <UpperLeftX>-20037508.34</UpperLeftX>
            <UpperLeftY>20037508.34</UpperLeftY>
            <LowerRightX>20037508.34</LowerRightX>
            <LowerRightY>-20037508.34</LowerRightY>
            <TileLevel>15</TileLevel>
            <TileCountX>1</TileCountX>
            <TileCountY>1</TileCountY>
            <YOrigin>top</YOrigin>
        </DataWindow>
        <Projection>EPSG:3857</Projection>
        <BlockSizeX>256</BlockSizeX>
        <BlockSizeY>256</BlockSizeY>
        <BandsCount>5</BandsCount>
        <ZeroBlockHttpCodes>404,503</ZeroBlockHttpCodes>
        <ZeroBlockOnServerException>true</ZeroBlockOnServerException>
        <DataValues NoData="0 0 0 0 0" min="0 0 0 0 0" max="10000 10000 10000 10000 65535" />
        <DataType>uint16</DataType>
        <Cache/>
</GDAL_WMS>

To use that file in ArcGIS, save it with a .tif extension instead of .xml.

We are continually working to improve our technical documentation and support. Please help by sharing your experience with us.

Send Us Your Feedback

XYZ Basemap Tile Service

last updated: September 10, 2024

XYZ Protocol Overview¶