Overview

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 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 object detections will be served as vector features. Each feature in the feature collection from the API will reference an individual instance of an object 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
Well Pad Detection Mosaic Vector
Silo bag Detection Mosaic Vector
Building Change Detection Multiple Mosaics Vector
Road Change Detection Multiple Mosaics Vector

Summary Statistics

Many users are interested in getting a snapshot view of the activity occurring in their areas of interest by aggregating the counts of detections or area covered per land type over time. This time series data can be generated by our Summary Statistics Endpoint, available at api.planet.com/analytics/stats. This is a POST endpoint that you’ll need to leverage to generate a statistical report followed by a GET request to download the generated report.

Depending on the source imagery and result format, the statistics reports are formatted differently with different metadata.

Vector Results on Scenes

Vector results on scenes are formatted as a count of detections per time period and can be aggregated to a daily, weekly or monthly basis. For example, a report could be generated for a seaport showing how many vessels there were per day. For reports run on scenes, we provide additional metadata indicating how much of the AOI was captured within the specified time period and how much of that coverage was cloud-free. We break this data down showing how much of the AOI was covered by clouds, heavy haze, light haze, snow or shadow. This can help provide the data needed to normalize the results and prevent false spikes/valleys due to coverage or cloud issues. For more information on an approach to normalize detections, see this notebook tutorial.

Vector Results on Mosaics

Vector results on mosaics are formatted as counts per time period and are aggregated based on the mosaics that generated them. If an Analytic Feed is based on weekly basemaps, the statistical report would be on a weekly basis, if it was on a monthly basemap, the report would be on a monthly basis and so on. For example, a report could be generated for a county showing how many well pads there were per month if it was based on our monthly mosaic.

Raster Results on Mosaics

Raster results on mosaics are formatted as the number of square meters per land class (e.g. roads) over time and are aggregated based on the mosaics that generated them. If an Analytic Feed is based on weekly basemaps, the statistical report would be on a weekly basis, if it was on a monthly basemap, the report would be on a monthly basis and so on. For example, a report could be generated for a county showing how many square meters were classified as roads per month if it was based on our monthly mosaic. For reports that are run on mosaics, we provide additional metadata indicating the total number of square meters analyzed. This can help provide the data needed to normalize results when comparing differently sized AOIs.

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--yyyy-mm-dd”. You’ll most likely see several that look like the following:

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.

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.


Rate this guide: