Planet Analytics leverages computer vision to transform our imagery into Analytic Feeds that detect and classify objects, identify geographic features, and understand change over time across the globe. This user guide is intended to help users access the Analytic Feeds and leverage them to build applications and solutions.
Our Analytic Feed Viewer, located here, is a great example of what can be built on top of our Analytics API. For more details about our Analytic Feed Viewer, please visit our developer center here.
Authentication¶
The Analytics API uses Basic HTTP Authentication and requires that you have a Planet API key. Currently, anyone can sign up for a free account on our website. Once you're signed up, you can find your API key in your account settings. Authenticate by setting username to your API key.
Authentication Via Basic HTTP using Python:
import requests
# install requests module to make request
PL_API_KEY = '12345'
# set your Planet API key as a string
BASE_URL = "https://api.planet.com/analytics/"
BASIC_AUTH = (PL_API_KEY, '')
# construct tuple to access API via Basic Auth
feed_list_url = f'{BASE_URL}feeds?limit=1'
resp = requests.get(feed_list_url, auth=BASIC_AUTH)
if resp.status_code == 200:
print('Yay, you can access the Analytics API')
else:
print('Something is wrong:', resp.content)
# test your credentials and access to Analytics API
Authentication Via cURL:
curl --header "Authorization: api-key ${PL_API_KEY}"
https://api.planet.com/analytics/
Analytics API¶
The Analytics API is a RESTful API interface to provide programmatic access to Planet Analytic Feeds. It enables search and retrieval of analytic results within the user’s subscription. Find details about the supported resources and operations in the API reference documentation.
Analytic Feeds¶
An Analytic Feed represents the blueprint for what model and what processing needs to take place to create analytics output derived from Planet imagery. Each feed essentially represents an analytic capability that has been uniquely configured to optimize performance and quality, and each feed has unique types of outputs. For example, a Monthly Road Detection Feed represents roads detected on monthly Planet Basemaps, and outputs raster "segmentation mask" data. Many different types of Feeds are currently available through the Planet Analytics API, and we plan on releasing new feeds in the future.
Subscriptions¶
Users have subscriptions to feeds in a specific Area of Interest (AOI) and Time Interval of Interest (TOI). For example, a subscription could be Road Detection over 12 months in San Francisco, California. Users can get a list of their subscriptions from the Analytics API.
Results¶
When new imagery is published in a user's subscription, Planet’s computer vision models process the imagery and its output is added to a collection of results associated with the subscription. For example, if a user has a subscription for the Vessel Detection Feed, newly published daily imagery within that subscription AOI will be processed and new vessel detections will be added to the subscription results. Feature Collections results are ordered by creation date, with most recent collections listed first.
Each result contains reference links to the source imagery that was used to derive the result. This should enable you to download or reference the imagery as you deem appropriate.
Note: for Analytic Feeds that surface change over time, multiple source imagery references will be made. This is to enable users to be able to quickly find a “before” and “after” view.
Vector Results¶
For vector-based results, geojson outputs are stored in Web Feature Service collections. These detections will be served as vector features. Each feature in the feature collection from the API will reference an individual instance of a detection (e.g. a vessel) or change detection (e.g, building construction).
Raster Results¶
GeoTIFF outputs containing raster results will be served as links within a feature collection. Each feature in the feature collection from the Analytics API references a mosaic quad with links to the source (input imagery for the analytic operation) and target (results of the analytic operation (ie, roads or building pixels).
Available Feeds, imagery and Output Formats¶
| Feed | Source Imagery | Result Format |
|---|---|---|
| Building Detection | Mosaic | Raster |
| Road Detection | Mosaic | Raster |
| Vessel Detection | Scene | Vector |
| Plane Detection | Scene | Vector |
| Building Change Detection | Multiple Mosaics | Vector |
| Road Change Detection | Multiple Mosaics | Vector |
Web Map Tile Service¶
By leveraging Planet’s Webmap Tile Service (WMTS), you can stream source imagery and derived raster output into ArcGIS, QGIS or any other GIS you wish to use. Enter the URL shown below into your GIS to surface a list of raster items you have access to. https://api.planet.com/basemaps/v1/mosaics/wmts?api_key={api-key}
This will produce a list of the mosaic imagery you have access to - this includes both satellite imagery and derivative raster output (e.g. road detections). Our naming convention for derivative raster output is “SIF-
| Item Title | Description |
|---|---|
| Global Monthly 2020 01 Mosaic | This represents Planet’s global visual mosaic product for January 2020 |
| sif-b442c53b-fc72-4bee-bab4-0b7aa318ccd9-2020-01-01 | This represents the derivative raster output for a given Feed. This one is for the Feed ID “b442c53b-fc72-4bee-bab4-0b7aa318ccd9” which is a monthly building detection feed. |
Bringing these layers into your tool of choice will enable you to compare them against each other as well as other public or private datasets you leverage.
Learn more about how to leverage Planet’s WMTS in the tile service reference documentation.
OGC Features API¶
Planet's Analytics API adheres to the Open Geospatial Consortium's (OGC) Features API specification which means you can stream in vector detections into your GIS platform of choice through a Web Feature Service (WFS) integration. Just make sure you select the OGC Features as the version of WFS. Enter the URL shown below to surface a list of Analytics Results you have access to. https://api.planet.com/analytics/
Learn More¶
When you're ready to dive deeper into using Planet's Analytics API, you'll find a collection of guides and tutorials on Planet School. You may be interested in this Python tutorial: Converting Building Footprints to Vector Layers along with this collection of quickstart guides to working with Analytics API.
We are continually working to improve our technical documentation and support. Please help by sharing your experience with us.