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, source block (with 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 or the 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.
There are two types of source blocks for Imagery Subscriptions: catalog and analysis_ready_ps.
catalogsource reference our scene catalogs (e.g. PSScene, SkySatScene, SkySatCollect, TanagerScene, TanagerMethane) and the source block requiresitem_types&asset_typesto be specified. Thetime_range_typeparameter can optionally be provided to specify the date field in image metadata to utilize for matching images - eitherpublished(default; when the image was published to the catalog) oracquired(when the image was captured or collected).analysis_ready_pssource reference our Analysis-Ready PlanetScope product, and the blocks requireidto be specified.
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. RRules are not supported for Analysis-Ready PlanetScope at this time.
Example Analysis-Ready PlanetScope Subscription Request¶
This example creates a subscription that will deliver Analysis-Ready PlanetScope from imagery captured between October 2023 and January 2024. Please note that Analysis-Ready PlanetScope does not support any tools at this time.
POST https://api.planet.com/subscriptions/v1/
{
"name": "Example Analysis-Ready PlanetScope Subscription",
"source": {
"type": "analysis_ready_ps",
"parameters": {
"id": "PS_ARD_SR_DAILY",
"start_time": "2023-10-01T00:00:00Z",
"end_time": "2024-01-30T00:00:00Z",
"geometry": {
"coordinates": [
[
[
-122.39334886532757,
37.795085729711886
],
[
-122.4196319874137,
37.795085729711886
],
[
-122.4196319874137,
37.77362268558437
],
[
-122.39334886532757,
37.77362268558437
],
[
-122.39334886532757,
37.795085729711886
]
]
],
"type": "Polygon"
}
}
},
"delivery": {}
}
Example PSScene Subscription 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": {
"item_types": ["PSScene"],
"asset_types": ["ortho_analytic_4b"],
"start_time": "2021-03-01T00:00:00Z",
"end_time": "2023-11-01T00:00:00Z",
"time_range_type": "acquired",
"geometry": {
"coordinates": [[[139.5648193359375,35.42374884923695],
[140.1031494140625,35.42374884923695],
[140.1031494140625,35.77102915686019],
[139.5648193359375,35.77102915686019],
[139.5648193359375,35.42374884923695]]],
"type": "Polygon"
}
}
},
"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¶
Edit via PUT request¶
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 a pending or running state, it may be edited with certain constraints. The following source block edits are disallowed:
start_time: Cannot be edited if the start time is in the past.item_type: Cannot be modified.
All other source filter criteria may be edited, as long as subscription does not surpass the limit on expected items delivered daily. These include:
start_time: May be modified if the start time is in the future.end_time: May be modified if the subscription has not expired.geometry: May be modified only for thecatalogsource type.rrule: May be modified. Not supported for Analysis-Ready PlanetScope.
Additionally, outside of the source block, the following elements may also be edited:
name: May be modified.delivery: May be modified.
The following elements may not be modified:
notifications: Cannot be modified.
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.
Edit via PATCH request¶
You can edit certain subscription attributes by submitting a PATCH request:
PATCH https://api.planet.com/subscriptions/v1/<subscription_id>
Not all attributes can be edited this way, but they are subject to fewer restrictions than PUT requests. Importantly, the full subscription request body is not required and such requests are accepted regardless subscription state.
See the API reference for the full list of supported attributes.
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 a Subscription¶
You can get details on a specific subscription with the following request:
GET https://api.planet.com/subscriptions/v1/<subscription_id>
The response will include the original request, status, created timestamp, updated timestamp, and a link to the subscription results page.
List Subscriptions¶
You list all subscriptions with the following request:
GET https://api.planet.com/subscriptions/v1
By status¶
You can filter by status with the status query parameter.
GET https://api.planet.com/subscriptions/v1?status=running&status=completed
By source_type¶
You can filter by source type with the source_type query parameter.
GET https://api.planet.com/subscriptions/v1/?source_type=catalog
By user_id¶
As an organization administrator, you can list subscriptions from any and all users in your organization with user_id.
GET https://api.planet.com/subscriptions/v1?user_id=all
GET https://api.planet.com/subscriptions/v1/<subscription_id>?user_id=all
To get subscriptions created by a specific user, replace 'all' with the user ID:
GET https://api.planet.com/subscriptions/v1/?user_id=<user-id>
List Subscription 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_idof the result.item_types: Theitem_typeof the result.
created: The time the result was generated. For acatalogsource 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 ofsuccessorfailed.errors: Information on result failure, including areasonand 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": {
"item_types": [
"PSScene"
],
"asset_types": [
"ortho_analytic_4b"
],
"start_time": "2022-01-01T00:00:00Z",
"end_time": "2025-11-01T00:00:00Z",
"time_range_type": "acquired",
"geometry": {
"coordinates": [
[
[
139.5648193359375,
35.42374884923695
],
[
140.1031494140625,
35.42374884923695
],
[
140.1031494140625,
35.77102915686019
],
[
139.5648193359375,
35.77102915686019
],
[
139.5648193359375,
35.42374884923695
]
]
],
"type": "Polygon"
}
}
},
"delivery": {
"type": "google_cloud_storage",
"parameters": {
"bucket": "[your-GCP-bucket-name]",
"credentials": "[base64-encoded-credentials]"
}
},
"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"
}
We are continually working to improve our technical documentation and support. Please help by sharing your experience with us.