Subscriptions Overview

last updated: February 05, 2024

Overview of the Subscriptions API

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.

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 catalog source type is supported. It takes item_types, asset_types, geometry, start_time, and a filter, and closely mirrors a Data API /quick-search request.
    • For Planetary Variables, the source type is based on the product offering: biomass_proxy, land_surface_temperature, soil_water_content, vegetation_optical_depth.
  • 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

Subscriptions API states

Status descriptions

  • preparing: The subscription was successfully submitted and is being set up.
  • pending: The subscription’s source start time (start_time value) 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_time value) 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 API backfill and forwardfill graph

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: