Subscriptions Overview

last updated: November 20, 2024

Overview of the Subscriptions API

The Subscriptions API provides continuous cloud delivery of imagery and Planetary Variables. The Subscriptions API is Planet's recommended data delivery API for customers in need of continuous data feed over areas of interest.

Delivery through the Subscriptions API allows for automation, seamless integration, scalability, customization, and consistent access to the data, while reducing the data processing burden on your end. With Subscriptions APIs, you can tailor the data request parameters to suit your specific needs, such as defining the area of interest, time range, and data frequency. This flexibility ensures that you receive the most relevant data for your use case.

Automation: Subscriptions APIs enable you to automate the process of acquiring Planetary Variables data for your area of interest. By setting up a subscription, you can receive the latest data automatically, without having to manually request it each time.

Integration: APIs are designed to be easily integrated into existing applications, tools, and workflows. By delivering Planetary Variables data through our API, it becomes straightforward to incorporate this valuable information into your current systems, enabling more informed decision-making and analysis.

Scalability: Planet’s Subscriptions API can handle the requests of Planetary Variables data for various scales, from small areas to large regions. This allows you to scale your monitoring and analysis efforts as needed, without being limited by data availability or processing capabilities.

Data Processing: Planet’s Subscriptions API provides a way to access aggregated time series data of Planetary Variables, via the results CSV and JSON endpoints avoiding the need for raster processing.

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, allowing you to create, monitor, and access these products 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.

For experts

Check API Documentation or Download OpenAPI specification.

Imagery Planetary Variables
Activate, customize, and deliver PlanetScope, SkySat, Tanager, 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 catalog imagery (e.g PlanetScope, SkySat, Tanager), 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 and Analysis-Ready PlanetScope, the source type is based on the product offering: biomass_proxy, land_surface_temperature, soil_water_content, vegetation_optical_depth, field_boundaries_sentinel_2_p1m, forest_carbon_diligence_30m, analysis_ready_ps.
  • 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, Microsoft Azure or Oracle Cloud Storage delivery details for the items returned by the subscription.
  • hosting: Describes the Sentinel Hub collection location for the items returned by the subscription.
  • notifications: Describes the notifications which can be delivered for a subscription.

Subscription status

The flowchart below shows the possible subscription statuses. The status of a subscription can be found in the status value of an API response.

Subscriptions API Status Flowchart

Status Description
preparing The subscription was successfully submitted and is being set up.
pending The subscription’s start time has not yet passed or data is being generated; delivery has not yet started.
running The subscription’s start time has passed and it is actively monitoring for new data; delivery may be in progress.
completed The subscription’s end time 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 has stopped.
cancelled The subscription was cancelled by a user; delivery has stopped.
suspended The subscription has a policy or quota conflict; 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.

 


We are continually working to improve our technical documentation and support. Please help by sharing your experience with us.

Send Us Your Feedback