Subscribing to Planet Imagery

last updated: June 17, 2024

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, source block (with 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.

There are two types of source blocks for Imagery Subscriptions: catalog and analysis_ready_ps.

  • catalog source reference our scene catalogs (e.g. PSScene, SkySatScene, SkySatCollect) and the blocks require item_types, asset_types to be specified.
  • analysis_ready_ps source reference our Analysis-Ready PlanetScope product, and the blocks require id to be specified.

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. RRules are not supported for Analysis-Ready PlanetScope at this time.

Example Analysis-Ready PlanetScope Subscription Request

This example creates a subscription that will deliver Analysis-Ready PlanetScope from imagery captured between October 2023 and January 2024. Please note that Analysis-Ready PlanetScope does not support any tools at this time.

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

{
  "name": "Example Analysis-Ready PlanetScope Subscription",
  "source": {
    "type": "analysis_ready_ps",
    "parameters": {
      "id": "PS_ARD_SR_DAILY",
      "start_time": "2023-10-01T00:00:00Z",
      "end_time": "2024-01-30T00:00:00Z",
      "geometry": {
        "coordinates": [
          [
            [
              -122.39334886532757,
              37.795085729711886
            ],
            [
              -122.4196319874137,
              37.795085729711886
            ],
            [
              -122.4196319874137,
              37.77362268558437
            ],
            [
              -122.39334886532757,
              37.77362268558437
            ],
            [
              -122.39334886532757,
              37.795085729711886
            ]
          ]
        ],
        "type": "Polygon"
      }
    }
  },
  "delivery": {}
}

Example PSScene Subscription 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": { ... }
}

Info

The requested image is not clipped to the specified geometry unless the clip tool is applied. For more information, see our Tools Documentation page.

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 are 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. Not supported for Analysis-Ready PlanetScope.

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 a Subscription

You can get details on a specific subscription with the following request:

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

The response will include the original request, status, created timestamp, updated timestamp, and a link to the subscription results page.

List Subscriptions

You list all subscriptions with the following request:

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

By status

You can filter by status with the status query parameter.

GET https://api.planet.com/subscriptions/v1?status=running&status=completed

By source_type

You can filter by source type with the source_type query parameter.

GET https://api.planet.com/subscriptions/v1/?source_type=catalog

By user_id

As an organization administrator, you can list subscriptions from any and all users in your organization with user_id.

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

To get subscriptions created by a specific user, replace 'all' with the user ID:

GET https://api.planet.com/subscriptions/v1/?user_id=<user-id>

List Subscription 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: