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, thecatalog
source type is supported. It takesitem_types
,asset_types
, and afilter
, and closely mirrors a Data API/quick-search
request.tools
: Describes raster tools which may be applied to a susbcription. Currently, onlyclip
is 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 (published
DateRangeFilter
gt
orgte
value) 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 (published
DateRangeFilter
lt
orlte
value) 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.
published
lt/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 support@planet.com, 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 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
published
DateRangeFilter
gt
andgte
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 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 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 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"
]
}
]
}