Querying Results

List Collections

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

Returns all result collections from your active subscriptions. Each collection contains the output from running an analytic feed over a subscription's defined area and time period.

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()

Response Properties

Each collection includes the following properties:

Field	Description	Example
`created`	UTC timestamp when the collection was created	`2019-03-08T18:11:57.488Z`
`description`	Human-readable description of the collection	`Building Detection in New Cairo`
`id`	UUID for the collection	`1ce86055-cad0-4960-bdf3-32763c17f19b`
`title`	Human-readable title of the collection	`New Cairo Buildings`
`links`	HATEOAS links to the collection, its items, and collections endpoint	See example below

Links Example

[
  {
    "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

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()

Response structure depends on the analytic feed type. Each feed returns specific metadata fields as described below.

Vessel Detection

Returns GeoJSON features representing individual detected vessels with bounding box coordinates and vessel-specific metadata.

Key Fields

Field	Description	Example
`geometry`	GeoJSON polygon defining the vessel's bounding box	`{"type": "Polygon", "coordinates": [...]}`
`id`	Unique identifier (UUID)	`17f21835-93c4-4664-b2ef-c2f57f5809a5`
`angle`	Mathematical angle of the vessel bounding box (0-180°)	`106.7`
`area_m2`	Area of the bounding box in square meters	`2543.2`
`bunkered`	Whether vessel is engaged in ship-to-ship transfer (Enhanced Vessel Detection only)	`false`
`heading`	Estimated heading direction (0-360°)	`162`
`length_m`	Estimated vessel length in meters	`113.79`
`width_m`	Estimated vessel width in meters	`22.35`
`object_class_label`	Vessel classification (Enhanced Vessel Detection only)	`"tanker"`
`score`	Detection confidence (0-1, higher = greater certainty)	`0.943`
`source_item_id`	Source imagery item ID	`"20251016_072148_62_2507"`
`observed`	UTC timestamp when vessel was observed	`"2025-10-16T07:21:48.627212Z"`

See the full Vessel Detection metadata reference for all available fields.

Aircraft Detection

Returns GeoJSON features representing individual detected aircraft with bounding box coordinates and aircraft-specific metadata.

Key Fields

Field	Description	Example
`geometry`	GeoJSON polygon defining the aircraft's bounding box	`{"type": "Polygon", "coordinates": [...]}`
`id`	Unique identifier (UUID)	`17f21835-93c4-4664-b2ef-c2f57f5809a5`
`bbox_area_m2`	Area of the bounding box in square meters	`1292.76`
`bbox_diagonal_m`	Diagonal length of the bounding box in meters	`51.09`
`bbox_length_m`	Estimated aircraft length in meters	`38.55`
`bbox_width_m`	Estimated aircraft width in meters	`33.53`
`score`	Detection confidence (0-1, higher = greater certainty)	`0.805`
`source_item_id`	Source imagery item ID	`"20260209_080938_54_24fd"`
`observed`	UTC timestamp when aircraft was observed	`"2026-02-09T08:09:38.541005Z"`

See the full Aircraft Detection metadata reference for all available fields.

Building Detection (Raster)

Returns raster GeoTIFF outputs for mosaic quads where building detection was performed. Results reference both source and target quads.

Key Fields

Field	Description	Example
`geometry`	GeoJSON polygon defining the quad's spatial extent	`{"type": "Polygon", "coordinates": [...]}`
`id`	Result identifier (UUID)	`50e7d65b-9ec6-4ec1-8f46-c80bcbfffb2b`
`links.target-quad`	Download link for the detection GeoTIFF	Link to two-band raster
`links.source-quad`	Download link for the source imagery quad	Link to source GeoTIFF
`observed`	UTC timestamp when source imagery was captured	`2019-03-20T07:57:18.186039Z`
`source_mosaic_name`	Source mosaic identifier for WMTS queries	`global_monthly_2018_07_mosaic`
`source_quad_id`	X-Y tile identifier of the source quad	`434-1216`
`target_mosaic_name`	Result mosaic identifier (format: `sif-{feed_id}-{date}`)	`sif-b8ee0ab1-4500-485d-80b1-a24d92ee4cd5-2018-07-01`

GeoTIFF Structure:

Band 1 (Detection mask): Binary mask where 0 = no building detected, 255 = building detected
Band 2 (Alpha channel): Validity mask where 255 = valid pixel, 0 = invalid pixel

Road Detection (Raster)

Returns raster GeoTIFF outputs for mosaic quads where road detection was performed. Results reference both source and target quads.

Key Fields

Field	Description	Example
`geometry`	GeoJSON polygon defining the quad's spatial extent	`{"type": "Polygon", "coordinates": [...]}`
`id`	Result identifier (UUID)	`50e7d65b-9ec6-4ec1-8f46-c80bcbfffb2b`
`links.target-quad`	Download link for the detection GeoTIFF	Link to two-band raster
`links.source-quad`	Download link for the source imagery quad	Link to source GeoTIFF
`observed`	UTC timestamp when source imagery was captured	`2019-03-20T07:57:18.186039Z`
`source_mosaic_name`	Source mosaic identifier for WMTS queries	`global_monthly_2018_07_mosaic`
`source_quad_id`	X-Y tile identifier of the source quad	`434-1216`
`target_mosaic_name`	Result mosaic identifier (format: `sif-{feed_id}-{date}`)	`sif-b8ee0ab1-4500-485d-80b1-a24d92ee4cd5-2018-07-01`

GeoTIFF Structure:

Band 1 (Detection mask): Binary mask where 0 = no road detected, 255 = road detected
Band 2 (Alpha channel): Validity mask where 255 = valid pixel, 0 = invalid pixel

Building Change Detection (Vector)

Returns GeoJSON features representing newly constructed buildings detected through temporal analysis. Each feature contains an aggregation of 8x8 pixel grid cells ("change cells") where building development was detected.

Key Fields

Field	Description	Example
`geometry`	GeoJSON polygon of the change cell area	`{"type": "Polygon", "coordinates": [...]}`
`id`	Unique identifier (UUID)	`17f21835-93c4-4664-b2ef-c2f57f5809a5`
`class_label`	Classification label	`"building"`
`change_direction`	Direction of change	`"positive"`
`date`	End date when change was detected	`"2026-02-02T00:00:00Z"`
`observed`	Start date of observation period	`"2026-01-26T00:00:00Z"`
`object_area_m2`	Area of detected change in square meters	`461.04`
`score`	Detection confidence (0.5-1.0, higher = greater certainty)	`0.594`
`source_mosaic_name`	Source mosaic used for detection	`rnb_weekly_v2_2026_01_26_2026_02_02`
`source_quad_id`	X-Y identifier of the source quad	`1140-1295`
`visual_mosaic_name`	Visual mosaic for imagery display	`ps_weekly_visual_subscription_...`

See the full Road & Building Change Detection metadata reference for all available fields.

Road Change Detection (Vector)

Returns GeoJSON features representing newly constructed roads detected through temporal analysis. Each feature contains an aggregation of 8x8 pixel grid cells ("change cells") where road development was detected.

Key Fields

Field	Description	Example
`geometry`	GeoJSON polygon of the change cell area	`{"type": "Polygon", "coordinates": [...]}`
`id`	Unique identifier (UUID)	`17f21835-93c4-4664-b2ef-c2f57f5809a5`
`class_label`	Classification label	`"road"`
`change_direction`	Direction of change	`"positive"`
`date`	End date when change was detected	`"2026-02-02T00:00:00Z"`
`observed`	Start date of observation period	`"2026-01-26T00:00:00Z"`
`object_area_m2`	Area of detected change in square meters	`461.04`
`score`	Detection confidence (0.5-1.0, higher = greater certainty)	`0.594`
`source_mosaic_name`	Source mosaic used for detection	`rnb_weekly_v2_2026_01_26_2026_02_02`
`source_quad_id`	X-Y identifier of the source quad	`1140-1295`
`visual_mosaic_name`	Visual mosaic for imagery display	`ps_weekly_visual_subscription_...`

See the full Road & Building Change Detection metadata reference for all available fields.

List Collections​

Example: List Collections​

Response Properties​

Links Example​

Query Collection Results​

Example​

Vessel Detection​

Key Fields​

Aircraft Detection​

Key Fields​

Building Detection (Raster)​

Key Fields​

Road Detection (Raster)​

Key Fields​

Building Change Detection (Vector)​

Key Fields​

Road Change Detection (Vector)​

Key Fields​

List Collections

Example: List Collections

Response Properties

Links Example

Query Collection Results

Example

Vessel Detection

Key Fields

Aircraft Detection

Key Fields

Building Detection (Raster)

Key Fields

Road Detection (Raster)

Key Fields

Building Change Detection (Vector)

Key Fields

Road Change Detection (Vector)

Key Fields