Overview

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, the catalog source type is supported. It takes item_types, asset_types, and a filter, and closely mirrors a Data API /quick-search request.
  • tools: Describes raster tools which may be applied to a susbcription. Currently, only clip 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

Subscriptions API states

Status Descriptions

  • preparing: The subscription was successfully submitted and is being set up.
  • pending: The subscription's source start time (published DateRangeFilter gt or gte value) has not yet passed. Delivery has not yet started.
  • active: 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 or lte 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.

Ordering Future Collections and Archive Imagery

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.

Subscriptions API forwardfill graph

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.

Subscriptions API forwardfill & backfill graph

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 number of active subscriptions with a cap on the total number of expected items delivered daily.

  • Max active Subscriptions: Maximum number of subscriptions an organization may maintain in an active state. A new subscription may not be created if an organization has already maxed out its number of active subscriptions.
  • Total Expected Items Delivered Daily: Total number of expected items matched and delivered daily across all active subscriptions. A new 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 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 active subscriptions.
    • New subscriptions cannot be created if they put the total number of expected items delivered daily over the maximum limit.
    • 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 active Subscriptions: 1,000 Total Expected 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 active, the following source block edits will be disallowed:

  • Changes to item_types
  • Changes to published DateRangeFilter gt and gte 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 active 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 active or completed states:

GET https://api.planet.com/subscriptions/v1?status=active&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 a catalog 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 of success or failed.
  • errors: Information on result failure, including a reason and array of details.
  • 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"
      ]
    }
  ]
}