Source

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

Catalog Source Type¶

The catalog source block references Planet's 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, asset_types, and a filter, much like the Data API's /quick-search endpoint.

• item_types: represent 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_types: represent the data products which 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.
• geometry: represents the GeoJSON geometry of the subscription's area of interest, which is used to determine matches. Only Polygon & MultiPolygon geometry types are supported.
• start_time: represents the start time of the subscription. This time can be in the past or future.
• end_time (optional): represents the end time of the subscription. This time can be in the past or future, and must be after the start_time.
• time_range_type (optional): represents time of interest type. The two options are acquired or published. acquired date represents when the image is actually taken. published represents when the item is first published in Planet’s itemstore.
• rrule (optional): represents the recurrence rule. Only monthly recurrences are supported at this time. More details can be found in the Source RRule section.
• filter(optional): describes item filter criteria based on item-level metadata. Available filter types are described in more detail in the next section.
• publishing_stages (optional): represent 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. This means if you want a preview image, specifically, you would 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.

RRules (Recurrence Rules)¶

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

At this time, a subscription supports only monthly recurrences (i.e. 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 Validation: a subscription can only be successfully created if one item type is specified.
• asset_types Validation: a subscription can only be successfully created if all asset_types specified are supported for the item type specified.
• end_time Validation:
  • 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 Validation:
  • 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 Validation:
  • If a geometry attribute is included in the source block, a GeometryFilter cannot be used.
  • If a start_time and/or end_time attribute is included in the source block, a DateRangeFilter cannot be used. We have deprecated the option to use DateRangeFilter, and encourage users to leverage start_time, end_time, and rrule to manage times of interest.
  • DateRangeFilter acquired and updated values are not currently supported.
  • 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. So if you want a preview image, specifically, 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.

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

• type: represents 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.
• id: represents 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.
• geometry: represents the GeoJSON geometry of the subscription's area of interest, which is used to determine matches. Only Polygon & MultiPolygon geometry types are supported.
• start_time: represents the start time of the subscription. This time can be in the past or future.
• end_time (optional): represents 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 catalog source block has a handful of validation exceptions to take note of.

• type Validation: a subscription can only be successfully created if one type is specified.
• id Validation: a subscription can only be successfully created if the id specified is supported by the type specified.
• end_time Validation:
  • A subscription must end after the start_time timestamp.

---

We are continually working to improve our technical documentation and support. Please help by sharing your experience with us.

Send Us Your Feedback