Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/subscriptions/sources/) # 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 utilizes 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. The `type` parameter is optional and, if ommitted, will be inferred by the presence of `item_types`. If you wish to specify `type`, the acceptable value is `catalog`. ### Parameters | Property | Required | Description | | ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **item\_types** | Required | 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](https://docs.planet.com/develop/apis/data/items.md). | | **asset\_types** | Required | Represent 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](https://docs.planet.com/data/imagery/planetscope/psscene.md). | | **geometry** | Required | Represents the area(s) of interest for your subscription, which is used to determine matches. For regular subscriptions a GeoJSON geometry or [feature reference](https://docs.planet.com/develop/apis/features/#feature-references) can be specified. For bulk subscriptions a feature collection reference should be used. Only Polygon & MultiPolygon geometry types are supported. | | **start\_time** | Required | Represents the subscription's start time. 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 | Specifies the type of timestamp to filter by: `acquired` (default) or `published`. `acquired` refers to when the image was captured, while `published` refers to when the item was first published in the Planet catalog. | | **rrule** | Optional | Represents the recurrence rule. Only monthly recurrences are supported at this time. More details can be found below. | | **filter** | Optional | Describes item filter criteria based on item-level metadata. Available filter types are described in more detail in the Filter Details section below. | | **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. 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. | | **geometry\_relation** | Optional | Specifies the relationship between the subscription's geometry and a matched item's geometry. More details can be found below. | ### RRule (Recurrence Rule) Recurrence rules create subscriptions that deliver during recurring periods within the total coverage time. Our implementation leverages the [iCalendar Recurrence Rules](https://icalendar.org/iCalendar-RFC-5545/3-8-5-3-recurrence-rule.html) 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" } ``` ### Geometry Relation The `geometry_relation` parameter specifies the relationship between the subscription's geometry and a matched item's geometry. This parameter is an extension of the [Data API's GeometryFilter](https://docs.planet.com/develop/apis/data/item-search.md#geometryfilter). * `intersects` (default) : Returns items whose footprint geometry partially or fully overlaps with the subscription geometry. * `contains` : Returns items where the footprint geometry fully encloses the subscription geometry. * `within` : Returns items whose entire footprint geometry is fully contained within the subscription geometry. Notably, subscriptions does not support the `disjoint` relation. ### Filter Details The filter object is designed to leverage [search filters in the Data API](https://docs.planet.com/develop/apis/data/item-search.md#filters). 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. * For PelicanScene only `finalized` is valid. ### Example * JSON * Python SDK * CLI ``` "source": { "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" }, "geometry_relation": "intersects" } } ``` ``` from datetime import datetime from planet.subscription_request import catalog_source catalog_source = catalog_source( item_types=["PSScene"], asset_types=["ortho_analytic_4b"], start_time=datetime.fromisoformat("2024-11-05T00:00:00Z"), end_time=datetime.fromisoformat("2024-11-10T00:00:00Z"), 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", }, geometry_relation="intersects", ) ``` ``` geometry="{ \"coordinates\": [ [ [139.56481933, 35.42374884], [140.10314941, 35.42374884], [140.10314941, 35.77102915], [139.56481933, 35.77102915], [139.56481933, 35.42374884] ] ], \"type\": \"Polygon\" }" planet subscriptions request-catalog \ --item-types PSScene \ --asset-types ortho_analytic_4b \ --start-time 2021-03-01T00:00:00.0Z \ --end-time 2023-11-01T00:00:00.0Z \ --time-range-type acquired \ --geometry "$geometry" \ --geometry-relation intersects ``` ## 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](https://docs.planet.com/develop/apis/subscriptions/reference.md#tag/subscriptions/operation/createSubscription), these are called "Subscription Source" types. These products are not searchable via Planet's Data API, and are only available through the Subscriptions API. The `type` parameter is optional and, if ommitted, will be inferred by `id`. If you wish to specify `type`, please visit the [Planetary Variables](https://docs.planet.com/data/planetary-variables.md) and [Analysis-Ready PlanetScope](https://docs.planet.com/data/imagery/arps.md) product pages to determine the acceptable values. ### Parameters | Property | Required | Description | | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **id** | Required | Represents the specific product for the subscription (e.g. SWC-SMAP-L\_V1.0\_100). Please visit the [Planetary Variable](https://docs.planet.com/data/planetary-variables.md) and [Analysis-Ready PlanetScope](https://docs.planet.com/data/imagery/arps.md) product pages to determine the value for the `id`. | | **geometry** | Required | Represents the area(s) of interest for your subscription, which is used to determine matches. For regular subscriptions a GeoJSON geometry or [feature reference](https://docs.planet.com/develop/apis/features/#feature-references) can be specified. For bulk subscriptions a feature collection reference should be used. Only Polygon & MultiPolygon geometry types are supported. | | **start\_time** | Required | 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 Planetary Variable source block has a handful of validation exceptions to take note of. #### id A subscription can only be successfully created if the `id` specified is supported. If `type` is specified, the `id` must be for the provided `type`. #### end\_time A subscription must end after the `start_time` timestamp. ### Example * JSON * Python SDK * CLI ``` "source": { "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" } } } ``` ``` from datetime import datetime from planet.subscription_request import subscription_source pv_source = subscription_source( source_id="SWC-AMSR2-X_V5.0_1000", start_time=datetime.fromisoformat("2022-12-07T00:00:00Z"), end_time=datetime.fromisoformat("2022-12-16T00:00:00Z"), geometry={ "coordinates": [ [ [139.56481933, 35.42374884], [140.10314941, 35.42374884], [140.10314941, 35.77102915], [139.56481933, 35.77102915], [139.56481933, 35.42374884], ] ], "type": "Polygon", }, ) ``` ``` planet subscriptions request-source \ --source-id SWC-AMSR2-X_V5.0_1000 \ --start-time 2022-12-07T00:00:00.0Z \ --end-time 2022-12-16T00:00:00.0Z \ --geometry pl:features/my/feature_collection-2q26z0q/mX9dB1o ```