The Subscriptions API provides continuous cloud delivery of imagery, metadata, and analysis.
To create an imagery subscription, you can specify filter criteria, raster processing tools, and a cloud delivery location. The API then automatically processes and delivers all items which meet your subscription criteria, as soon as they are published to the catalog.
The Subscriptions API is Planet's recommended data delivery API for customers in need of daily imagery over stable areas of interest.
Create an Imagery Subscription¶
A basic subscription must include a name
, catalog
source
block (with item_types
, asset_types
, geometry
, start_time
, end_time
), and a delivery
block with a specified cloud storage location. Subscriptions also support select tools
. A subscription request will be rejected if the geometry specified in the geometry
attribute and clip tool
exceeds 1,500 vertices.
A subscription processes and delivers items as soon as all item filter criteria are met, and all requested asset types have been published and are available for delivery.
Monitoring across seasons¶
The Subscriptions API can support seasonal monitoring by delivering archive imagery and future collections for specific months over the duration of a subscription.
To create a subscription that delivers imagery within specific time periods during a time of interest, utilize the rrule
attribute that leverages iCalendar recurrence rules. This can be used to create subscriptions that deliver items for recurring periods within the total coverage time. More details can be found in the Source RRule section.
Example Request¶
This example creates a subscription that will deliver imagery acquired between March 2021 and October 2023.
POST https://api.planet.com/subscriptions/v1/
{
"name": "Example Subscription",
"source": {
"type": "catalog",
"parameters": {
"geometry": {
"coordinates": [[[139.5648193359375,35.42374884923695],
[140.1031494140625,35.42374884923695],
[140.1031494140625,35.77102915686019],
[139.5648193359375,35.77102915686019],
[139.5648193359375,35.42374884923695]]],
"type": "Polygon"
},
"time_range_type": "acquired",
"start_time": "2021-03-01T00:00:00Z",
"end_time": "2023-11-01T00:00:00Z",
"item_types": ["PSScene"],
"asset_types": ["ortho_analytic_4b"]
}
},
"delivery": { ... }
}
Info
The requested image is not clipped to the specified geometry unless the clip tool is applied. For more information, see our Tools Documentation page.
Edit an Imagery Subscription¶
You can edit a subscription by submitting a full subscription request to the following endpoint:
PUT https://api.planet.com/subscriptions/v1/<subscription_id>
When a subscription is in pending
state, it may be edited in full. After the subscription transitions to running
, the following source
block edits will be disallowed:
- Changes to
item_types
- Changes to
start_time
values
All other source filter criteria may be edited, as long as subscription does not surpass the limit on expected items delivered daily.
Importantly, the edit will only apply to future item publications and deliveries. No items will be redelivered. If you need to reorder archive items based on an updated filter or tool specifications, you can search for and order archive items with the Data API and Orders API.
Backfill subscriptions cannot be edited.
Cancel a Subscription¶
You can cancel subscription, with the following request:
POST https://api.planet.com/subscriptions/v1/<subscription_id>/cancel
After a subscription is cancelled, no additional items will be delivered (except for any items in processing or delivery). A cancelled subscription cannot be transitioned to running
state. cancelled
subscriptions will continue to be returned in the GET
subscriptions response.
Get an Imagery Subscriptions¶
You can get a list of your subscriptions, with the following request:
GET https://api.planet.com/subscriptions/v1
The response will include a list of your subscriptions (including cancelled
subscriptions). Each listed subscription will include the original subscription request, subscription status
, created
timestamp, and updated
timestamp.
You can filter subscriptions by status with the status
query parameter. As an example, this API call would return all subscriptions in running
or completed
states:
GET https://api.planet.com/subscriptions/v1?status=running&status=completed
You can get details on a specific subscription with the following request:
GET https://api.planet.com/subscriptions/v1/<subscription_id>
You can get a list of all subscriptions of a specific source_type
. For example, the following call returns all of your imagery Subscriptions.
GET https://api.planet.com/subscriptions/v1/results?format=csv&source_type=catlog
If you are an organization administrator, you can get details for all subscriptions in an organization by including the user_id=all
query parameter (Note: the api_key
must be of a requestor that is an org admin):
GET https://api.planet.com/subscriptions/v1?user_id=all
or
GET https://api.planet.com/subscriptions/v1/<subscription_id>?user_id=all
Get Imagery Subscriptions Results¶
A result for the catalog
source
type subscription represents an attempt to process and deliver an item that matches your subscription criteria. You can get a paginated list of your subscription's results, with the following request:
GET https://api.planet.com/subscriptions/v1/<subscription_id>/results
The response will include a paginated list of all of the subscription's results which were created within the last 30 days. Results for at least the past 30 days of deliveries will be returned. The response schema will include:
id
: The unique id of the subscription result.status
: The status of delivery of the result's item. Result status can take one of the following values:created
: The result has been created in our system. For catalog source type subscriptions, this means an item has been published which matches your subscription.queued
: The result is in queue for processing.processing
: The result is in processing.success
: The result is completed and the outputs have been delivered.failed
: The result is completed; the outputs failed to be delivered.
properties
:item_id
: Theitem_id
of the result.item_types
: Theitem_type
of the result.
created
: The time the result was generated. For acatalog
source type subscription, this will be the time that the subscription acknowledges the newly published item.updated
: The time that the result was last updated.completed
: The time the result reached an end status ofsuccess
orfailed
.errors
: Information on result failure, including areason
and array ofdetails
.output
: The directories of the final output files.
You can filter subscriptions results by status
(i.e. ?status=processing
) and by created
, updated
, or completed
timestamps, using STAC API timestamp and interval conventions:
- A datetime: "2020-09-01T00:00:00Z"
- A closed interval: "2020-09-01T00:00:00Z/2020-09-30T23:59:59Z"
- Open intervals: "2020-09-01T00:00:00Z/.." or "../2020-09-01T00:00:00Z"
As an organization administrator, you also have the ability to get subscription results for any subscription created in your organization by including the user_id=all
query parameter.
As an example, this API call would return all of a subscription's success
results completed before September 30, 2020 (and created within the last 30 days).
GET https://api.planet.com/subscriptions/v1/b9ec5d6b-8753-440a-852c-528188f914d0/results?status=success&completed=../2020-09-30T00:00:00Z
Example Response¶
{
"name": "Example Subscription",
"source": {
"type": "catalog",
"parameters": {
"asset_types": [
"ortho_analytic_4b"
],
"end_time": "2025-11-01T00:00:00Z",
"geometry": {
"coordinates": [
[
[
139.5648193359375,
35.42374884923695
],
[
140.1031494140625,
35.42374884923695
],
[
140.1031494140625,
35.77102915686019
],
[
139.5648193359375,
35.77102915686019
],
[
139.5648193359375,
35.42374884923695
]
]
],
"type": "Polygon"
},
"item_types": [
"PSScene"
],
"start_time": "2022-01-01T00:00:00Z",
"time_range_type": "acquired"
}
},
"delivery": {
"type": "google_cloud_storage",
"parameters": {
"bucket": "[your-GCP-bucket-name]",
"credentials": "[base64-encoded-credentials-for-service-agent…]"
}
},
"created": "2022-11-21T21:46:18.392063Z",
"_links": {
"_self": "https://api.planet.com/subscriptions/v1/1ac43ca5-2ac5-48b0-a4b2-f72032cc3f03"
},
"status": "preparing",
"id": "1ac43ca5-2ac5-48b0-a4b2-f72032cc3f03",
"updated": "2022-11-21T21:46:18.392063Z"
}
Rate this guide: