Skip to main content

Mechanics

Create a Subscription​

You can create a subscription by submitting a full subscription request to the following endpoint:

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

A basic subscription must include a name and source block. Subscriptions also support select tools and a delivery block for specifying cloud storage and hosting. A subscription request will be rejected if the geometry specified in the geometry attribute or the 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.

Subscriptions API supports various different data products with nuanced properties within the source block. Data products that belong to the Planet scene catalogs (For example, PSScene, SkySatScene, TanagerScene, etc.) can be subscribed to using the catalog source block, and all other data products Subscriptions API supports (For example, Planetary Variables, Analysis-Ready PlanetScope) can be subscribed to using the subscription source block. These different source blocks are described in more detail in the subscription sources section.

Time series data is available via the results endpoint for all subscriptions after they are created. Planetary Variable and Analysis-Ready PlanetScope subscriptions can be created as results only subscriptions by omitting the delivery parameter. A results only subscription will not deliver any data products to cloud storage. Catalog subscriptions cannot be created as results-only subscriptions.

Example: PSScene Subscription Request​

This example creates a subscription that will deliver imagery to a Google Cloud Storage bucket.

curl -X POST "https://api.planet.com/subscriptions/v1" \
    --include \
    -H "Authorization: api-key $PL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "Example PSScene Subscription",
        "source": {
            "type": "catalog",
            "parameters": {
                "item_types": ["PSScene"],
                "asset_types": ["ortho_analytic_4b"],
                "start_time": "2025-01-15T00:00:00.0Z",
                "end_time": "2025-01-15T00:00:01.0Z",
                "time_range_type": "acquired",
                "geometry": {
                    "coordinates": [
                        [
                            [139.56481933, 35.42374884],
                            [140.10314941, 35.42374884],
                            [140.10314941, 35.77102915],
                            [139.56481933, 35.77102915],
                            [139.56481933, 35.42374884]
                        ]
                    ],
                    "type": "Polygon"
                }
            }
        },
        "delivery": {
            "type": "google_cloud_storage",
            "parameters": {
                "bucket": $GCS_BUCKET,
                "credentials": $GCS_CREDENTIALS
            }
        }
    }'

Example: Planetary Variable Subscription Request​

Here is an example of a JSON payload for SWC-AMSR2-X_V5.0_1000 results only subscription over San Francisco using a Feature Reference ID. Note that this example omits the delivery parameter.

curl -X POST "https://api.planet.com/subscriptions/v1" \
    --include \
    -H "Authorization: api-key $PL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "Example Soil Moisture Subscription",
        "source": {
            "type": "soil_water_content",
            "parameters": {
                "id": "SWC-AMSR2-X_V5.0_1000",
                "start_time": "2025-01-15T00:00:00.0Z",
                "end_time": "2025-01-15T00:00:01.0Z",
                "geometry": {
                    "content": "pl:features/my/feature_collection-2q26z0q/mX9dB1o",
                    "type": "ref"
                }
            }
        }
    }'

Example: Analysis-Ready PlanetScope Subscription Request​

This example creates a subscription that will deliver Analysis-Ready PlanetScope imagery. Please note that Analysis-Ready PlanetScope does not support any tools at this time.

curl -X POST "https://api.planet.com/subscriptions/v1" \
    --include \
    -H "Authorization: api-key $PL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "Example Analysis-Ready PlanetScope Subscription",
        "source": {
            "type": "analysis_ready_ps",
            "parameters": {
                "id": "PS_ARD_SR_DAILY",
                "start_time": "2025-01-15T00:00:00.0Z",
                "end_time": "2025-01-15T00:00:01.0Z",
                "geometry": {
                    "coordinates": [
                        [
                            [-122.39334886, 37.79508572],
                            [-122.41963198, 37.79508572],
                            [-122.41963198, 37.77362268],
                            [-122.39334886, 37.77362268],
                            [-122.39334886, 37.79508572]
                        ]
                    ],
                    "type": "Polygon"
                }
            }
        },
        "hosting": {
            "type": "sentinel_hub"
        }
    }'

Update a Subscription​

You can update a subscription by submitting a full subscription request to the following endpoint:

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

A subscription may be updated when it is in a pending or running state, with certain constraints:

  • source.start_time: Cannot be updated if the start time is in the past.
  • source.item_type: Cannot be modified.
  • notifications: Cannot be modified.

All other elements may be updated as long as the subscription does not surpass the limit on expected items delivered daily:

  • name: May be modified.
  • source.start_time: May be modified if the start time is in the future.
  • source.end_time: May be modified if the subscription has not expired.
  • source.geometry: May be modified only for the catalog source type.
  • source.rrule: May be modified. Not supported for Analysis-Ready PlanetScope.
  • delivery: May be modified.

Importantly, the update 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.

Example: Update a Subscription​

curl -X PUT "https://api.planet.com/subscriptions/v1/${SUBSCRIPTION_ID}" \
    --include \
    -H "Authorization: api-key $PL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "Updated Subscription",
        "source": {
            "type": "catalog",
            "parameters": {
                "item_types": ["PSScene"],
                "asset_types": ["ortho_analytic_4b"],
                "start_time": "2025-01-15T00:00:00.0Z",
                "end_time": "2025-01-15T00:00:01.0Z",
                "time_range_type": "acquired",
                "geometry": {
                    "coordinates": [
                        [
                            [139.56481933, 35.42374884],
                            [140.10314941, 35.42374884],
                            [140.10314941, 35.77102915],
                            [139.56481933, 35.77102915],
                            [139.56481933, 35.42374884]
                        ]
                    ],
                    "type": "Polygon"
                }
            }
        },
        "delivery": {
            "type": "google_cloud_storage",
            "parameters": {
                "bucket": $GCS_BUCKET,
                "credentials": $GCS_CREDENTIALS
            }
        }
    }'

Patch a Subscription​

You can patch specific subscription properties by submitting a PATCH request:

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

Not all properties 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 of a subscription state.

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

Example: Patch a Subscription​

curl -X PATCH "https://api.planet.com/subscriptions/v1/${SUBSCRIPTION_ID}" \
    --include \
    -H "Authorization: api-key $PL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "Patch Subscription"
    }'

Cancel a Subscription​

You can cancel a subscription with the following request:

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

After a subscription is canceled, no additional items will be delivered (except for any items in processing or delivery). A canceled subscription cannot be transitioned to running state. canceled subscriptions will continue to be returned in the GET subscriptions response.

Example: Cancel a Subscription​

curl -X POST "https://api.planet.com/subscriptions/v1/${SUBSCRIPTION_ID}/cancel" \
    --include \
    -H "Authorization: api-key $PL_API_KEY" \
    -H "Content-Type: application/json"

Get a Subscription​

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

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

The response will include the original request, pagination links, a results link, and system generated properties like status, created timestamp, and updated timestamp.

Example: Get a Subscription​

curl -X GET "https://api.planet.com/subscriptions/v1/${SUBSCRIPTION_ID}" \
    --include \
    -H "Authorization: api-key $PL_API_KEY" \
    -H "Content-Type: application/json"

List Subscriptions​

You can list all subscriptions with the following request:

GET https://api.planet.com/subscriptions/v1
curl -X GET "https://api.planet.com/subscriptions/v1" \
    --include \
    -H "Authorization: api-key $PL_API_KEY" \
    -H "Content-Type: application/json"

This access pattern supports query parameters for filtering:

  • status
  • source_type
  • user_id

Example: List Subscriptions By Status​

curl -X GET "https://api.planet.com/subscriptions/v1?status=running" \
    --include \
    -H "Authorization: api-key $PL_API_KEY" \
    -H "Content-Type: application/json"

Example: List Subscriptions By Source Type​

curl -X GET "https://api.planet.com/subscriptions/v1?source_type=catalog" \
    --include \
    -H "Authorization: api-key $PL_API_KEY" \
    -H "Content-Type: application/json"

Example: List Subscriptions By User ID​

curl -X GET "https://api.planet.com/subscriptions/v1?user_id=123" \
    --include \
    -H "Authorization: api-key $PL_API_KEY" \
    -H "Content-Type: application/json"

List Subscription Results​

The response will include a paginated list of all of the subscription's results that were created within the last 30 days. A result for the catalog source type subscription represents an attempt to process and deliver an item that matches your subscription criteria. Results for at least the past 30 days of deliveries will be returned. The response schema will include:

PropertyDescription
idThe unique ID of the subscription result.
statusThe delivery status of the result's item. Result status can be either created, queued, processing, success, or failed. See the section on subscription states and statuses for more details.
propertiesTime series data for the subscription. See Catalog properties and Planetary Variable/Analysis-Ready PlanetScope properties tables for details.
createdThe time the result was generated. For a catalog source type subscription, this will be when the subscription acknowledges the newly published item.
updatedThe time that the result was last updated.
completedThe time the result reached an end status of success or failed.
errorsInformation on result failure, including a reason and array of details.
outputThe directories of the final output files.

Catalog subscription results​

PropertyDescription
item_idThe item_id of the result.
item_typesThe item_type of the result.

Planetary Variable and Analysis-Ready PlanetScope results​

PropertyDescription
item_idThe item_id of the result.
local_solar_timeTime based on the position of the Sun in the sky when the asset was captured.
source_idThe specific product ID for the subscription.
statistics[].assetThe data product that the statistic is calculated from.
statistics[].bandThe specific range of wavelengths in the electromagnetic spectrum that the statistic is calculated from.
statistics[].nameThe name of the statistic: valid_percent (integer from 0 - 100), mean (floating point with two fractional digits).
statistics[].typeThe data type of the statistic, e.g. number.
statistics[].valueThe value of the statistic.

You can filter subscriptions results by status (For example, ?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.

Example: List Subscription Results​

curl -X GET "https://api.planet.com/subscriptions/v1/${SUBSCRIPTION_ID}/results" \
    --include \
    -H "Authorization: api-key $PL_API_KEY" \
    -H "Content-Type: application/json"

Get a Summary​

You can get a summary of all the subscriptions you have created by status with the following request:

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

The response will include a count of subscriptions by status.

Example: Get Summary​

curl -X GET "https://api.planet.com/subscriptions/v1/summary" \
    --include \
    -H "Authorization: api-key $PL_API_KEY" \
    -H "Content-Type: application/json"

If you are an organization administrator, you can get a summary of all subscriptions created in your organization by including the user_id=all query parameter.

Example: Get Summary as Org Admin​

curl -X GET "https://api.planet.com/subscriptions/v1/summary?user_id=all" \
    --include \
    -H "Authorization: api-key $PL_API_KEY" \
    -H "Content-Type: application/json"

Get a Subscription Summary​

You can get a summary of result statuses for a single subscription with the following request:

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

The response will include a count of results by status, as well as the subscription status.

Example: Get Subscription Summary​

curl -X GET "https://api.planet.com/subscriptions/v1/${SUBSCRIPTION_ID}/summary" \
    --include \
    -H "Authorization: api-key $PL_API_KEY" \
    -H "Content-Type: application/json"
note

Org admins may get summaries of any subscription within the organization. No extra parameters are required.

Most Planet API responses contain a _links object that contains a list of hyperlinks to itself and related data. You are encouraged to rely on these links rather than constructing the links yourself.

The most common _link is _self, which is a self reference. When an API response is paginated, _links will contain _next and _prev references.

Pagination​

The Planet API paginates responses to limit the results, making them easier to work with. The first GET request will yield the first page along with _links representing the location of the _next page. Following the _next link will return another page of results. This process may be repeated until the _next link is no longer returned, which indicates the last page of the results.

The following _links are provided in the response to facilitate pagination:

  • _self - The canonical location of the current page.
  • _first - The initial page.
  • _next - The page that logically follows the current page.
  • _prev - The page that logically precedes the current page.
Last updated on