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", |
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" |
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 | [ |
source | Description of the source on which the respective feed operates. Includes source bundle, item type and query filter parameters | { |
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: |
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 | [ |
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. | { |
id | Result identifier | 50e7d65b-9ec6-4ec1-8f46-c80bcbfffb2b |
links: self | Link for the result (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 | { |
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 6: 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. | { |
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 - 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
Metadata Field | Description | Sample |
---|---|---|
created | Time stamp when the item was created in UTC (check) | 2020-03-30T18:36:00.103Z |
geometry | The bounding box coordinates of the detection / result. | { |
id | Item identifier | 6636342e-a13b-41fc-a88b-b73653f08f59 |
link: Self | Link to the item in the feature collection | https://api.planet.com/analytics/collections/a5dfe56d-879a-479d-8641-cae77c6ac574/items/6636342e-a13b-41fc-a88b-b73653f08f59 |
link: source-quad | Link to the source quad which is the imagery used to generate the detection output | https://api.planet.com/analytics/collections/a5dfe56d-879a-479d-8641-cae77c6ac574/items/6636342e-a13b-41fc-a88b-b73653f08f59/resources/source-quad |
model_id | Unique identifier of the computer vision model used to create this item | 01DZSXQF289NN642QCM5EW5QSV |
model_version | Time stamp indicating the version of to the computer vision model used to create this item | 2020-01-30T02:11:49Z |
object_area_m2 | The area of item’s physical footprint, described in square meters. | 27886.310865727868 |
object_diagonal_m | Diagonal length of the item’s physical footprint, described in meters | 267.0932163139776 |
object_length | Length of item’s physical footprint, described in meters | 240.64565218705684 |
object_width | Width of the item’s physical footprint, described in meters | 115.88121627084911 |
source_first_acquired | The timestamp of the earliest imagery captured in producing the source imagery basemap quad (inclusive) | 2019-06-01T00:00:00Z |
source_last_acquired | The timestamp of the latest imagery captured in producing the source imagery basemap quad (exclusive) | 2019-07-01T00:00:00Z |
source_mosaic | The source mosaic upon which the derived analytic output was generated. | global_monthly_2019_06_mosaic |
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_2019_06_mosaic |
observed | Date-time at which the source imagery was captured. | 020-04-13T16:30:36.111473Z |
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.9756358861923218 |
source_cloud_cover | Average percentage of cloud cover in the source asset from which the object was detected | 100 |
xmax_px | location of the detection along the horizontal axes in pixel coordinates | 3973 |
xmin_px | location of the detection along the horizontal axes in pixel coordinates | 3949 |
ymax_px | location of the detection along the vertical axes in pixel coordinates | 2774 |
ymin_px | location of the detection along the vertical axes in pixel coordinates | 2724 |
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.
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 | { |
id | Result identifier | acd47acd-1301-4baf-8315-5a745824ae09 |
links: self | Link for the result (self) | { |
links: source-quad | Link to the source quad which is the imagery used to generate the detection output | { |
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" |
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
Metadata Field | Description | Sample |
---|---|---|
collection (optional) | Geojson feature collection specifying what areas of interest should be processed. Can contain multiple features. | ~/files/stats_feature_colleciton.geojson |
clipToSubscription (optional) | Optional flag to clip each input feature to the subscription AOI. If a feature does not intersect the subscription AOI then it will be removed. At least one feature is required to intersect the subscription AOI. | false |
endTime (optional) | End time of the time window for the stats report. Will take the end time of the Analytic Subscription submitted if not provided | 2019-03-01T00:00:00.000Z |
Interval (required) | Specifies the interval that the report will be aggregated upon | “day”, “week” or “month” |
startTime (optional) | Start time of the time window for the stats report. Will take the start time of the Analytic Subscription submitted if not provided | 2019-01-01T00:00:00.000Z |
subscriptionID (required) | The Analytic Subscription from which the stats report will be generated | a3239cf2-67d9-430f-a332-bf052b23e676 |
title (required) | A title for the stats report to be generated. | “Roads_in_Massachusetts” |
Table 8: Summary Statistics API POST Response
Metadata Field | Description | Sample |
---|---|---|
collection | The (optionally) submitted Geojson feature collection specifying what areas of interest should be processed. Can contain multiple features. If no Geojson feature collection was submitted, this will default to the area of interest defined in the subscription | 2020-05-18T18:40:03.022Z |
created | Timestamp of the POST request | 2020-05-18T18:40:03.022Z |
endtime | The (optionally) submitted timestamp signifying the last time period that should be aggregated against. If not submitted, this will default to the endtime defined in the subscription | 2020-12-01T00:00:00.000Z |
id | UUID for the stats report | 5763da60-d167-482d-a9f2-9c83009e3d63 |
interval | The submitted interval | “day” or “week” or “month” |
links: self | Links for the POST response (itself) | https://api.planet.com/analytics/stats/5763da60-d167-488d-a9f2-9c83019e3d63 |
links: subscription | Links for the associated analytic subscription | https://api.planet.com/analytics/subscriptions/a3239cf2-67d9-430f-a332-bf052b23e676 |
status | Status of the stats report being generated | “Started” or “pending” or “complete" |
subscriptionID | The Analytic Subscription from which the stats report will be generated | a3239cf2-67d9-430f-a332-bf052b23e676 |
title | The title for the stats report to be generated. | “Roads_in_Massachusetts” |
updated | Timestamp of the when the report was updated | 2020-05-18T18:40:03.022Z |
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.
Metadata Field | Description | Sample |
---|---|---|
Feature ID | Unique ID for submitted features (if no features were submitted, this will reflect the subscription name of the analytic subscription used) | New Mexico (subscription_d99ff2j8-5e7d-4ddc-9993-e32bbc4aa434) |
Start Time | Start time of the time period reported | 2019-01-01T00:00:00Z |
End Time | End time of the time period reported | 2019-02-01T00:00:00Z |
Feature Area - Sq meters | Number of square meters classified as the feature (e.g. roads) | 12515 |
Total Area - Sq meters | Total number of square meters for the area of interest | 23523 |
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.
Metadata Field | Description | Sample |
---|---|---|
Feature ID | Unique ID for submitted features (if no features were submitted, this will reflect the subscription name of the analytic subscription used) | Port of Oakland (subscription_d99ff9f8-5d7d-4ddc-9993-e32bbc4aa434) |
Start Time | Start time of the time period reported | 2019-01-01T00:00:00Z |
End Time | End time of the time period reported | 2019-01-02T00:00:00Z |
Total Object Count | Number of detections | 22 |
Unique Object Count | Number of unique detections. This removes any detections whose centroid is within 10 meters of another detection within a 20 minute window | 20 |
Submitted Area | Area in square meters of the submitted polygon (defaults to subscription geometry if none are submitted) | 45193025 |
Total Area (udm) | Based on Planet’s UDM asset, the number of square meters captured within that time period | 21521612 |
Clear Area (udm_band_1) | Based on Planet’s UDM asset, the total number of cloud-free square meters captured | 136236 |
Total Area (udm2) | Based on Planet’s UDM asset, the number of square meters captured within that time period | 21521615 |
Clear Area (udm2_band_1) | Based on Planet’s UDM2 asset, the total number of cloud-free square meters captured | 346343 |
Snow Area (udm2_band_2) | Based on Planet’s UDM2 asset, number of snowy square meters captured | 125126 |
Shadow Area (udm2_band_3) | Based on Planet’s UDM2 asset, number of shadow square meters captured | 125165 |
Light Haze Area (udm2_band_4) | Based on Planet’s UDM2 asset, number of lightly hazy square meters captured | 12512 |
Heavy Haze Area (udm2_band_5) | Based on Planet’s UDM2 asset, number of heavily hazy square meters captured | 12556 |
Cloud Area (udm2_band_6) | Based on Planet’s UDM2 asset, number of cloudy square meters captured | 236262 |
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.
Metadata Field | Description | Sample |
---|---|---|
Feature ID | Unique ID for submitted features (if no features were submitted, this will reflect the subscription name of the analytic subscription used) | New Mexico (subscription_d99ff2j8-5e7d-4ddc-9993-e32bbc4aa434) |
Start Time | Start time of the time period reported | 2019-01-01T00:00:00Z |
End Time | End time of the time period reported | 2019-02-01T00:00:00Z |
Total Object Count | Raw count of detections | 220 |
Unique Object Count | Number of unique detections. This removes any detections whose centroid is within 10 meters of another detection within a 20 minute window | 215 |
Rate this guide: