Subscribing to Planet Imagery

The Subscriptions API provides continuous cloud delivery of imagery, metadata, and analysis.

To create an imagery subscription, you can specify filter criteria, raster processing tools, and a cloud delivery location. The API then automatically processes and delivers 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.

Create an Imagery Subscription¶

A basic subscription must include a name, catalog source block (with item_types, asset_types, geometry, start_time, end_time), and a delivery block with a specified cloud storage location. Subscriptions also support select tools. A subscription request will be rejected if the geometry specified in the geometry attribute and clip tool exceeds 1,500 vertices.

A subscription processes and delivers items as soon as all item filter criteria are met, and all requested asset types have been published and are available for delivery.

Monitoring across seasons¶

The Subscriptions API can support seasonal monitoring by delivering archive imagery and future collections for specific months over the duration of a subscription.

To create a subscription that delivers imagery within specific time periods during a time of interest, utilize the rrule attribute that leverages iCalendar recurrence rules. This can be used to create subscriptions that deliver items for recurring periods within the total coverage time. More details can be found in the Source RRule section.

Example Request¶

This example creates a subscription that will deliver imagery acquired between March 2021 and October 2023.

POST https://api.planet.com/subscriptions/v1/

{
    "name": "Example Subscription",
    "source": {
        "type": "catalog",
        "parameters": {
            "geometry": {
                "coordinates": [[[139.5648193359375,35.42374884923695],
                                [140.1031494140625,35.42374884923695],
                                [140.1031494140625,35.77102915686019],
                                [139.5648193359375,35.77102915686019],
                                [139.5648193359375,35.42374884923695]]],
                "type": "Polygon"
            },
            "time_range_type": "acquired",
            "start_time": "2021-03-01T00:00:00Z",
            "end_time": "2023-11-01T00:00:00Z",
            "item_types": ["PSScene"],
            "asset_types": ["ortho_analytic_4b"]
        }
    },
    "delivery": { ... }
}

Edit an Imagery Subscription¶

Edit via PUT request¶

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 a pending or running state, it may be edited with certain constraints. The following source block edits will be disallowed:

• start_time: Cannot be edited if the start time is in the past.
• geometry: Cannot be modified.
• item_type: Cannot be modified.

All other source filter criteria may be edited, as long as subscription does not surpass the limit on expected items delivered daily. These include:

• start_time: May be modified if the start time is in the future.
• end_time: May be modified if the subscription has not expired.
• rrule: May be modified.

Additionally, outside of the source block, the following elements may also be edited:

• name: May be modified.
• delivery: May be modified.

The following elements may not be modified:

• notifications: Cannot be modified.

Importantly, the edit will only apply to future item publications and deliveries. No items will be redelivered. If you need to reorder archive items based on an updated filter or tool specifications, you can search for and order archive items with the Data API and Orders API.

Edit via PATCH request¶

You can edit certain subscription attributes by submitting a PATCH request:

PATCH https://api.planet.com/subscriptions/v1/<subscription_id>

Not all attributes can be edited this way, but they are subject to fewer restrictions than PUT requests. Importantly, the full subscription request body is not required and such requests are accepted regardless subscription state.

See the API reference for the full list of supported attributes.

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 an Imagery 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>

You can get a list of all subscriptions of a specific source_type. For example, the following call returns all of your imagery Subscriptions.

GET https://api.planet.com/subscriptions/v1/results?format=csv&source_type=catlog

If you are an organization administrator, you can get details for all subscriptions in an organization by including the user_id=all query parameter (Note: the api_key must be of a requestor that is an org admin):

GET https://api.planet.com/subscriptions/v1?user_id=all

or

GET https://api.planet.com/subscriptions/v1/<subscription_id>?user_id=all

Get Imagery 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 for at least the past 30 days of deliveries will 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 organization administrator, you also have the ability to get subscription results for any subscription created in your organization by including the user_id=all query parameter.

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¶

{
    "name": "Example Subscription",
    "source": {
        "type": "catalog",
        "parameters": {
            "asset_types": [
                "ortho_analytic_4b"
            ],
            "end_time": "2025-11-01T00:00:00Z",
            "geometry": {
                "coordinates": [
                    [
                        [
                            139.5648193359375,
                            35.42374884923695
                        ],
                        [
                            140.1031494140625,
                            35.42374884923695
                        ],
                        [
                            140.1031494140625,
                            35.77102915686019
                        ],
                        [
                            139.5648193359375,
                            35.77102915686019
                        ],
                        [
                            139.5648193359375,
                            35.42374884923695
                        ]
                    ]
                ],
                "type": "Polygon"
            },
            "item_types": [
                "PSScene"
            ],
            "start_time": "2022-01-01T00:00:00Z",
          "time_range_type": "acquired"
        }
    },
    "delivery": {
        "type": "google_cloud_storage",
        "parameters": {
            "bucket": "[your-GCP-bucket-name]",
            "credentials": "[base64-encoded-credentials-for-service-agent…]"
        }
    },
    "created": "2022-11-21T21:46:18.392063Z",
    "_links": {
        "_self": "https://api.planet.com/subscriptions/v1/1ac43ca5-2ac5-48b0-a4b2-f72032cc3f03"
    },
    "status": "preparing",
    "id": "1ac43ca5-2ac5-48b0-a4b2-f72032cc3f03",
    "updated": "2022-11-21T21:46:18.392063Z"
}

---

Rate this guide: