Source

last updated: December 15, 2021

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.

Deprecated

Please note that the source schema has been updated in October 2021. The Subscriptions API has transitioned the area of interest geometry from the GeometryFilter to the geometry top-level attribute, and subscription start and end time from the DateRangeFilter to the start_time and end_time top-level attributes.

Catalog Source Type

The catalog source block references Planet's core imagery catalog of scenes and orthotiles. 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. PSScene4Band 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 PSScene4Band item. You can view an overview of available asset types here.
  • geometry: represents the geometry of the area of interest of the subscription that will be used to determine matches.
  • 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.
  • 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. You can find an overview of all filter types here and filterable properties for each item type here. Required filter types are described in more detail in the next section.

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

Deprecated

We have deprecated DateRangeFilter and GeometryFilter types in order to support features that provide more control over a subscription such as RRules that enable customers to tailor when imagery is delivered.

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.