API Responses

last updated: March 23, 2023

Subscriptions

Endpoint:

api.planet.com/analytics/subscriptions/

Example:

curl --header "Authorization: api-key ${PL_API_KEY}" https://api.planet.com/analytics/subscriptions/

The Subscriptions endpoint returns all of the Subscriptions that are enabled for a particular api_key. Each item within this response describes a specific Subscription including its spatial area of interest as well as its temporal start-time and end-time. The Subscription dictates over what time period and area a particular computer vision operation will be performed.

Table 1: Subscriptions endpoint
Metadata Field Description Sample
created Timestamp when the subscription was created (in UTC) 2019-03-08T18:11:57.488Z
description Description of the Subscription as entered by the Planet Analytics Admin Building Detection in New Cairo
id UUID for the subscription f301b8c9-04e1-49f6-ab31-24a8c25edbd5
feedID UUID for the Feed 1ce86055-cad0-4960-bdf3-32763c17f19b
startTime Starting time of the time window for the subscription 2019-01-01T00:00:00.000Z
endTime End time of the time window for the subscription. If the subscription does not have an end time, this field will not be surfaced. 2019-01-31T00:00:00.000Z
geometry Polygon coordinates to the spatial extent of the subscription 
 {"type": "Polygon",
        "coordinates": [
          [
               [
                 103.849296569824,
                 1.2513119542594
               ],
               [
                 103.880882263184,
                 1.2513119542594
               ],
               [
                 103.880882263184,
                 1.27293604010387
               ],
               [
                 103.849296569824,
                 1.27293604010387
               ],
               [
                 103.849296569824,
                 1.2513119542594
               ]
             ]
           ]
         }
links Links to the individual subscription that the item refers to, the resulting collection of analytic results from the subscription, the feed operation that is associated with the subscription and to the subscriptions endpoint 
             "rel": "self"
           },
          {
             "href": "https://api.planet.com/analytics/collections/f301b8c9-04e1-49f6-ab31-24a8c25edbd5/items",
             "rel": "results"
           },
          {
             "href": "https://api.planet.com/analytics/feeds/e2ee4fca-e998-46fc-abe4-2ccaa7b7d285",
             "rel": "feed"
           },
          {
             "href": "https://api.planet.com/analytics/subscriptions",
             "rel": "subscriptions"
          }
         ],
title Title of the subscription as entered by the Planet Analytics Admin Demo_Subscription_Singapore
updated Last update time to the results associated with a subscription 2019-04-10T04:40:20.261Z

Feeds

Endpoint:

api.planet.com/analytics/feeds/

Example:

curl --header "Authorization: api-key ${PL_API_KEY}" https://api.planet.com/analytics/feeds/

The Feeds endpoint returns all of the Feeds that are enabled for a particular api_key. Each item within this response describes a specific feed including the source of imagery on which the feed operates. The Feeds describe the particular computer vision operation that will be performed when applied to the source imagery.
The table below contains descriptions of the properties of each collection of responses returned by the feeds endpoint.

Table 2: Feeds endpoint
Metadata Field Description Sample
created Timestamp when the feed was created (in UTC) 2019-03-08T18:11:57.488Z
description Description of the feed as entered by the Planet Analytics Admin Ship detections from rectified PlanetScope imagery
id UUID for the feed f35f37ce-4ba9-4b0d-b7d7-b687834223c3
links Links to the individual feed and to the collection of feeds 
 [
        {
          "href": "https://api.planet.com/analytics/feeds/f35f37ce-4ba9-4b0d-b7d7-b687834223c3", 
          "rel": "self"
        },
       {
          "href": "https://api.planet.com/analytics/feeds", 
          "rel": "feeds"
        }
      ]
source Description of the source on which the respective feed operates. Includes source bundle, item type and query filter parameters 
{
        "config": {
          "bundle": "visual", 
          "query": {
            "filter": {
              "config": ["true"], 
              "field_name": "ground_control", 
              "type": "StringInFilter"
           }, 
            "item_types": ["PSScene3Band"]
          }
        }, 
        "type": "image"
      }
target Defines the type of output for the feed. For an object detection based feed, this would be a collection. For a segmentation based feed, this would be a mosaic with an associated series_id indicating the UUID of the resulting Planet mosaic 
Vector output:
 {
     "type": "collection"
 }
 
Or for Raster output 
 
{
        "config": {
          "series_id": "431b62a0-eaf9-45e7-acf1-d58278176d52"
       },
        "type": "mosaic"
      }
title Title of the feed as entered by the Planet Analytics Admin Ship Detections
updated Timestamp of the last update from the feed (in UTC) 2019-04-11T17:51:39.771Z

Collections

Endpoint:

api.planet.com/analytics/collections/

Example:

curl --header "Authorization: api-key ${PL_API_KEY}" 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 as well as its temporal start-time and end-time defined in the Subscription. Below is a description of the properties of each collection of results returned by the collections endpoint.

Table 3: Collections endpoint
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"
        }
      ]

Collections for Raster Results

Endpoint:

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

Example:

curl --header "Authorization: api-key ${PL_API_KEY}" https://api.planet.com/analytics/collections/27c0df67-572d-4036-95d6-489decf36aa9/items

Each result in a raster-based feature collection references a quad from the analytic feed over which an operation has been executed. The result references the target quad through the [links][target-quad] property. This link allows the user 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 4: 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 
          "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

Collections for Vector-Based Results - Scene Imagery - Object Detection

Endpoint:

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

Example:

curl --header "Authorization: api-key ${PL_API_KEY}" https://api.planet.com/analytics/collections/886b4dbb-b878-4f6b-b000-0d96cbf71d4d/items

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 5: 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 to 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 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

Collections for Vector-Based Results - Mosaic Imagery - Change Detection

Endpoint:

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

Example:

curl --header "Authorization: api-key ${PL_API_KEY}" https://api.planet.com/analytics/collections/acd47acd-1301-4baf-8315-5a745824ae09/items

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", along with metadata associated with it. Each result references a quad from the analytic 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 6: 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"
Rate this guide: