Basemaps API
The Basemaps API enables developers to access and download Planet Basemaps products.
Within the Basemaps API, the terms "basemaps" and "mosaics" are often used interchangeably.
To learn more about Basemaps products, see the product page.
Key Concepts
The Basemaps API is organized around the following key concepts:
- series: time-series collections of related mosaics (e.g. Global Monthly)
- mosaics: individual mosaics or basemaps and their associated data and metadata
Data for a mosaic can be downloaded as quads (tiled data in Cloud Optimized GeoTIFF format) directly from Basemaps API, or accessed as tiles using the Tiles API.
Access
Access to the Basemaps API (listing and downloading series and mosaics) is based on your Planet plan. You will need your Planet API key and an active plan with Basemaps access to view and download these products. The ability to view mosaics and download data is constrained by your Area of Access.
Usage
Series
A series is a growing time-series of related mosaics created on a regular cadence. Its basemaps may change over time if the temporal period of access allows.
List series
List series using the /basemaps/v1/series endpoint:
- CURL
curl --request GET \
-u "${PL_API_KEY}:" \
--url "https://api.planet.com/basemaps/v1/series/"
Series can also be filtered by name:
- CURL
curl --request GET \
-u "${PL_API_KEY}:" \
--url "https://api.planet.com/basemaps/v1/series/?name__is=Global%20Monthly"
Mosaics
List mosaics
Mosaics belong to a series, but they can also be listed separately and filtered by name or other attributes.
- CURL
curl --request GET \
-u "${PL_API_KEY}:" \
--url "https://api.planet.com/basemaps/v1/mosaics/"
Filtering mosaics by name:
- CURL
curl --request GET \
-u "${PL_API_KEY}:" \
--url "https://api.planet.com/basemaps/v1/mosaics/?name__is=${MOSAIC_NAME}"
Browsing mosaics within a series:
- CURL
curl --request GET \
-u "${PL_API_KEY}:" \
--url "https://api.planet.com/basemaps/v1/mosaics/${SERIES_ID}/mosaics/"
Get single mosaic
Requesting a single mosaic returns metadata and links.
- CURL
curl --request GET \
-u "${PL_API_KEY}:" \
--url "https://api.planet.com/basemaps/v1/mosaics/${MOSAIC_ID}/"
For each basemap, there is an endpoint for searching for downloadable quads and, if enabled, a link to an XYZ tile service for streaming.
Get mosaic quads
Quads are downloadable Cloud Optimized GeoTIFF files. They are organized as a tiled grid. Search for quads for a mosaic by providing
the mosaic name and a bounding box given by lx,ly,ux,uy (lower x, lower y, upper x, upper y in degrees).
- CURL
curl --request GET \
-u "${PL_API_KEY}:" \
--url "https://api.planet.com/basemaps/v1/mosaics/${MOSAIC_ID}/quads/?bbox=${LX},${LY},${UX},${UY}"
The response contains quads that intersect with the provided bounding box. Quad metadata includes direct download links for each file.
WMTS GetCapabilities
A WMTS capabilities document is available for each series, all basemaps, or a specific basemap. Similar to the XYZ tile service link, third-party software may consume this service.
For more on WMTS and XYZ tile services, see the Tiles API documentation.
Example: Browsing Mosaics to Download Quads or Import into GIS Software
A typical workflow for a user with access to several series over a period of time might be to:
- list series and determine which one is suitable for a given task
- list basemaps within the series, selecting one or more based on time(s) of interest
- use the quad search endpoint with an AOI to query each basemap and iterate over the quads, downloading them
- alternately, fetch the XYZ or WMTS tile service link and paste into third-party GIS software (QGIS or other compatible mapping client)
- CURL
# List series
curl --request GET \
-u "${PL_API_KEY}:" \
--url "https://api.planet.com/basemaps/v1/series/"
# For the selected series, list mosaics.
# This URL is also available as a link for each entry in the list series response.
curl --request GET \
-u "${PL_API_KEY}:" \
--url "https://api.planet.com/basemaps/v1/mosaics/${SERIES_ID}/mosaics/"
# Select an individual mosaic, and look up metadata.
# This link is also available in the entry for each mosaic in the list mosaics response.
curl --request GET \
-u "${PL_API_KEY}:" \
--url "https://api.planet.com/basemaps/v1/mosaics/${MOSAIC_ID}/"
# Find quads over an AOI for the selected mosaic
# the bbox parameter must contain two corners (lower left and upper right) of a bounding box in the format lx,ly,ux,uy.
# The response contains links that can be used to directly download quad files in GeoTIFF format.
curl --request GET \
-u "${PL_API_KEY}:" \
--url "https://api.planet.com/basemaps/v1/mosaics/${MOSAIC_ID}/quads/?bbox=-87.1,35,-87,35.1"
# Alternately, use the GetCapabilities URL with compatible GIS software.
# note: most GIS software may only require the URL. This example uses curl to fetch the full document
# in XML format.
curl --request GET \
--url "https://api.planet.com/basemaps/v1/mosaics/${MOSAIC_ID}/wmts?api_key=${PL_API_KEY}"