The Subscriptions API provides continuous cloud delivery of imagery, Planetary Variables, metadata, and analysis. The Subscriptions API is Planet’s recommended data delivery API for customers in need of daily imagery and Planetary Variables over stable areas of interest.
To create a subscription, you can specify the filter, applicable tools, and a cloud delivery location. The API automatically processes and delivers all items which meet your subscription criteria, as soon as they are published to the catalog.
Subscribing to imagery and Planetary Variables with Planet’s Subscriptions APIs¶
With Planet’s Subscriptions APIs, you can subscribe to imagery and Planetary Variables. There are two source types: Imagery, where you can activate, customize, and deliver PlanetScope, SkySat, and archival imagery, and Planetary Variables, allowing you to create, monitor, and access these through the Subscriptions API. Here we cover the subscription schema, subscription status, forwardfill and backfill subscriptions, API limits, and rate limiting. Details on parameters for the subscription block provide information relating to Source, Tools, Delivery, and Notifications.
- API mechanics: If you're new to Subscription APIs, review the mechanics of finding your API key, making sure your area of interest in within your area of access, making RestFUL calls, delivering results, and paginating through the results in the API Mechanics section.
- Information on this page: Below you can find details on the subscriptions schema, subscription status, forwardfill and backfill subscriptions, subscriptions api limits, and rate limiting.
- Details on block parameters: Get more detail on Source, Tools, Delivery, and Notifications.
- Details specific to the source types: Get specific information on the following source types:
| Imagery | Planetary Variables |
|---|---|
| Activate, customize, and deliver PlanetScope, SkySat, and archival imagery | Create, monitor, and access Planetary Variables through the Subscriptions API |
Subscriptions schema¶
A subscription request has four main blocks.
source: Describes the data products and criteria used to define what the subscription delivers.- For imagery, the
catalogsource type is supported. It takesitem_types,asset_types,geometry,start_time, and afilter, and closely mirrors a Data API/quick-searchrequest. - For Planetary Variables, the source type is based on the product offering:
biomass_proxy,land_surface_temperature,soil_water_content,vegetation_optical_depth.
- For imagery, the
tools: Describes raster tools which may be applied to an imagery subscription. For Planetary Variables, all rasters are clipped to the subscription’s AOI, and no additional tools are supported.delivery: Describes the Google Cloud Storage, Amazon S3, and Microsoft Azure cloud delivery options for the items returned by the subscription.notifications: Describes the notifications which can be delivered for a subscription.
Subscription status¶
Status descriptions¶
preparing: The subscription was successfully submitted and is being set up.pending: The subscription’s source start time (start_timevalue) has not yet passed. Delivery has not yet started.running: The subscription’s source start time has passed and it is actively monitoring for new data and delivering it. Delivery may be in progress.completed: The subscription’s source end time (end_timevalue) is at least 7 days into the past and all items have been delivered. Items may be delivered within a 60-day grace period after the subscription was marked as completed. After the grace period, delivery stops indefinitely.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 supports delivery of both archive imagery and future imagery collections.
- Forwardfill subscriptions are subscriptions with an end time in the future.
- Backfill subscriptions are subscriptions with a start and end time in the past.
Subscriptions may have either a backfill or forwardfill portion, or both. For example, a subscription’s start time may be 3 years in the past to gather baseline data and then end at a time in the future. As long as a forwardfill subscription is running, you can update it.
During periods of high demand, Planet load balances data production and delivery between customers and their individual subscriptions to deliver a steady stream of data as fast as possible. For each subscription, delivery of forwardfill data is prioritized over backfill so that customers always have access to the latest data as soon as possible.
The Planet SDK for Python also supports connecting to the Subscriptions API and has a powerful “backfill” capability to bulk order historical imagery to your area of interest.
Subscriptions API limits¶
Note
These limits are validated when a subscription is created. If an organization exceeds its limits, all existing active subscriptions (i.e.: end_time has not passed) continue to deliver imagery and are not suspended or cancelled. Only new subscriptions cannot be created.
Additionally, if an organization has insufficient quota, new subscriptions cannot be created, however, active systems are not suspended or cancelled.
An “active” subscription is one where the end_time has not passed.
Subscriptions API use is limited to a maximum count of active subscriptions and a maximum total count of expected items delivered daily across all forwardfill portions of a subscriptions.
Backfill portions of subscriptions are limited to 5 years of archive delivery from the defined start_time. This means that if a subscription has a start_time of December 1, 2015, a valid end_time would be December 1, 2020. If more than 5 years of archive imagery is required, we recommend creating additional subscriptions to deliver that imagery.
- Max Forwardfill Subscriptions: Maximum number of active subscriptions. A new subscription may not be created if an organization has already maxed out its number of active 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 seven days. These numbers are totaled across all forwardfill subscriptions.
- Note: Validation on "expected items delivered daily" is done upfront, at subscription creation. The Subscriptions API does not artificially limit item delivery if a subscription happens to match more items than expected on a given day.
By default, customers are subject to the following limits:
- Max Subscriptions: 2,000
- Total Expected Forwardfill Items Delivered Daily: 2,000
Please reach out to your Account Manager, or submit a request, if you need these limits to be increased.
Rate limiting¶
To improve the experience for all of our users, Planet uses rate limiting to prevent overloading the system. If handled correctly, rate limiting errors can be a normal and useful part of working with the API.
When a rate limit has been exceeded, the Planet API responds with an HTTP 429 response code. When this occurs, we recommend implementing retry with an exponential backoff. An exponential backoff means that you wait for exponentially longer intervals between each retry of a single failing request.
The following rate limits are currently in place:
- Subscription Creation - 5 requests per second, per API key.
- Subscription Cancelation - 5 requests per second, per API key.
- Get Subscription - 5 requests per second, per API key.
- Get Subscription Results - 5 requests per second, per API key.
Learning Resources
For information on working with Planet APIs, see Get Started with Planet APIs. Find a collection of guides and tutorials on Planet University. Also checkout Planet notebooks on GitHub, such as the Subscriptions tutorials: subscriptions_api_tutorial.
Rate this guide: