The Subscriptions API is Planet's next-gen data delivery API. With a single API call, this "order a search" capability allows you to subscribe to continuous cloud delivery of imagery and metadata collections which meet your item filter criteria.
To create a subscription, you can specify imagery filter criteria, raster processing tools (including clip), and a cloud delivery location. The API will then automatically process and deliver 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.
Subscriptions Schema
A subscription request has three main blocks.
source: Describes the data products and criteria used to define what the subscription delivers. Currently, thecatalogsource type is supported. It takesitem_types,asset_types, and afilter, and closely mirrors a Data API/quick-searchrequest.tools: Describes raster tools which may be applied to a susbcription. Currently, onlyclipis be supported.delivery: Describes the Google Cloud Storage, Amazon S3, and Microsoft Azure cloud delivery options for the items returned by the subscription.
More details on source, tools, and delivery block parameters are available in left-hand navigation pages, or jump straight to a Create Subscription Example Request below.
Subscription Status
Status Descriptions
preparing: The subscription was successfully submitted and is being set up.pending: The subscription's source start time (publishedDateRangeFiltergtorgtevalue) has not yet passed. Delivery has not yet started.running: The subscription’s source start time has passed and it is actively monitoring new catalog publish events and processing output. Delivery may be in progress.completed: The subscription’s source end time (publishedDateRangeFilterltorltevalue) has passed and all items are delivered. Delivery has stopped.suspended: The subscription has a policy or quota conflict. Delivery has stopped.cancelled: The subscription was cancelled by a user. Delivery has stopped.failed: There was an issue with the subscription.
Forwardfill and Backfill Subscriptions
The Subscriptions API currently support delivery of future imagery collections. This means, the start time (published DateRangeFilter gt or gte UTC value) of a subscription must be in the future (after the time of subscription creation) and only future imagery collections will be delivered.
We are calling a subscription of this nature a "forwardfill" subscription.
Early next year, we plan to offer archive imagery, or "backfill" support in the Subscriptions API. This will allow customers to order historical imagery. The start date of the subscription may be in the past (before the time of subscription creation) and customers will be able to order archive imagery only, or both archive and future collections, if the subscription end date (published DateRangeFilter lt or lte UTC value) is in the future.
Customers interested in archive imagery may continue to order archive imagery via the Orders API.
Subscriptions API Limits
Subscriptions API use will be limited to a maximum count of forwardfill subscriptions (ex. published lt/lte value has not passed) and a maximum total count of expected items delivered daily across all forwardfill subscriptions.
- Max Forwardfill Subscriptions: Maximum number of subscriptions with an active time of interest (ex.
publishedlt/lte value has not passed). A new forwardfill subscription may not be created if an organization has already maxed out its number of forwardfill subscriptions. - Total Expected Forwardfill Items Delivered Daily: Total number of expected items matched and delivered daily across all forwardfill subscriptions. A new forwardfill subscription cannot be created if its expected number of items delivered daily puts the organization over its total cap.
- To estimate the expected number of items a forwardfill subscription will deliver daily, the Subscriptions API uses Data API's Search Stats endpoint and averages daily items matched over the last 7 days. These numbers are then totaled across all forwardfill subscriptions.
- Note: Validation on "expected items delivered daily" is done upfont, at subscription creation. The Subscriptions API will not artificially limit item delivery if a subscription happens to match more items than expected on a given day.
By default, customers will be subject to the following limits: Max Forwardfill Subscriptions: 1,000 Total Expected Forwardfill Items Delivered Daily: 1,000
Please reach out to your Account Manager, or submit a request, if you need these limits to be increased.
Create a Subscription
A basic subscription must include a name, catalog source block (with item_types, asset_types, a top-level AndFilter, a GeometryFilter, and a published DateRangeFilter gt or gte UTC value in the future), 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 GeometryFilter and clip tool exceeds 500 vertices.
A subscription will process and deliver items as soon as all item filter criteria are met and all requested asset types have been published and are available for delivery.
Example Request
POST https://api.planet.com/subscriptions/v1/
{
"name": "basic_subscription",
"source": {
"type": "catalog",
"parameters": {
"item_types": [
"PSScene4Band"
],
"asset_types": [
"analytic_sr",
"analytic_xml",
"udm2"
],
"filter": {
"type": "AndFilter",
"config": [
{
"type": "DateRangeFilter",
"field_name": "published",
"config": {
"gt":"2020-07-31T00:00:00Z",
"lte":"2020-08-31T00:00:00Z"
}
},
{
"type": "GeometryFilter",
"field_name": "geometry",
"config": {
"type": "Polygon",
"coordinates": [
[
[
-122.3984670639038,
37.75459945618027
],
[
-122.39546298980713,
37.75459945618027
],
[
-122.39546298980713,
37.75768707689704
],
[
-122.3984670639038,
37.75768707689704
],
[
-122.3984670639038,
37.75459945618027
]
]
]
}
},
{
"type": "RangeFilter",
"field_name": "visible_percent",
"config": {
"gte": 90
}
}
]
}
}
},
"tools": [
{
"type": "clip",
"parameters": {
"aoi": {
"type": "Polygon",
"coordinates": [
[
[
-122.3984670639038,
37.75459945618027
],
[
-122.39546298980713,
37.75459945618027
],
[
-122.39546298980713,
37.75768707689704
],
[
-122.3984670639038,
37.75768707689704
],
[
-122.3984670639038,
37.75459945618027
]
]
]
}
}
}
],
"delivery": {
"type": "google_cloud_storage",
"parameters": {
"bucket": "<my-bucket>",
"credentials": "<my-credentials>"
}
}
}
Edit a 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
publishedDateRangeFiltergtandgtevalues
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 publishes and deliveries. No items will be redelivered. If you need to reorder archive items based on updated filter or tool specifications, you can search for and order archive items with the Data API and Orders API.
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 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>
Get 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 more than 30 days old will not 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: The item_id of the result.item_types: The item_type of 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 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
{
"_links": {
"_self": "http://api.planet.com/subscriptions/v1/b9ec5d6b-8753-440a-852c-528188f914d0/results",
"next": "http://api.planet.com/subscriptions/v1/b9ec5d6b-8753-440a-852c-528188f914d0/results?page_marker=2020-09-16T23%3A32%3A37.501441Z"
},
"results": [
{
"id": "fa48f60d-160a-4714-a1f1-268e2fc96a58",
"status": "success",
"properties": {
"item_id": "20200729_143245_ssc8d3_0001",
"item_types": [
"PSScene4Band"
]
},
"created": "2020-09-16T23:32:54.42402Z",
"updated": "2020-09-16T23:32:56.536936Z",
"completed": "2020-09-16T23:32:56.536936Z",
"errors": null,
"outputs": [
"b9ec5d6b-8753-440a-852c-528188f914d0/20200729_053412_88_105e/20200729_053412_88_105e_metadata.json",
"b9ec5d6b-8753-440a-852c-528188f914d0/20200729_053412_88_105e/20200729_053412_88_105e_3B_AnalyticMS.tif"
]
}
]
}