Tile Services Overview

last updated: September 04, 2024

The API Tile Service and Basemap Tile Service make it easy to visualize Planet imagery in desktop or web mapping applications that support either the XYZ or the WMTS protocol. Planet tile services provide a way for web developers and GIS analysts to interact with, and derive value from Planet imagery without additional image processing.

Authentication

A valid Planet account is required to access either of the tile services (XYZ or WMTS). Authenticate by providing a valid api_key as a query parameter to all tile requests.

Note:

For all Planet tile services, you must be authenticated for the specific requested resource. If you do not have the correct permissions, the tile request results in a 404 error. To be properly authenticated, provide a valid api_key as a query parameter in all tile requests.

API Key Security Risk

There is a potential security risk with the Planet API tile service. If you are using your own API key to access tiles or Basemaps there is no security risk . However, if you are accessing tiles in an application where others can view the request, then the API key is potentially exposed. An example of this is available by viewing the Network tab of Developer Tools in your browser while logged in to your Planet Explorer account. Although the API key is secure in this example, it illustrates that the API key is exposed. To avoid the API key security risk, create a reverse proxy or store your API key as an environment variable.

A reverse proxy:

  • Is the most secure method for safely storing Planet API key credentials
  • Stores secure credentials that make requests for the application and passes request responses to the application
  • Stores and encrypts API keys in one location
  • Stores API keys with HTTPS over a Transport Layer Security (TLS) channel.
  • Provides greater web acceleration (faster requests and responses between the server and the client browser)
  • Provides load balancing configuration
  • Eliminates the risk of:
    • Exposing credentials to malicious clients
    • Updating API keys in the wrong location

You can create a reverse proxy from most cloud providers, including NGINX and Google Cloud Platform (GCP). Creating a secret with Secret Manager provides complete details on creating and accessing the secret key from the GCP Secret Manager.

Store the API Key as an Environment Variable

Store the API key as an environment variable, and use the git ignore command when pushing to the repository. This is not the recommended method and if your credentials are not encrypted, the risk of API key exposure remains. Do not use the API key environment variable with public applications.

To obtain a new API key, contact Planet Support if your API key is shared or exposed.

Tile Service URLs

The Planet tile services provide tiles by using the following domains:

  • https://tiles0.planet.com
  • https://tiles1.planet.com
  • https://tiles2.planet.com
  • https://tiles3.planet.com

Load more tiles concurrently in web browsers by using multiple subdomains. Libraries such as OpenLayers and Leaflet provide the ability to access all subdomains by using the proper string patterns.

API Tile Service

The API Tile Service acts as an extension to the Planet API by visually listing the Planet assets that are available in the item archive as tiles. The imagery returned by the tile service is a compressed version of the high-quality visual asset, making it easy to incorporate into any supporting client. Currently, only clients using the XYZ tile protocol are supported.

API Tile Service Request Structure

https://tiles{0-3}.planet.com/data/v1/{item_type}/{item_id}/{z}/{x}/{y}.png?api_key={api-key}

API Tile Service Request in Python with Basic HTTP Authentication

import os
# import os module to access environmental modules

import requests
from requests.auth import HTTPBasicAuth
# import helper functions to make Basic request to Planet API

PLANET_API_KEY = os.getenv('PL_API_KEY')
# Setup the API Key from the `PL_API_KEY` environment variable

BASE_URL = 'https://tiles{0-3}.planet.com/data/v1/{item_type}/{item_id}/{z}/{x}/{y}.png'

if PLANET_API_KEY is None:
    PLANET_API_KEY = '12345'
# pass in your API key

auth = HTTPBasicAuth(PLANET_API_KEY, '')
# HTTPBasicAuth() wants a username & password; you can pass an empty string for the password

res = requests.get(url=BASE_URL, auth=auth)

print(res.status_code)
# make a request to Tile Services API and test the response
Parameter Value
item_type Item type of the item to view.
item_id Item id of the item to view.
z Tile zoom level.
x Tile row in the grid.
y Tile column in the grid.

The following example is a complete URL for a tile request for the PSScene item with an id of 20161221_024131_0e19:

API Tile Service Example

  https://tiles1.planet.com/data/v1/PSScene/20161221_024131_0e19/14/12915/8124.png?api_key={api-key}

Basemap Tile Service

The Planet Basemap tile service provides access to tiles for weekly or monthly, color corrected global mosaics. The Basemap tile service works with any client that supports the XYZ or the WMTS protocol.

Details on Planet specifications are available in Planet Basemaps Product Specifications.

Learning Resources


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

Send Us Your Feedback