Querying Results

List Collections

https://api.planet.com/analytics/collections

The collections endpoint returns all of the results from different subscriptions that are enabled for a particular api_key. Each result within the collection describes a result of running a particular feed over the spatial area of interest and its temporal start-time and end-time defined in the subscription.

Example: List Collections

CURL
Python

curl "https://api.planet.com/analytics/collections" \
    -H "Authorization: api-key $PL_API_KEY"

import os
import requests
from requests.auth import HTTPBasicAuth

API_KEY = os.getenv("PL_API_KEY")
if not API_KEY:
    raise ValueError(
        "Please set the PL_API_KEY environment variable as your Planet API key"
    )


def list_collections():
    auth = HTTPBasicAuth(API_KEY, "")
    resp = requests.get("https://api.planet.com/analytics/collections", auth=auth)
    if not resp.ok:
        raise Exception(f"Failed to list collections: {resp.text}")
    return resp.json()

Below is a description of the properties of each collection of results returned by the collections endpoint.

Table 1: collections response

Metadata Field	Description	Sample
created	Timestamp when the result was created (in UTC)	2019-03-08T18:11:57.488Z
description	Description of the Collection as entered by the Planet Analytics Admin	Building Detection in New Cairo
id	UUID for the result	1ce86055-cad0-4960-bdf3-32763c17f19b
title	Title of the Collection as entered by the Planet Analytics Admin	New Cairo Buildings
links	Links to the collections endpoint, to the specific collection of results this result belongs to, and to all of the results generated within this collection of results	[ { "href": "https://api.planet.com/analytics/collections/0c400b73-17e9-43be-884a-c30851d79ca3", "rel": "self" }, { "href": "https://api.planet.com/analytics/collections/0c400b73-17e9-43be-884a-c30851d79ca3/items", "rel": "items" }, { "href": "https://api.planet.com/analytics/collections", "rel": "collections" } ]

Query Collection Results

https://api.planet.com/analytics/collections{collection ID}/items

Example: Query results for a collection (For example, a subscription)

CURL
Python

curl https://api.planet.com/analytics/collections/$SUBSCRIPTION_ID/items \
    -H "Authorization: api-key $PL_API_KEY"

import os
import requests
from requests.auth import HTTPBasicAuth

API_KEY = os.getenv("PL_API_KEY")
if not API_KEY:
    raise ValueError(
        "Please set the PL_API_KEY environment variable as your Planet API key"
    )


def query_results(subscription_id):
    auth = HTTPBasicAuth(API_KEY, "")
    resp = requests.get(
        f"https://api.planet.com/analytics/collections/{subscription_id}/items",
        auth=auth,
    )
    if not resp.ok:
        raise Exception(f"Failed to query results: {resp.text}")
    return resp.json()

The shape of the response will depend on the type of feed run over the subscription. The sections below describe the structure of the response for raster-based and vector-based results.

Raster Results

Each result in a raster-based feature collection references a quad from the feed over which an operation has been executed. The result references the target quad through the ["links"]["target-quad"] property. This link allows users to download a two-band GeoTIFF corresponding to the quad. The first band contains the results of the analytic operations as a binary mask with a value of 0, indicating the absence of a detection, and value of 255, indicating the presence of a detection for each pixel in the source quad. For example, a building detection feed would produce a value of 0 where it does not detect buildings and a value of 255 where it does detect buildings. The second band is the alpha channel passed through from the source mosaic quad with a value of 255 indicating valid pixels and a value of 0 indicating invalid pixels.

Table 2: raster-based results

Metadata Field	Description	Sample
created	Timestamp when the result was created (in UTC)	2019-03-08T18:11:57.488Z
geometry	The spatial extent of the resulting quad's area.	{ "type": "Polygon", "coordinates": [ [ [ 103.849296569824, 1.2513119542594 ], [ 103.880882263184, 1.2513119542594 ], [ 103.880882263184, 1.27293604010387 ], [ 103.849296569824, 1.27293604010387 ], [ 103.849296569824, 1.2513119542594 ] ] ] }
id	Result identifier	50e7d65b-9ec6-4ec1-8f46-c80bcbfffb2b
links: self	Link for the result (self)	{ "href": "https://api.planet.com/analytics/collections/2d28b64b-1561-4a6f-8294-1a85aac2e3f6/items/50e7d65b-9ec6-4ec1-8f46-c80bcbfffb2b", "rel": "self" }
Links: source-quad	Link to the source quad which is the imagery used to generate the detection output	{ "href": "https://api.planet.com/analytics/collections/2d28b64b-1561-4a6f-8294-1a85aac2e3f6/items/50e7d65b-9ec6-4ec1-8f46-c80bcbfffb2b/resources/source-quad", "rel": "source-quad" }
Links: target-quad	Link to the target quad which is the analytic output file	{ "href": "https://api.planet.com/analytics/collections/2d28b64b-1561-4a6f-8294-1a85aac2e3f6/items/50e7d65b-9ec6-4ec1-8f46-c80bcbfffb2b/resources/target-quad", "rel": "target-quad" }
observed	Date-time at which the source imagery was captured.	2019-03-20T07:57:18.186039Z
source_mosaic_name	The source mosaic upon which derivation is made. This is the unique identifier that can be used to source the mosaic from the Planet Mosaics WMTS service.	global_monthly_2018_07_mosaic
source_quad_id	Unique identifier of the original mosaic quad upon which the detection operation is executed, described as X-Y tile identifiers (More info on Page 16 of Planet Basemaps Product Specification)	434-1216
target_mosaic_name	Unique name of mosaic for querying the Planet Mosaics WMTS service or Planet Mosaics API.	sif-b8ee0ab1-4500-485d-80b1-a24d92ee4cd5-2018-07-01
target_quad_id	Raster output of the detection, described in UUID format.	434-1216

Vector Results

Object detection on scenes

Each Item in a vector-based feature collection references an instance of a detected object. The Analytics API provides the location coordinates of the object along with metadata associated with it.

Table 3: vector based model detections on scenes

Metadata Field	Description	Sample
created	Time stamp when the item was created in UTC (check)	2019-03-27T14:14:52.896Z
geometry	The bounding box coordinates of the detection / result.	{ "type": "Polygon", "coordinates": [ [ [ 103.849296569824, 1.2513119542594 ], [ 103.880882263184, 1.2513119542594 ], [ 103.880882263184, 1.27293604010387 ], [ 103.849296569824, 1.27293604010387 ], [ 103.849296569824, 1.2513119542594 ] ] ] }
id	Item identifier	df7d8723-996a-4085-a714-e145a56ac5d9
link: Self	Link to the item in the feature collection	https://api.planet.com/analytics/collections/886b4dbb-b878-4f6b-b000-0d96cbf71d4d/items/df7d8723-996a-4085-a714-e145a56ac5d9
link: source-image-info	Link to the source image metadata in which the item was detected	https:/api.planet.com/analytics/collections/886b4dbb-b878-4f6b-b000-0d96cbf71d4d/items/df7d8723-996a-4085-a714-e145a56ac5d9/resources/source-image-info
model_id	Unique identifier of the computer vision model used to create this item	01D3FJCDHEZ1JS56150B7YR8VT
model_version	Time stamp indicating the version of the computer vision model used to create this item	2019-03-29T21:01:06Z
object_area_m2	The area of item's physical footprint, described in square meters.	21899.365647766444
object_diagonal_m	Diagonal length of the item's physical footprint, described in meters	216.4834894839776
object_length	Length of item's physical footprint, described in meters	178.2395839691162
object_width	Width of the item's physical footprint, described in meters	122.86477088928223
source_item_id	Unique ID of the source asset that the item was derived from, described as a string.	20190320_075718_0f35
source_asset_type	Type of asset derived from the source item, described as analytic or visual.	visual
source_item_type	The class of spacecraft and/or processing level of an item upon which derivation is made.	PSScene3Band
observed	Date-time at which the source imagery was captured.	2019-03-20T07:57:18.186039Z
score	Confidence of detection resulting in the item in the range `[0.0, 1.0]` with a value of 1.0 indicating full confidence	0.9995234
source_cloud_cover	Average percentage of cloud cover in the source asset from which the object was detected	0.1
xmax_px	Location of the detection along the horizontal axes in pixel coordinates	2076
xmin_px	Location of the detection along the horizontal axes in pixel coordinates	2020
ymax_px	Location of the detection along the vertical axes in pixel coordinates	3047
ymin_px	Location of the detection along the vertical axes in pixel coordinates	2969

Change detection on mosaics

Each Item in a vector-based feature collection for roads & building change references an instance of a newly constructed building or road. The Analytics API provides the location coordinates of an aggregation of 8x8 pixel grid cells containing the object (or "change cells") and associated metadata. Each result references a quad from the feed over which an operation has been executed, specifically the most recent mosaic after which the change has occurred. The result references the source quad through the ["links"]["source-quad"] property.

Table 4: vector based model detections on mosaics

Metadata Field	Description	Sample
created	Timestamp when the result was created (in UTC)	2020-04-08T18:11:57.488Z
geometry	The coordinates of the aggregation of 8x8 pixel grid cells containing the change	{ "type": "Polygon", "coordinates": [ [ [ 103.849296569824, 1.2513119542594 ], [ 103.880882263184, 1.2513119542594 ], [ 103.880882263184, 1.27293604010387 ], [ 103.849296569824, 1.27293604010387 ], [ 103.849296569824, 1.2513119542594 ] ] ] }
id	Result identifier	acd47acd-1301-4baf-8315-5a745824ae09
links: self	Link for the result (self)	{ "href": "https://api.planet.com/analytics/collections/acd47acd-1301-4baf-8315-5a745824ae09/items/acd47acd-1301-4baf-8315-5a745824ae09", "rel": "self" }
links: source-quad	Link to the source quad which is the imagery used to generate the detection output	{ "href": "https://api.planet.com/analytics/collections/acd47acd-1301-4baf-8315-5a745824ae09/items/acd47acd-1301-4baf-8315-5a745824ae09/resources/source-quad", "rel": "source-quad" }
date_after	Date of the most recent time period, corresponding to date at which the change was detected	"2020-03-01 00:00:00 +0000 UTC"
date_before	Estimated date of time period before the change event. This is fixed to 2 months prior to date_after. The true change event may be earlier in some cases	"2019-11-01T00:00:00Z"
object_area_m2	The area of the item's physical footprint, described in square meters. The area is smaller than the area of the change cell	458.7873390337813
observed	Date-time at which the source imagery (source_mosaic_after) was captured. For Change Detection it corresponds to the same date as date_after (legacy)	"2020-03-01T00:00:00Z"
source_mosaic_after	Mosaic name (not the series name) for the most recent source imagery upon which derivation is made. This is the unique identifier that can be used to source the mosaic from the Planet Mosaics WMTS service	global_monthly_2020_03_mosaic
source_mosaic_before	Mosaic name (not the series name) for the source imagery two time periods prior from the most recent mosaic upon which derivation is made. This is the unique identifier that can be used to source the mosaic from the Planet Mosaics WMTS service	global_monthly_2019_11_mosaic
source_quad_id	X-Y identifier of the image quad in the mosaic grid (More info on Page 16 of Planet Basemaps Product Specification). For Change Detection, it corresponds to the source_mosaic_after quad	"1848-793"

List Collections​

Example: List Collections​

Table 1: collections response​

Query Collection Results​

Example: Query results for a collection (For example, a subscription)​

Raster Results​

Table 2: raster-based results​

Vector Results​

Object detection on scenes​

Table 3: vector based model detections on scenes​

Change detection on mosaics​

Table 4: vector based model detections on mosaics​