Copy for LLM[View as Markdown](https://docs.planet.com/guides/subscribe-to-planetary-variables/) # Subscribe to Planetary Variables [Planetary Variables](https://docs.planet.com/data/planetary-variables.md) are available using the [Subscriptions API](https://docs.planet.com/develop/apis/subscriptions.md). info Additional Planet API Documentation Find more information in the [API Reference](https://docs.planet.com/develop/apis/subscriptions/reference.md) and check out usage examples in these [Jupyter Notebooks](https://github.com/planetlabs/notebooks/tree/master/jupyter-notebooks/api_guides/subscriptions_api). ## Getting Started with Planetary Variables Subscription 1. [Upload your AOIs to Features Manager](https://docs.planet.com/platform/get-started/access-data/manage-areas-of-interest.md) 2. [Reserve PV quota for your AOIs](https://docs.planet.com/platform/get-started/access-data/reserve-quota.md) 3. [Install Planet SDK](https://planet-sdk-for-python.readthedocs.io/en/stable/get-started/quick-start-guide/) 4. [Sign on to your account](https://planet-sdk-for-python.readthedocs.io/en/stable/get-started/quick-start-guide/#usage) Where do I get the geometry reference? You can get the `pl:features/...` reference after uploading your AOIs to [Features Manager](https://docs.planet.com/platform/get-started/access-data/manage-areas-of-interest.md). Be sure to save the `feature_ref` string for use in your CLI and SDK requests. ### Subscribing with Planet SDK command-line interface The `planet subscriptions` command enables easy interaction with the Subscriptions API. The **no code** command-line interface (CLI) is explained in [Subscriptions API Tutorial](https://planet-sdk-for-python.readthedocs.io/en/stable/cli/cli-subscriptions/). The steps are: 1. Generate a Planetary Variable subscription source with `request-source` 2. Generate a subscriptions request with `request` 3. Create and monitor a subscription with `create` and `get` 4. Finally, you are able to retrieve the data with `results` #### Step 1 - Generate a Planetary Variable Subscription Source The `request-source` [command](https://planet-sdk-for-python.readthedocs.io/en/stable/cli/cli-reference/#request-source) constructs the source part of a Planetary Variable request. For a given Planetary Variables source ID (`--source-id`), the subscription is defined with `--geometry`, `--start-time`, and `--end-time` (optional) parameters. Planetary Variables source IDs are available in the section [#planetary-variables-source-ids](#planetary-variables-source-ids). In the example below, we are subscribing to Crop Biomass Version 4.0 starting on 2022-08-24 and with no end date. ``` planet subscriptions request-source --source-id BIOMASS-PROXY_V4.0_10 \ --geometry pl:features/my/sf_feature_collection-2q26z0q/mX9dB1o --start-time 2022-08-24T00:00:00-07:00 > request-pv.json ``` #### Step 2 - Generate a Subscription Request After the creation of the `request-pv.json` file, the `request` [command](https://planet-sdk-for-python.readthedocs.io/en/stable/cli/cli-reference/#request_1) will generate the JSON payload file ([example](#description-of-the-json-payload)). Raster delivery is optional for Planetary Variables subscriptions. For users that only want to receive time series data, Planetary Variables subscriptions do not require cloud delivery of rasters files. If rasters or vectors outputs are desired, `--delivery cloud-delivery.json` can be added for delivery to a cloud storage [destination](https://docs.planet.com/develop/apis/subscriptions/delivery.md#delivery-to-cloud-storage) or `--hosting sentinel_hub` if the subscribed data is hosted on the browser. ``` planet subscriptions request --name 'First Subscription' --source request-pv.json > my-subscription.json ``` #### Step 3 - Submit and Monitor a Subscription The subscription, as described in `my-subscription.json`, is submitted with the `create` [command](https://planet-sdk-for-python.readthedocs.io/en/stable/cli/cli-reference/#create_3). The response will be displayed and a unique subscription identifier ID will be created (For example, `518b802e-919f-41c6-a068-b8d740b9e64a`). ``` planet subscriptions create my-subscription.json ``` The `get` [command](https://planet-sdk-for-python.readthedocs.io/en/stable/cli/cli-reference/#get_4) outputs the subscription description, including the `status` (see [status definitions](https://docs.planet.com/develop/apis/subscriptions.md#states--status-descriptions)). ``` # For macOS/Linux planet subscriptions get 518b802e-919f-41c6-a068-b8d740b9e64a --pretty | grep status # For Windows (PowerShell) planet subscriptions get 518b802e-919f-41c6-a068-b8d740b9e64a --pretty | select-string status ``` #### Step 4 - Get the Results of a Subscription Data availability notice It may take a few minutes after the subscription is created for the results to become available. If you run the `results` command immediately, you may get an empty file. Please wait until the subscription status is `running` or `completed` before retrieving results. This step allows you to save the time series data and other per-delivery metadata into a CSV file. ``` planet subscriptions results 518b802e-919f-41c6-a068-b8d740b9e64a --csv > my-subscription-results.csv ``` Planet SDK More commands are available for interacting with the Subscriptions API and described in the [CLI reference documentation](https://planet-sdk-for-python.readthedocs.io/en/stable/cli/cli-reference/#subscriptions). ### Subscribing with Planet SDK for Python The documentation is available through the [Planet SDK for Python](https://planet-sdk-for-python.readthedocs.io/en/stable/python/sdk-guide/). ## Description of the JSON Payload The JSON payload of the request must specify these required parameters: | Parameters | Descriptions | | ------------------------------------------- | ------------------------------------------------------ | | **name** | User-defined free text identifier for the subscription | | **source.type** | Planetary Variables data product type | | **source.parameters.id** | Planetary Variables data product identifier (id) | | **source.parameters.start\_time** | Date and time when the subscription begins | | **source.parameters.geometry** | Area of interest (AOI) | | **source.parameters.end\_time \[optional]** | Date and time when the subscription ends (optional) | | **delivery \[optional]** | Cloud storage location (optional) | | **hosting \[optional]** | Hosting configuration (optional) | Find your product parameters The Planetary Variables **source.type** and **source.parameters.id** are described in [#planetary-variables-source-ids](#planetary-variables-source-ids). For more information on **start\_time**, see [this section](https://docs.planet.com/develop/apis/subscriptions/sources.md#planetary-variable-and-analysis-ready-source-types). Here is an example of a JSON payload for `SWC-AMSR2-X_V5.0_1000` over San Francisco using a [Feature Reference ID](https://docs.planet.com/develop/apis/features.md) between December 7th, 2022 and December 16th, 2022, and delivery of raster files to a Google Cloud Bucket. ``` { "name": "Soil Moisture SWC-AMSR2-X_V5.0_1000 - SF", "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/sf_feature_collection-2q26z0q/mX9dB1o", "type": "ref" } } }, "delivery": { "type": "google_cloud_storage", "parameters": { "bucket": "example-bucket", "credentials": "" } } } ``` #### Data Delivery Planetary Variables have three main options for the data [delivery](https://docs.planet.com/develop/apis/subscriptions/delivery.md). **Option 1 - Data hosted on the Browser** Subscriptions can be [delivered to a collection](https://docs.planet.com/develop/apis/subscriptions/delivery.md) by using the `--hosting sentinel_hub` and `--collection-id` flags. The `--collection_id` is optional. If you decide to use this, make sure that the subscription request and the collection have matching bands. If you are unsure, allow the system to create a new collection for you by omitting the `--collection_id` option. This will make sure that the newly set up collection is configured correctly, and you can subsequently add items to this collection as needed. All Planetary Variables are supported for this option. **Option 2 - Raster data delivered to user cloud storage** Soil Water Content, Land Surface Temperature, Forest Carbon, and Crop Biomass provide raster assets that are clipped to the subscription’s AOI. Field Boundaries provides vector assets, also clipped to the AOI. Delivery destination can be specified using the `delivery` parameter. The Subscriptions API supports delivery of rasters to Amazon S3, Microsoft Azure Blob Storage, Google Cloud Storage, Oracle Cloud Storage, [Google Earth Engine](https://docs.planet.com/develop/apis/subscriptions/delivery.md#google-earth-engine), and [other S3-compatible storage providers](https://docs.planet.com/develop/apis/subscriptions/delivery.md#s3-compatible-delivery). All supported cloud delivery options are described [here](https://docs.planet.com/develop/apis/subscriptions/delivery.md#delivery-to-cloud-storage). Here is an example of a JSON payload for delivery to Google Cloud: ``` { "type": "google_cloud_storage", "parameters": { "bucket": "your-gcs-bucket", "credentials": "c29tZWNyZWRzZm9yeW91cmdjc2J1Y2...", "path_prefix": "optionalsubfolder1/optionalsubfolder2" } } ``` All Planetary Variables are supported for this option. **Option 3 - Time series-only delivery** Time series data is available for all planetary variable subscriptions. It is also possible to only receive time series data and not require cloud storage by simply omitting the `delivery` parameter when creating a subscription. The time series data includes two statistics: * `valid_percent`: Integer from 0 to 100 * `mean`: Floating point with two fractional digits (these are digits after decimal point) ![Subscriptions API Land Surface Temperature CSV Data Frame](/notebooks/subscribe-to-pv/subscriptions_lst_csv_df.webp) All Planetary Variables are supported for this option. #### Status Descriptions Status definitions are provided [here](https://docs.planet.com/develop/apis/subscriptions.md#states--status-descriptions). ## Planetary Variables Source IDs The following tables outline data coverage and subscription constraints for Planetary Variable products. The listed time ranges reflect the standard archive availability for ongoing subscriptions. Many Planetary Variable products support **backfill subscriptions** that may extend beyond these ranges. For more details, refer to the [product specific documentation](https://docs.planet.com/data/planetary-variables.md). ### Crop Biomass Loading... For more information, see the [Crop Biomass product page](https://docs.planet.com/data/planetary-variables/crop-biomass.md). ### Field Boundaries Loading... For more information, see the [Field Boundaries product page](https://docs.planet.com/data/planetary-variables/field-boundaries.md). ### Forest Carbon Diligence #### Canopy Height 30m Loading... #### Canopy Cover 30m Loading... #### Aboveground Carbon Density 30m Loading... For more information, see the [Forest Carbon Diligence product page](https://docs.planet.com/data/planetary-variables/forest-carbon-diligence.md). ### Forest Carbon Monitoring #### Canopy Height 3m Loading... #### Canopy Cover 3m Loading... #### Aboveground Carbon Density 3m Loading... For more information, see the [Forest Carbon Monitoring product page](https://docs.planet.com/data/planetary-variables/forest-carbon-monitoring.md). ### Land Surface Temperature #### Land Surface Temperature 20 m Loading... #### Land Surface Temperature 100 m Loading... #### Land Surface Temperature 1000 m Loading... For more information, see the [Land Surface Temperature product page](https://docs.planet.com/data/planetary-variables/land-surface-temperature.md). ### Soil Water Content #### Soil Water Content 20 m Loading... #### Soil Water Content 100 m Loading... #### Soil Water Content 1000 m Loading... For more information, see the [Soil Water Content product page](https://docs.planet.com/data/planetary-variables/soil-water-content.md).