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

 {"type": "Polygon",
        "coordinates": [
          [
               [
                 103.849296569824,
                 1.2513119542594
               ],
               [
                 103.880882263184,
                 1.2513119542594
               ],
               [
                 103.880882263184,
                 1.27293604010387
               ],
               [
                 103.849296569824,
                 1.27293604010387
               ],
               [
                 103.849296569824,
                 1.2513119542594
               ]
             ]
           ]
         }
 

             "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"
          }
         ],

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

 [
        {
          "href": "https://api.planet.com/analytics/feeds/f35f37ce-4ba9-4b0d-b7d7-b687834223c3", 
          "rel": "self"
        },
       {
          "href": "https://api.planet.com/analytics/feeds", 
          "rel": "feeds"
        }
      ]

{
        "config": {
          "bundle": "visual", 
          "query": {
            "filter": {
              "config": ["true"], 
              "field_name": "ground_control", 
              "type": "StringInFilter"
           }, 
            "item_types": ["PSScene3Band"]
          }
        }, 
        "type": "image"
      }

Vector output:
 {
     "type": "collection"
 }
 
Or for Raster output 
 
{
        "config": {
          "series_id": "431b62a0-eaf9-45e7-acf1-d58278176d52"
       },
        "type": "mosaic"
      }

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

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

 {
        "type": "Polygon",
        "coordinates": [
          [
            [
              103.849296569824,
              1.2513119542594
            ],
            [
              103.880882263184,
              1.2513119542594
            ],
            [
              103.880882263184,
              1.27293604010387
            ],
            [
              103.849296569824,
              1.27293604010387
            ],
            [
              103.849296569824,
              1.2513119542594
            ]
          ]
        ]
      }

 {
          "href": "https://api.planet.com/analytics/collections/2d28b64b-1561-4a6f-8294-1a85aac2e3f6/items/50e7d65b-9ec6-4ec1-8f46-c80bcbfffb2b",
          "rel": "self"
 }

          "rel": "source-quad"
 }

{
          "href": "https://api.planet.com/analytics/collections/2d28b64b-1561-4a6f-8294-1a85aac2e3f6/items/50e7d65b-9ec6-4ec1-8f46-c80bcbfffb2b/resources/target-quad",
          "rel": "target-quad"
 }

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 6: Vector based model detections on scenes

 {
        "type": "Polygon",
        "coordinates": [
          [
            [
              103.849296569824,
              1.2513119542594
            ],
            [
              103.880882263184,
              1.2513119542594
            ],
            [
              103.880882263184,
              1.27293604010387
            ],
            [
              103.849296569824,
              1.27293604010387
            ],
            [
              103.849296569824,
              1.2513119542594
            ]
          ]
        ]
      }

Collections for Vector-Based Results - Mosaic 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/a5dfe56d-879a-479d-8641-cae77c6ac574/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 6: Vector based model detections on mosaics

{
        "type": "Polygon",
        "coordinates": [
          [
            [
              103.849296569824,
              1.2513119542594
            ],
            [
              103.880882263184,
              1.2513119542594
            ],
            [
              103.880882263184,
              1.27293604010387
            ],
            [
              103.849296569824,
              1.27293604010387
            ],
            [
              103.849296569824,
              1.2513119542594
            ]
          ]
        ]
      }

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.

{
        "type": "Polygon",
        "coordinates": [
          [
            [
              103.849296569824,
              1.2513119542594
            ],
            [
              103.880882263184,
              1.2513119542594
            ],
            [
              103.880882263184,
              1.27293604010387
            ],
            [
              103.849296569824,
              1.27293604010387
            ],
            [
              103.849296569824,
              1.2513119542594
            ]
          ]
        ]
      }

 {
          "href": "https://api.planet.com/analytics/collections/acd47acd-1301-4baf-8315-5a745824ae09/items/acd47acd-1301-4baf-8315-5a745824ae09",
          "rel": "self"
 }

 {
          "href": "https://api.planet.com/analytics/collections/acd47acd-1301-4baf-8315-5a745824ae09/items/acd47acd-1301-4baf-8315-5a745824ae09/resources/source-quad",
          "rel": "source-quad"
 }

Summary Statistics Post Endpoint

The Summary Statistics endpoint is different from the others related to the Analytics API as it requires first a POST request to generate a report which you can then make a GET request for. We’ll go through the POST endpoint first along with the required and optional parameters you can submit, followed by how to query for a report’s status and how to get the report itself.

Post Endpoint:

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

Example:

 curl --request POST \
  --url https://api.planet.com/analytics/stats \
  --header 'Authorization: api-key ${PL_API_KEY}' \
  --header 'content-type: application/json' \
  --data '{
    "title": "Roads_in_Massachusetts",
    "subscriptionID": "a3239cf2-67d9-430f-a332-bf052b23e676",
    "interval": "month"
 }

This example will run a summary statistics report for the full area of interest captured in the Analytic Subscription. More often than not, users will wish to break up their AOI into smaller subAOIs that they can then compare with each other. For example, you could submit all of the counties of Texas so you could compare development county to county. Below is an example where we include subAOIs - note that each has a property "id" - make sure this is lower case. This will be returned in the report as a description of the subAOI.

Example:

 curl --request POST \
  --url https://api.planet.com/analytics/stats \
  --header 'Authorization: api-key ${PL_API_KEY}' \
  --header 'content-type: application/json' \
  --data '{
    "title": "Roads_in_Texas",
    "subscriptionID": "b3232cf2-67a9-430f-a332-bf052b23e676",
    "interval": "month"
    "collection": {
    "type": "FeatureCollection",
    "features": [
        {
        "type": "Feature",
        "properties": {
            "id": "AOI-1"
        },
        "geometry": {
            "type": "Polygon",
            "coordinates": [
            [
                [
                -99.15710449218749,
                29.377388403478992
                ],
                [
                -99.09393310546875,
                29.377388403478992
                ],
                [
                -99.09393310546875,
                29.47307903155816
                ],
                [
                -99.15710449218749,
                29.47307903155816
                ],
                [
                -99.15710449218749,
                29.377388403478992
                ]
            ]
            ]
        }
        },
        {
        "type": "Feature",
        "properties": {
            "id": "AOI-2"
        },
        "geometry": {
            "type": "Polygon",
            "coordinates": [
            [
                [
                -99.03076171875,
                29.408497744069077
                ],
                [
                -98.96484375,
                29.408497744069077
                ],
                [
                -98.96484375,
                29.46829664171322
                ],
                [
                -99.03076171875,
                29.46829664171322
                ],
                [
                -99.03076171875,
                29.408497744069077
                ]
            ]
            ]
        }
        },
        {
        "type": "Feature",
        "properties": {
            "id": "AOI-3"
        },
        "geometry": {
            "type": "Polygon",
            "coordinates": [
            [
                [
                -99.3438720703125,
                29.372601506681402
                ],
                [
                -99.1845703125,
                29.372601506681402
                ],
                [
                -99.1845703125,
                29.463514026304715
                ],
                [
                -99.3438720703125,
                29.463514026304715
                ],
                [
                -99.3438720703125,
                29.372601506681402
                ]
            ]
            ]
        }
        }
    ]
    }
 }

Table 7: Summary Statistics POST data

Table 8: Summary Statistics API POST Response

Summary Statistics Reports

Once a summary stats report has been generated, you can query to get the results formatted as a geojson, csv or json response using a “format” parameter. Depending on the source imagery (scenes vs. mosaics), different metadata fields will be provided.

Endpoint:

https://api.planet.com/analytics/stats/<jobID>/report

Example with JSON response (default):

curl --header "Authorization: api-key ${PL_API_KEY}" 
https://api.planet.com/analytics/stats/<jobID>/report

Example with CSV response:

curl --header "Authorization: api-key ${PL_API_KEY}"
https://api.planet.com/analytics/stats/<jobID>/report?format=csv

Example with GeoJSON response:

curl --header "Authorization: api-key ${PL_API_KEY}"  
https://api.planet.com/analytics/stats/<jobID>/report?format=geojson

Table 9: Summary Statistics Report data for Raster Results Derived from Mosaics

Reports based on Feeds generated from mosaic data resulting in raster data (e.g. building detection) show the total number of square meters classified as the particular feature (e.g. roads) as well as the total number of square meters processed. This gives additional context if comparing multiple areas of differing sizes.

Table 10: Summary Statistics Report Data for Vector Results Derived from Scenes

Reports based on Feeds generated from scenes provide the number of raw and deduplicated detections per day. The raw count of detections may be double counting some features in cases where multiple satellite passes were made within a short period of time (eg. minutes). The deduplicated count removes detections whose centroid is within 10 meters of another detection within a 20 minute window.

Also provided is the number of square meters within the area of interest that were captured or cloudy. This provides additional information needed to normalize the results and counteract issues caused by coverage or clouds.

Table 11: Summary Statistics Report Data for Vector Results Derived from Mosaics

Reports based on Feeds generated from mosaic data resulting in vector data (e.g. well pad detection) show the total number of detections within the given time period.