Skip to main content

Sources

The Subscription API's source block describes the items and formats you want, filtered to your specifications. The subscription pulls this source data from the Planet imagery and Planetary Variables catalog.

Catalog Source Type​

The catalog source block parameters require the Planet core imagery catalog of scenes. These Planet data products are automatically published in our catalog and immediately searchable via Planet's Data API.

Parameters​

The parameters of the catalog source block require item_types and asset_types, much like the Data API's /quick-search endpoint.

PropertyRequiredDescription
item_typesRequiredRepresent the class of spacecraft and processing level of the subscription's matching items. PSScene is an example of an item type. You can read more on item types here.
asset_typesRequiredRepresent the data products that will be delivered for all subscription-matching items. An item will only match and deliver if all specified asset types are published for that item. analytic_sr is an example of an asset type available for a PSScene item. You can view an overview of available asset types here.
geometryRequiredRepresents the GeoJSON geometry or feature reference of the subscription's area of interest, which is used to determine matches. Only Polygon & MultiPolygon geometry types are supported.
start_timeRequiredRepresents the subscription's start time. This time can be in the past or future.
end_timeOptionalRepresents the end time of the subscription. This time can be in the past or future, and must be after the start_time.
time_range_typeOptionalRepresents time of interest type. The two options are acquired or published. acquired date represents when the image is taken. published represents when the item was first published in the Planet catalog.
rruleOptionalRepresents the recurrence rule. Only monthly recurrences are supported at this time. More details can be found below.
filterOptionalDescribes item filter criteria based on item-level metadata. Available filter types are described in more detail in the Filter Details section below.
publishing_stagesOptionalRepresent the imagery to be delivered for subscriptions based on publishing stage (preview, standard, finalized). When included in the creation request, a subscription only delivers items with a publishing stage attribute that match what is included here. If multiple versions of an item match the included publishing stages, the Subscriptions API delivers the version in the latest publishing stage. If you specifically want a preview image, set the publishing_stages to only preview. The Subscription API only delivers an item once. If the publishing_stages attribute is not included, a customer should get either standard or finalized imagery.

RRule (Recurrence Rule)​

Recurrence rules create subscriptions that deliver during recurring periods within the total coverage time. Our implementation leverages the iCalendar Recurrence Rules specification.

Subscriptions API supports monthly recurrences (For example, recurrences defined using the BYMONTH property along with FREQ=YEARLY or recurrences defined using FREQ=MONTHLY).

If an rrule is included in a subscription creation request, an end_time must be included that is within 5 years of the subscription’s creation time. Start and end times should not be provided in the RRule: the subscription will always respect the timestamps included in the start_time and end_time parameters.

Example​

A subscription where only imagery between March and October is delivered for images published between March 1, 2020 and November 1, 2022:

{
  "start_time": "2020-03-01T00:00:00Z",
  "end_time": "2022-11-01T00:00:00Z",
  "rrule": "FREQ=MONTHLY;BYMONTH=3,4,5,6,7,8,9,10"
}

Filter Details​

The filter object is designed to leverage search filters in the Data API. The filter can support a top level AndFilter, OrFilter, NotFilter, and one level of filters nested under it, or one top level filter of another type.

A subscription can leverage all filter types (with the exception of DateRangeFilter and GeometryFilter).

The Subscriptions API implicitly includes the PermissionFilter when delivering results based on the requester’s permissions to download.

Validation​

The Subscriptions catalog source block has a handful of validation exceptions to take note of:

item_types​

A subscription can only be successfully created if one item type is specified.

asset_types​

A subscription can only be successfully created if all asset_types specified are supported for the item type specified.

end_time​

  • A subscription must end after the start_time timestamp.
  • A subscription must have an end time less than or equal to 5 years from the start_time if an rrule is included.

rrule​

  • A subscription can only support monthly recurrences. BYWEEKNO, BYMONTHDAY, BYYEARDAY, BYDAY, BYHOUR, BYMINUTE, BYSECOND, BYEASTER are not supported.
  • Start and end times provided using DTSTART and/or UNTIL are not supported and will produce an error.

filter​

  • publishing_stages (optional), if used, must not be an empty list. If a publishing_stages attribute is included in the source block, the only acceptable fields are preview, standard, or finalized. If you create a list with multiple stages, the latest stage is delivered. If you specifically want a preview image, create a separate subscription passing only preview for the `publishing_stages value.
    • For PSScene preview, standard, or finalized is valid.
    • For SkySatScene only preview or finalized is valid.
    • For SkySatCollect only finalized is valid.
    • For SkySatVideo only finalized is valid.

Example​

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

Planetary Variable and Analysis-Ready Source Types​

The Subscriptions API also supports other products like Planetary Variables and Analysis-Ready PlanetScope which are different from catalog source types. In the Subscriptions API OpenAPI Specification, these are called "Subscription Source" types. These products are not searchable via Planet's Data API, and are only available through the Subscriptions API.

Parameters​

The source blocks require a type, and the parameters are id, geometry, start_time, and end_time.

PropertyRequiredDescription
typeRequiredRepresents the type of Planetary Variable or Analysis-Ready PlanetScope product (e.g soil_water_content). Please visit the Planetary Variable and Analysis-Ready PlanetScope product pages to determine the value for the type.
idRequiredRepresents the specific product for the subscription (e.g. SWC-SMAP-L_V1.0_100). Please visit the Planetary Variable and Analysis-Ready PlanetScope product pages to determine the value for the id.
geometryRequiredRepresents the GeoJSON geometry or feature reference of the subscription's area of interest, which is used to determine matches. Planetary Variables support Polygon & MultiPolygon geometry types. Analysis-Ready PlanetScope supports the Polygon geometry type, it does not support MultiPolygon geometries.
start_timeRequiredRepresents the start time of the subscription. This time can be in the past or future.
end_timeOptionalRepresents the end time of the subscription. This time can be in the past or future, and must be after the start_time.

Validation​

The Subscriptions Planetary Variable source block has a handful of validation exceptions to take note of.

type​

A subscription can only be successfully created if one type is specified.

id​

A subscription can only be successfully created if the id specified is supported by the type specified.

end_time​

A subscription must end after the start_time timestamp.

Example​

"source": {
    "type": "soil_water_content",
    "parameters": {
        "id": "SWC-AMSR2-X_V5.0_1000",
        "start_time": "2022-12-07T00:00:00Z",
        "end_time": "2022-12-16T00:00:00Z",
        "geometry": {
            "content": "pl:features/my/feature_collection-2q26z0q/mX9dB1o",
            "type": "ref"
        }
    }
}
Last updated on