Subscribing to Planetary Variables

last updated: April 04, 2024

Delivery of Planetary Variables through the Subscriptions API allows for automation, seamless integration, scalability, customization, and consistent access to the data, while reducing the data processing burden on your end.

With Subscriptions APIs, you can tailor the data request parameters to suit your specific needs, such as defining the area of interest, time range, and data frequency. This flexibility ensures that you receive the most relevant data for your use case.

Automation: Subscriptions APIs enable you to automate the process of acquiring Planetary Variables data for your area of interest. By setting up a subscription, you can receive the latest data automatically, without having to manually request it each time.

Integration: APIs are designed to be easily integrated into existing applications, tools, and workflows. By delivering Planetary Variables data through our API, it becomes straightforward to incorporate this valuable information into your current systems, enabling more informed decision-making and analysis.

Scalability: Planet’s Subscriptions API can handle the requests of Planetary Variables data for various scales, from small areas to large regions. This allows you to scale your monitoring and analysis efforts as needed, without being limited by data availability or processing capabilities.

Data Processing: Planet’s Subscriptions API provides a way to access aggregated time series data of Planetary Variables, via the results CSV and JSON endpoints avoiding the need for raster processing.

Product descriptions and identifiers¶

Crop Biomass 10 m¶

Crop Biomass is a fusion of microwave and optical satellite imagery, using the advantages of each to accurately estimate relative above-ground crop biomass regardless of cloud cover and at a high spatial resolution (10 m x 10 m). It integrates microwave data from the European Space Agency (ESA) Sentinel-1A satellites and optical images from its Sentinel-2 satellites. Planet then fuses the output from these combined data sources using an algorithm designed to provide a reliable measurement of crop biomass over agricultural areas under all circumstances. This is a relative measure of biomass, so each pixel value has a value of 0 (low biomass) to 1 (high biomass). The product is provided daily and near real time.

Review an example of subscribing to Crop Biomass Planetary Variables using the Subscriptions API.

Forest Carbon Diligence¶

The Forest Carbon Diligence product is composed of a bundle of data resources: Canopy Height, Canopy Cover, and Aboveground Live Carbon at 30-meter spatial resolution. These data resources are produced annually over the entire landmass of the Earth (between 75° N and S). We use an extensive library of airborne LiDAR to train deep learning models to predict canopy height and canopy cover from satellite imagery. We use these data along with additional data on basal area and wood density to estimate aboveground live carbon using regionally calibrated allometric equations.

The archive currently extends back to 2013 and is available through December 31, 2022.

Refer to this example of subscribing to Forest Carbon Diligence using the Subscriptions API.

Canopy Height 30 m¶

A measure of the height of woody vegetation from the ground to the top of the canopy (meters) in one meter increments. Includes pixel-level 95th and 5th percentile confidence intervals as a separate 2-band raster (CANOPY_HEIGHT_UNCERTAINTY_v1.0.0_30). Data type is UInt8 (Byte).

Canopy Cover 30 m¶

A measure of the horizontal area occupied by woody vegetation (percent) in one percent increments. Includes pixel-level 95th and 5th percentile confidence intervals as a separate 2-band raster (CANOPY_COVER_UNCERTAINTY_v1.0.0_30). Data type is UInt8 (Byte).

Aboveground Live Carbon 30 m¶

A measure of the carbon density (Mg/ha) contained in aboveground live woody vegetation in increments of one Mg/ha. Includes pixel-level 95th and 5th percentile confidence intervals as a separate 2-band raster (ABOVEGROUND_CARBON_DENSITY_UNCERTAINTY_v1.0.0_30). Data type is Int16.

Quality Assurance (QA) 30 m¶

A shared data resource for all “main” data resources above. Values 0-100 indicate the “quality” of the pixel selected for the surface reflectance mosaic, with higher numbers indicating higher quality pixels. Some pixels have no valid optical observations throughout the year. These have been back-filled/forward-filled with the nearest valid observation. Values 213-222 indicate the year that the filled value was sourced from (213 represents 2013, 216 represents 2016, etc.). File name is {METRIC}_QA-MASK_v1.0.0_03. Data type is UInt8 (Byte).

Day of Year 30 m¶

A shared data resource for all “main” data resources above. Day of year (Julian day) that the pixel was observed by satellite. Data type is UInt8 (Byte).

Land Surface Temperature¶

The Planet Land Surface Temperature product is a feed of high-resolution, globally available, twice-daily measurements of the temperature of the land’s surface, unhindered by clouds.

Its rich archive and spatial granularity enable more accurate data accounting for regional variations over time. The ability to provide cloud-free readings consistently allows organizations to gather better intelligence on a range of phenomena, from monitoring urban heat stress to optimized planting dates for crop production. In combination with other datasets, such as Soil Water Content and Land Surface Temperature, data can provide critical insights into the state of the environment.

Review an example of subscribing to Land Surface Temperature Planetary Variables using the Subscriptions API.

Land Surface Temperature 100 m¶

Satellite observed land surface temperature using multi-frequency microwave combined with infrared technology and patented methodology. 100 m resolution.

Land Surface Temperature 1 km¶

Satellite observed land surface temperature using multi-frequency microwave sensor technology and patented methodology. 1 km resolution.

Soil Water Content¶

Soil Water Content provides a measurement of soil moisture from the top of the soil across the globe using microwave data from multiple sources, including SMOS, SMAP, and AMSR-E. Planet’s proprietary algorithms combine these data sources to provide high-quality soil moisture data at high temporal and spatial resolution, unhindered by clouds or vegetation.

Review an example of subscribing to Soil Water Content Planetary Variables using the Subscriptions API.

Soil Water Content 100 m¶

Satellite observed volumetric soil water content at 100 meter resolution.

Soil Water Content 1 km¶

Satellite observed volumetric soil water content at 1 km resolution.

Vegetation Optical Depth 1 km¶

Satellite observed Vegetation Optical Depth using multi-frequency microwave sensor technology and patented methodology at 1km resolution. The Vegetation Optical Depth product quantifies the amount of vegetation in a given area by measuring the attenuation of light due to absorption and scattering caused by the vegetation. It has applications in agriculture, environmental monitoring, and land management.

Field Boundaries¶

Field Boundaries is an enabling Planetary Variable that provides critical infrastructure required to answer many of the larger scale questions about agriculture production.

They are the output of a process of automatically tracing the boundaries of agricultural parcels from satellite or aerial imagery. An agricultural parcel is a spatially homogeneous land unit used for agricultural purposes, where a single crop group is grown at a given point in time. The result of the process is field boundaries vector dataset. The data consists of a set of many closed vector polygons marking the extent of each agricultural parcel delivered as a GeoPackage.

An example workflow for creating a subscription to Field Boundaries can be found at Planetary Variables - Field Boundaries.

Field Boundaries Sentinel-2 P1M¶

Field Boundaries, computed on one month of Sentinel-2 data at 10m spatial resolution ("P1M" is a one-month duration as per ISO 8601 standard). Field Boundaries can be computed on any one month period from 2018 onwards.

Planetary Variables types and IDs¶

When your account is provisioned with Planetary Variables, you can find them in your account dashboard. The naming convention is based on grouping together all product types of Planetary Variable plus the resolution. So for example, if you have been provisioned with Soil Water Content Planetary Variables at 100 meters for Africa, you see a card in your dashboard that says SWC 100M in Africa. This means you have the ability to request and deliver through the Subscriptions API all three Soil Water Content 100M products: SWC-AMSR2-C_V1.0_100, SWC-AMSR2-X_V1.0_100, and SWC-SMAP-L_V1.0_100.

Source ID	Source Type	Description
BIOMASS-PROXY_V3.0_10	biomass_proxy	Crop Biomass V3.0 data product with a 10-meter spatial resolution. The available archive period is from January 1, 2019 to present.
LST-AMSR2_V1.0_100	land_surface_temperature	Land Surface Temperature data derived from the AMSR2 instrument, version 1.0, with a spatial resolution of 100 meters. The available archive period is from July 1, 2017 to present.
LST-AMSRE_V1.0_1000	land_surface_temperature	Land Surface Temperature data derived from the AMSR-E instrument, version 1.0, with a spatial resolution of 1 kilometer. The available archive period is from June 15, 2002 to October 04, 2011.
LST-AMSR2_V1.0_1000	land_surface_temperature	Land Surface Temperature data derived from the AMSR2 instrument, version 1.0, with a spatial resolution of 1 kilometer. The available archive period is from July 25, 2012 to present.
SWC-AMSR2-C_V1.0_100	soil_water_content	Soil Water Content data derived from the AMSR2 instrument in the C-band frequency range, with a spatial resolution of 100 meters. The available archive period is from July 1, 2017 to present.
SWC-AMSR2-X_V1.0_100	soil_water_content	Soil Water Content data derived from the AMSR2 instrument in the X-band frequency range, with a spatial resolution of 100 meters. The available archive period is from July 1, 2017 to present.
SWC-SMAP-L_V1.0_100	soil_water_content	Soil Water Content data derived from the SMAP mission using L-band radiometry, with a spatial resolution of 100 meters. The available archive period is from July 1, 2017 to present.
SWC-AMSR2-C_V2.0_100	soil_water_content	Soil Water Content data derived from the AMSR2 instrument in the C-band frequency range, with a spatial resolution of 100 meters. The available archive period is from July 1, 2017 to present.
SWC-AMSR2-X_V2.0_100	soil_water_content	Soil Water Content data derived from the AMSR2 instrument in the X-band frequency range, with a spatial resolution of 100 meters. The available archive period is from July 1, 2017 to present.
SWC-SMAP-L_V2.0_100	soil_water_content	Soil Water Content data derived from the SMAP mission using L-band radiometry, with a spatial resolution of 100 meters. The available archive period is from July 1, 2017 to present.
SWC-AMSRE-C_V4.0_1000	soil_water_content	Soil Water Content data derived from the AMSR-E instrument in the C-band frequency range, with a spatial resolution of 1 kilometer. The available archive period is from June 15, 2002 to October 04, 2011.
SWC-AMSRE-X_V4.0_1000	soil_water_content	Soil Water Content data derived from the AMSR-E instrument in the X-band frequency range, with a spatial resolution of 1 kilometer. The available archive period is from June 15, 2002 to October 04, 2011.
SWC-AMSR2-C_V4.0_1000	soil_water_content	Soil Water Content data derived from the AMSR2 instrument in the C-band frequency range, with a spatial resolution of 1 kilometer. The available archive period is from July 25, 2012 to present.
SWC-AMSR2-X_V4.0_1000	soil_water_content	Soil Water Content data derived from the AMSR2 instrument in the X-band frequency range, with a spatial resolution of 1 kilometer. The available archive period is from July 25, 2012 to present.
SWC-SMAP-L_V4.0_1000	soil_water_content	Soil Water Content data derived from the SMAP mission using L-band radiometry, with a spatial resolution of 1 kilometer. The available archive period is from April 1, 2015 to present.
SWC-AMSRE-C_V5.0_1000	soil_water_content	Soil Water Content data derived from the AMSR-E instrument in the C-band frequency range, with a spatial resolution of 1 kilometer. The available archive period is from June 15, 2002 to October 04, 2011.
SWC-AMSRE-X_V5.0_1000	soil_water_content	Soil Water Content data derived from the AMSR-E instrument in the X-band frequency range, with a spatial resolution of 1 kilometer. The available archive period is from June 15, 2002 to October 04, 2011.
SWC-AMSR2-C_V5.0_1000	soil_water_content	Soil Water Content data derived from the AMSR2 instrument in the C-band frequency range, with a spatial resolution of 1 kilometer. The available archive period is from July 25, 2012 to present.
SWC-AMSR2-X_V5.0_1000	soil_water_content	Soil Water Content data derived from the AMSR2 instrument in the X-band frequency range, with a spatial resolution of 1 kilometer. The available archive period is from July 25, 2012 to present.
SWC-SMAP-L_V5.0_1000	soil_water_content	Soil Water Content data derived from the SMAP mission using L-band radiometry, with a spatial resolution of 1 kilometer. The available archive period is from April 1, 2015 to present.
VOD-AMSRE-C_V4.0_1000	vegetation_optical_depth	Vegetation Optical Depth data derived from the AMSR-E satellite sensor on the Aqua satellite, with a "C" band frequency and a 1 kilometer spatial resolution. The available archive period is from June 15, 2002 to October 04, 2011.
VOD-AMSRE-X_V4.0_1000	vegetation_optical_depth	Vegetation Optical Depth data derived from the AMSR-E satellite sensor on the Aqua satellite, with an "X" band frequency and a 1 kilometer spatial resolution. The available archive period is from June 15, 2002 to October 04, 2011.
VOD-AMSR2-C_V4.0_1000	vegetation_optical_depth	Vegetation Optical Depth data derived from the Advanced Microwave Scanning Radiometer 2 (AMSR2) satellite sensor on the GCOM-W1 satellite, with a "C" band frequency and a 1 kilometer spatial resolution. The available archive period is from July 2017 to present.
VOD-AMSR2-X_V4.0_1000	vegetation_optical_depth	Vegetation Optical Depth data derived from the Advanced Microwave Scanning Radiometer 2 (AMSR2) satellite sensor on the GCOM-W1 satellite, with an "X" band frequency and a 1 kilometer spatial resolution. The available archive period is from July 25, 2012 to present.
VOD-SMAP-L_V4.0_1000	vegetation_optical_depth	Vegetation Optical Depth data derived from the SMAP mission using L-band radiometry, with a spatial resolution of 1 kilometer. The available archive period is from April 1, 2015 to present.
CANOPY_HEIGHT_v1.0.0_30	forest_carbon_diligence_30m	Height above ground in meters at 30 m spatial resolution, annual, archive to 2013 and is available through December 31, 2022.
CANOPY_COVER_v1.0.0_30	forest_carbon_diligence_30m	Percent canopy cover at 30 m spatial resolution, annual, archive to 2013 and is available through December 31, 2022.
ABOVEGROUND_CARBON_DENSITY_v1.0.0_30	forest_carbon_diligence_30m	Aboveground live carbon density (Mg/ha) at 30 m spatial resolution, annual, archive to 2013 and is available through December 31, 2022.
DAY_OF_YEAR_v1.0.0_30	forest_carbon_diligence_30m	Day of year (Julian day) pixel was observed by satellite at 30 m spatial resolution, annual, archive to 2013 and is available through December 31, 2022.
FIELD_BOUNDARIES_v1.0.0_S2_P1M	field_boundaries_sentinel_2_p1m	Field Boundaries, computed on one month of Sentinel-2 data at 10m spatial resolution ("P1M" is a one-month duration as per ISO 8601 standard). Field Boundaries can be computed on any one month period from 2018 onwards.

See a brief description of Sensors for Planetary Variables.

Metadata-only subscriptions¶

Raster delivery is optional for Planetary Variables subscriptions. Subscriptions created without delivery parameters are considered metadata-only subscriptions. This access pattern only applies to subscriptions for time series data; there is nothing to deliver for time series data. Simply omit delivery parameters when creating a new Planetary Variables subscription to create a metadata-only subscription. Note that time series data is available for all subscriptions with or without delivery configured.

Create a Planetary Variables Subscription¶

If you view the Subscriptions API specification to create a subscription, you see that creating a Planetary Variable subscription is similar to creating an Imagery subscription, but some things are different depending on the source you declare. If you want Planetary Variables, you specify a Planetary Variable source.

You can create a new Soil Water Content subscription by making a POST request to https://api.planet.com/subscriptions/v1. At minimum, the JSON payload on the request must specify required parameters:

Parameters¶

name: User-defined free text identifier for the subscription
source.type: Planetary Variables data product type
source.parameters.id: Planetary Variables data product identifier ("Source ID" in the table above)
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
delivery [optional]: Cloud storage location

Example POST create new subscription request¶

POST https://api.planet.com/subscriptions/v1
Content-Type: application/json
Basic Authorization: api-key {{apiKey}}

{
   "name": "Soil Moisture SWC-AMSR2-X_V4.0_1000 - SF",
   "source": {
       "type": "soil_water_content",
       "parameters": {
           "id": "SWC-AMSR2-X_V4.0_1000",
           "start_time": "2022-12-07T00:00:00Z",
           "end_time": "2022-12-16T00:00:00Z",
           "geometry": {
               "coordinates": [
                   [
                       [-122.52072063227817, 37.81322925468427],
                       [-122.52072063227817, 37.69640519175928],
                       [-122.35324889517493, 37.69640519175928],
                       [-122.35324889517493, 37.81322925468427],
                       [-122.52072063227817, 37.81322925468427]
                   ]
               ],
               "type": "Polygon"
           }
       }
   },
   "delivery": {
       "type": "google_cloud_storage",
       "parameters": {
           "bucket": "example-bucket",
           "credentials": "<REDACTED>"
       }
   }
}

Example Response¶

{
   "name": "Soil Moisture SWC-AMSR2-X_V4.0_1000 - SF",
   "source": {
       "type": "soil_water_content",
       "parameters": {
           "end_time": "2022-12-16T00:00:00Z",
           "geometry": {...},
           "id": "SWC-AMSR2-X_V4.0_1000",
           "start_time": "2022-12-07T00:00:00Z"
       }
   },
   "delivery": {
       "type": "google_cloud_storage",
       "parameters": {
           "bucket": "example-bucket",
           "credentials": "<REDACTED>"
       }
   },
   "created": "2023-04-11T18:19:38.096904Z",
   "_links": {
       "_self": "https://api.planet.com/subscriptions/v1/2aa224f7-59e8-4907-9232-b980054b024b"
   },
   "status": "preparing",
   "id": "2aa224f7-59e8-4907-9232-b980054b024b",
   "updated": "2023-04-11T18:19:38.096904Z"
}

Edit a Planetary Variables Subscription¶

Edit via `PUT` request¶

You can edit a subscription by submitting a full subscription request to the following endpoint:

PUT https://api.planet.com/subscriptions/v1/<subscription_id>

When a subscription is in a pending or running state, it may be edited with certain constraints. The following source block edits will be disallowed:

start_time: Cannot be modified.
end_time: Cannot be set to a time in the past (end_time < now()) and cannot be modified for subscriptions that are backfill-only.
geometry: Cannot be modified.
id: Source ID cannot be modified.

All other source filter criteria may be edited, as long as subscription does not surpass the limit on expected items delivered daily. These include:

end_time: May be modified if the subscription is in forwardfill (end_time > now()) and the subscription has not expired.

Additionally, outside of the source block, the following elements may also be edited:

name: May be modified.
delivery: May be modified.

The following elements may not be modified:

notifications: Cannot be modified.

Edit via `PATCH` request¶

You can edit certain subscription attributes by submitting a PATCH request:

PATCH https://api.planet.com/subscriptions/v1/<subscription_id>

Not all attributes can be edited this way, but they are subject to fewer restrictions than PUT requests. Importantly, the full subscription request body is not required and such requests are accepted regardless subscription state.

See the API reference for the full list of supported attributes.

Monitor a Planetary Variable Subscription¶

Looking now at the Subscriptions API specification to get a subscription, you can monitor your subscriptions by making a GET request to https://api.planet.com/subscriptions/v1. JSON response payloads will include a status field on the first dimension of each subscription, which indicates the state of a subscription’s lifecycle.

Subscription states¶

preparing: The subscription was successfully submitted and is being set up.
pending: The subscription's source start time has not yet passed; delivery has not yet started.
running: The subscription's source start time has passed and it is actively monitoring to deliver new Planetary Variables data as they become available; delivery may be in progress.
completed: The subscription's source end time has passed and all items are delivered; delivery has stopped.
cancelled: The subscription was cancelled by a user; delivery has stopped.
failed: There was an issue with the subscription.

Example GET all-subscriptions-owned-by-user request¶

You can request an array of all the different subscriptions by not specifying any path or query parameters.

Example GET¶

GET https://api.planet.com/subscriptions/v1/
Basic Authorization: api-key {{apiKey}}

Example Response¶

{
   "_links": {
       "_self": "https://api.planet.com/subscriptions/v1"
   },
   "subscriptions": [
       {
           "name": "Soil Moisture SWC-AMSR2-X_V4.0_1000 - SF",
           "source": {
               "type": "soil_water_content",
               "parameters": {
                   "end_time": "2022-12-16T00:00:00Z",
                   "geometry": {...},
                   "id": "SWC-AMSR2-X_V4.0_1000",
                   "start_time": "2022-12-07T00:00:00Z"
               }
           },
           "delivery": {
               "type": "google_cloud_storage",
               "parameters": {
                   "bucket": "example-bucket",
                   "credentials": "<REDACTED>"
               }
           },
           "created": "2023-04-11T18:19:38.096904Z",
           "_links": {
               "_self": "https://api.planet.com/subscriptions/v1/2aa224f7-59e8-4907-9232-b980054b024b"
           },
           "status": "completed",
           "id": "2aa224f7-59e8-4907-9232-b980054b024b",
           "updated": "2023-04-11T18:21:31.80108Z"
       },
       {...},
       {...},
       {...}
   ]
}

Example GET a single subscription request¶

Provide a subscriptions ID in the path to request metadata on a specific subscription.

Example GET¶

GET https://api.planet.com/subscriptions/v1/2aa224f7-59e8-4907-9232-b980054b024b
Basic Authorization: api-key {{apiKey}}

Example Response¶

{
   "name": "Soil Moisture SWC-AMSR2-X_V4.0_1000 - SF",
   "source": {
       "type": "soil_water_content",
       "parameters": {
           "end_time": "2022-12-16T00:00:00Z",
           "geometry": {...},
           "id": "SWC-AMSR2-X_V4.0_1000",
           "start_time": "2022-12-07T00:00:00Z"
       }
   },
   "delivery": {
       "type": "google_cloud_storage",
       "parameters": {
           "bucket": "example-bucket",
           "credentials": "<REDACTED>"
       }
   },
   "created": "2023-04-11T18:19:38.096904Z",
   "_links": {
       "_self": "https://api.planet.com/subscriptions/v1/2aa224f7-59e8-4907-9232-b980054b024b"
   },
   "status": "completed",
   "id": "2aa224f7-59e8-4907-9232-b980054b024b",
   "updated": "2023-04-11T18:21:31.80108Z"
}

Example GET a filter-by status request¶

To get a filtered array of subscriptions by state of lifecycle, request with a status query parameter.

Example GET¶

GET https://api.planet.com/subscriptions/v1?status=running
Basic Authorization: api-key {{apiKey}}

Example Response¶

{
    "_links": {
        "_self": "https://api.planet.com/subscriptions/v1?status=running"
    },
    "subscriptions": [
        {
            "name": "Soil Moisture SWC-AMSR2-X_V4.0_1000 - SF",
            "source": {
                "type": "soil_water_content",
                "parameters": {
                    "geometry": {...},
                    "id": "SWC-AMSR2-X_V4.0_1000",
                    "start_time": "2022-12-07T00:00:00Z"
                }
            },
            "delivery": {
                "type": "google_cloud_storage",
                "parameters": {
                    "bucket": "example-bucket",
                    "credentials": "<REDACTED>"
                }
            },
            "created": "2023-04-05T17:20:44.569948Z",
            "_links": {
                "_self": "https://api.planet.com/subscriptions/v1/db406042-b990-4fc7-8983-9e2123f4dbc8"
            },
            "status": "running",
            "id": "db406042-b990-4fc7-8983-9e2123f4dbc8",
            "updated": "2023-04-05T17:20:56.42878Z"
        },
       {...},
       {...},
       {...}
    ]
}

Get Planetary Variables subscription results¶

A result for a Planetary Variable source type subscription represents an attempt to process and deliver an item that matches your subscription criteria. You can get a paginated list of your subscription's results.

Access results of a subscription by making a GET request to https://api.planet.com/subscriptions/v1/<SUBSCRIPTION_ID>/results. Response payloads include a list of all of the subscription’s results, persisted for the lifetime of a subscription (from completion), plus 90 days. By default this endpoint responds with a JSON payload, but you can request a CSV response via optional query parameter ?format=csv, as in https://api.planet.com/subscriptions/v1/<SUBSCRIPTION_ID>/results?format=csv. Pagination is only supported for JSON requests; it is not supported for CSV requests.

Raster Results¶

Soil Water Content, Land Surface Temperature, Crop Biomass, and Vegetation Optical Depth include raster assets. All rasters are clipped to the subscription’s AOI and no additional tools are supported. An item will always be published, even for days where no upstream data is available. This produces an empty raster and the quality flags asset will include nodata for all pixels. Except for Crop Biomass which does not produce empty rasters because it is a daily product.

Soil Water Content and Land Surface Temperature are tile-based data products.

Note

If upstream data becomes available after an empty raster is produced, subscriptions which already received empty rasters will not be updated. In this case new subscriptions created after upstream data is available may receive usable data where old subscriptions may not have.

Metadata Results (Time Series)¶

For customers that only want to receive aggregated statistical data, Planetary Variables subscriptions do not require cloud delivery of rasters files. They can be metadata-only. Results metadata statistics (time series data) include two statistics:

valid_percent: Integer from 0 - 100
mean: Floating point with two fractional digits (these are digits after decimal point)

NaN rasters from days with no coverage have associated zero, or null, metadata statistics.

Note

metadata.json files as seen in imagery subscriptions are not generated or delivered for Planetary Variable subscriptions.

Quality Flag Asset Results¶

Soil Water Content, Land Surface Temperature, and Vegetation Optical Depth include quality flag assets that supply additional information about things like data issues, data usage, and overall quality. Quality flag assets are distinguished from raster assets via -qf postfix on the product ID, as in [product]-[datetime]_[product-abbreviation]-qf.tiff. Vegetation Optical Depth uses the same flag as the corresponding soil water content product.

{
  "completed": "2023-04-19T06:52:25.86372Z",
  "created": "2023-04-19T06:49:44.403053Z",
  "errors": {},
  "id": "[subscription ID]",
  "item_datetime": "2022-12-15T01:30:00Z",
  "outputs": [
    "[subscription ID]/2022/12/15]/SWC-AMSR2-X_V4.0_1000-20221215T0130_swc-qf.tiff",
    "[subscription ID]/2022/12/15]/SWC-AMSR2-X_V4.0_1000-20221215T0130_swc.tiff"
  ],
  "properties": {...},
  "status": "success",
  "updated": "2023-04-19T06:52:25.86372Z"
}

Flag types¶

Planetary Variables data comes with three possible types of flags:

static flags: Areas based on static features such as terrain slope.
critical flags: Indicate data that is not to be used. We replace the data with a missing value. When retrieving data products you can access the original data by looking at the second band in the GeoTIFF files. All values in the flag file > 127 are critical.
non-critical flags: Data can be used with caution, taking into account the information given in the flag. The Data is shown as normal in the viewer and stored similarly to non-flagged data in the GeoTIFF files. All values in the flag file <= 127 are non-critical.

Examples¶

Example GET Results Metadata Request (JSON)¶

Request the results endpoint to consume subscriptions results metadata with default JSON format.

GET https://api.planet.com/subscriptions/v1/2aa224f7-59e8-4907-9232-b980054b024b/results
Basic Authorization: api-key {{apiKey}}

Example Response¶

{
   "_links": {
       "_self": "https://api.planet.com/subscriptions/v1/2aa224f7-59e8-4907-9232-b980054b024b/results"
   },
   "results": [
       {
           "id": "d3eede31-da38-44f4-b3f2-ce8d84868f17",
           "status": "success",
           "properties": {
               "item_id": "SWC-AMSR2-X_V4.0_1000_2022-12-14T0130",
               "local_solar_time": "2022-12-14T01:30",
               "source_id": "SWC-AMSR2-X_V4.0_1000",
               "statistics": [
                   {
                       "asset": "swc",
                       "band": "band-1",
                       "name": "mean",
                       "type": "number",
                       "value": 0.29
                   },
                   {
                       "asset": "swc",
                       "band": "band-1",
                       "name": "valid_percent",
                       "type": "number",
                       "value": 59
                   }
               ]
           },
           "created": "2023-04-11T18:20:00.681444Z",
           "updated": "2023-04-11T18:20:55.580542Z",
           "completed": "2023-04-11T18:20:55.580542Z",
           "errors": {},
           "outputs": [
               "2aa224f7-59e8-4907-9232-b980054b024b/2022/12/14/SWC-AMSR2-X_V4.0_1000-20221214T0130_swc.tiff",
               "2aa224f7-59e8-4907-9232-b980054b024b/2022/12/14/SWC-AMSR2-X_V4.0_1000-20221214T0130_swc-qf.tiff"
           ],
           "item_datetime": "2022-12-14T09:30:00Z"
       },
       {},
       {},
       {}
   ]
}

Example correlating QF pixels with LST pixels¶

This script demonstrates how to process a QF raster, filter for flagged pixels, and then inspect those flagged pixels in the LST raster. Note that the LST rasters have two bands. The first band includes a value add that replaces critically flagged pixels with a no data value. The second band is the original data. My example script then would likely be most useful for a user who is interested in filtering on non-critical pixels in band one of the LST raster (because these are not replaced with a no data value).

from random import randint

import numpy as np
import rasterio

LST_TIFF = "LST-AMSR2_V1.0_1000-20230506T1330_lst.tiff"
QF_TIFF = "LST-AMSR2_V1.0_1000-20230506T1330_lst-qf.tiff"

def read_raster(file, band):
    '''
    Reads the first band of a raster data file into memory.

    Parameters:
        file (str): System file path to raster data file
        band (int): Band of imagery to read

    Returns:
        raster (numpy.ndarray): Numpy array representation of raster values
    '''

    with rasterio.open(file) as data:
        raster = data.read(band)
        return raster

def filter_quality_flags_xy(raster):
    '''
    Filters raster array for quality flag values (i.e. values greater than '0') and
    their x/y position in the raster.  All values in the flag file > 127 are critical.
    All values in the flag file <= 127 are non-critical.

    Parameters:
        raster (numpy.ndarray): Numpy array representation of raster values

    Returns:
        quality_flags_xy (array[QualityFlagXY(x (int), y (int), qf (int))]): Array of
            quality flags values and their x/y position in the raster
    '''

    class QualityFlagXY:
        def __init__(self, x, y, qf):
            self.x = x
            self.y = y
            self.qf = qf

    quality_flags_xy = []
    xy = np.where(raster > 0)
    for i in range(len(xy[0])):
        x = xy[0][i]
        y = xy[1][i]
        quality_flags_xy.append(
            QualityFlagXY(
                x = x,
                y = y,
                qf = raster[x][y]
            )
        )
    return quality_flags_xy

if __name__ == "__main__":
    # Read land surface temperature quality flag raster
    qf_raster = read_raster(QF_TIFF, 1)

    # Filter for x/y pixel positions of quality flags in the raster
    qf_xy = filter_quality_flags_xy(qf_raster)

    # Pick a flagged pixel at random (for demonstration)
    qf_pixel = qf_xy[randint(0, len(qf_xy))]

    # Read band 1 of land surface temperature raster - band 1 pixels
    # flagged as critical are replaced with a no data value
    lst_raster_band_1 = read_raster(LST_TIFF, 1)

    # Get flagged pixel from band 1 of land surface temperature raster
    band_1_pixel = lst_raster_band_1[qf_pixel.x][qf_pixel.y]

    # Print results!
    print("=================================================")
    print(f"LST TIFF:                {LST_TIFF} Band 1")
    print(f"QF pixel x/y:            {qf_pixel.x}, {qf_pixel.y}")
    print(f"QF value:                {qf_pixel.qf}")
    print(f"Flagged LST pixel value: {band_1_pixel}")
    print("=================================================\n")

    # Read band 2 of land surface temperature raster - band 2 contains
    # original pixels regardless of whether or not they are flagged
    lst_raster_band_2 = read_raster(LST_TIFF, 2)

    # Get flagged pixel from band 2 of land surface temperature raster
    band_2_pixel = lst_raster_band_2[qf_pixel.x][qf_pixel.y]

    # Print results!
    print("=================================================")
    print(f"LST TIFF:                {LST_TIFF} Band 2")
    print(f"QF pixel x/y:            {qf_pixel.x}, {qf_pixel.y}")
    print(f"QF value:                {qf_pixel.qf}")
    print(f"Flagged LST pixel value: {band_2_pixel}")
    print("=================================================\n")

Example GET Results Metadata Request (CSV)¶

Request the results endpoint to consume subscriptions results metadata with CSV format.

GET https://api.planet.com/subscriptions/v1/eed83494-b291-498e-bce7-0cd35cb1b0ca/results?format=csv
Basic Authorization: api-key {{apiKey}}

Example Response¶

id,item_datetime,status,created,updated,errors,bp.band-1.mean,bp.band-1.valid_percent,item_id,local_solar_time,source_id
...
0dc975f6-89c9-4ea6-9ebc-43c14c21cb13,2020-06-26T06:00:00Z,SUCCESS,2023-05-17T02:12:29.590891Z,2023-05-17T02:12:29.590891Z,{},0.37,100,BIOMASS-PROXY_V3.0_10_2020-06-26T0000,2020-06-26T00:00,BIOMASS-PROXY_V3.0_10
8f5c4840-9bc0-43da-85f4-69c6f00529fe,2020-06-27T06:00:00Z,SUCCESS,2023-05-17T02:12:30.83867Z,2023-05-17T02:12:30.83867Z,{},0.39,100,BIOMASS-PROXY_V3.0_10_2020-06-27T0000,2020-06-27T00:00,BIOMASS-PROXY_V3.0_10
3e7e8db1-261a-4505-a2fe-2a2afa84a7e1,2020-06-28T06:00:00Z,SUCCESS,2023-05-17T02:12:31.834162Z,2023-05-17T02:12:31.834162Z,{},0.41,100,BIOMASS-PROXY_V3.0_10_2020-06-28T0000,2020-06-28T00:00,BIOMASS-PROXY_V3.0_10
9775597c-dae9-459c-a5f0-f677a62d1f6c,2020-06-29T06:00:00Z,SUCCESS,2023-05-17T02:12:32.888926Z,2023-05-17T02:12:32.888926Z,{},0.43,100,BIOMASS-PROXY_V3.0_10_2020-06-29T0000,2020-06-29T00:00,BIOMASS-PROXY_V3.0_10
...

Example GET Results Metadata Filter On item_datetime Request (CSV)¶

Request the results endpoint to consume subscriptions results metadata with CSV format and filter on item_datetime.

GET https://api.planet.com/subscriptions/v1/eed83494-b291-498e-bce7-0cd35cb1b0ca/results?format=csv&item_datetime=2020-06-28T06:00:00Z
Basic Authorization: api-key {{apiKey}}

Example Response¶

id,item_datetime,status,created,updated,errors,bp.band-1.mean,bp.band-1.valid_percent,item_id,local_solar_time,source_id
3e7e8db1-261a-4505-a2fe-2a2afa84a7e1,2020-06-28T06:00:00Z,SUCCESS,2023-05-17T02:12:31.834162Z,2023-05-17T02:12:31.834162Z,{},0.41,100,BIOMASS-PROXY_V3.0_10_2020-06-28T0000,2020-06-28T00:00,BIOMASS-PROXY_V3.0_10

Example GET Results Metadata Filter On source_type Request (CSV)¶

You can get a list of all subscriptions of a specific source_type, for example:

?source_type=biomass_proxy
?source_type=soil_water_content&source_type=land_surface_temperature

The following call returns all of your Soil Water Content and all of your Land Surface Temperature Subscriptions.

GET https://api.planet.com/subscriptions/v1/results?format=csv&source_type=soil_water_content&source_type=land_surface_temperature
Basic Authorization: api-key {{apiKey}}

Example Response¶

{
    "_links": {
        "_self": "https://api.planet.com/subscriptions/v1?source_type=soil_water_content&source_type=land_surface_temperature",
        "next": "https://api.planet.com/subscriptions/v1?page_marker=2023-05-06T21%3A09%3A31.011874Z&source_type=soil_water_content&source_type=land_surface_temperature"
    },
    "subscriptions": [
        {
            "name": "Phoenix, AZ 5 yrs LST-AMSR2_V1.0_100",
            "source": {
                "type": "land_surface_temperature",
                "parameters": {
                    "end_time": "2023-05-15T00:00:00Z",
                    "geometry": {...},
                    "id": "LST-AMSR2_V1.0_100",
                    "start_time": "2019-05-15T00:00:00Z"
                }
            },
            "delivery": {
                "type": "google_cloud_storage",
                "parameters": {
                    "bucket": "gcs-bucket",
                    "credentials": "<REDACTED>"
                }
            },
            "created": "2023-05-18T22:32:58.321561Z",
            "_links": {
                "_self": "https://api.planet.com/subscriptions/v1/[subscription ID]"
            },
            "status": "running",
            "id": "[subscription ID]",
            "updated": "2023-05-18T22:34:05.643347Z"
        },
        {
            "name": "Horn of Africa 10 yrs SWC-AMSR2-C_V4.0_1000",
            "source": {
                "type": "soil_water_content",
                "parameters": {
                    "end_time": "2023-05-15T00:00:00Z",
                    "geometry": {...},
                    "id": "SWC-AMSR2-C_V4.0_1000",
                    "start_time": "2013-05-15T00:00:00Z"
                }
            },
            "created": "2023-05-12T18:52:36.696783Z",
            "_links": {
                "_self": "https://api.planet.com/subscriptions/v1/[subscription ID]"
            },
            "status": "cancelled",
            "id": "[subscription ID]",
            "updated": "2023-05-12T18:53:58.235672Z"
        },
        {
            "name": "Horn of Africa SWC-AMSR2-C_V4.0_1000",
            "source": {
                "type": "soil_water_content",
                "parameters": {
                    "end_time": "2023-05-15T00:00:00Z",
                    "geometry": {...},
                    "id": "SWC-AMSR2-C_V4.0_1000",
                    "start_time": "2022-05-15T00:00:00Z"
                }
            },
            "created": "2023-05-12T17:36:03.382816Z",
            "_links": {
                "_self": "https://api.planet.com/subscriptions/v1/[subscription ID]"
            },
            "status": "completed",
            "id": "[subscription ID]",
            "updated": "2023-05-15T00:00:18.111201Z"
        }
        .
        .
        .
    ]
}

Sensors for Planetary Variables¶

AMSR¶

AMSR2 and AMSR-E are two different instruments within the AMSR series:

JAXA AMSR2 (Advanced Microwave Scanning Radiometer 2) is an instrument on board the Global Change Observation Mission - Water (GCOM-W) satellite, which was launched by the Japan Aerospace Exploration Agency (JAXA). AMSR2 is designed to provide improved measurements of land, ocean, and atmospheric parameters.
NASA AMSR-E (Advanced Microwave Scanning Radiometer for EOS) is an instrument on board the Earth Observing System (EOS) Aqua satellite. AMSRE was developed by JAXA in collaboration with NASA. The instrument provided data for studying Earth's water cycle, climate, and related processes.

NASA SMAP¶

SMAP stands for Soil Moisture Active Passive. It is a NASA Earth observation satellite mission. The radar active sensor on this project failed within months of going into operation.

ESA Sentinel¶

Sentinel-1A Sentinel-1A is a satellite from the European Space Agency (ESA) that carries a C-band Synthetic Aperture Radar (SAR) instrument, allowing for all-weather, day-and-night imaging of the Earth's surface. The mission is designed to provide a variety of applications, including monitoring sea ice, maritime surveillance, monitoring land use, and mapping land surfaces for applications such as forestry, agriculture, and land cover classification. Sentinel-1A data is freely available and provides frequent revisits over the same area, making it a valuable tool for monitoring environmental changes.
Sentinel-2 Sentinel-2 is another mission from ESA's Copernicus program that carries a multispectral imaging instrument with a swath width of 290 km, designed to provide high-resolution (up to 10 meters) imagery of the Earth's surface. The mission comprises two identical satellites that together provide a revisit time of five days at the equator. Sentinel-2's capabilities enable it to provide a wide range of applications, including land cover mapping, monitoring vegetation health and changes, and assessing water quality. The mission's data is freely available and has already contributed to various scientific studies and applications, such as mapping urban areas, detecting crop stress, and monitoring wildfires.

Radio frequencies bands¶

L-band¶

L-band is a range of radio frequencies typically defined as 1 to 2 GHz. L-band radiometers are used in Planetary Variables to measure soil moisture and vegetation water content. The L-band frequency range is particularly well-suited for passive microwave remote sensing applications, as it allows for the detection of microwave radiation emitted by the Earth's surface and atmosphere, which is influenced by the amount of moisture present in the soil and vegetation.

C-band¶

C-band is a range of radio frequencies typically defined as 4 to 8 GHz. The C-band frequency range is well-suited for measuring a variety of environmental variables, including soil moisture and vegetation biomass.

X-band¶

X-band is a range of radio frequencies typically defined as 8 to 12 GHz. It is well-suited for measuring a variety of environmental variables, including soil moisture, vegetation biomass, and changes in the Earth's surface topography.

Rate this guide:

Subscribing to Planetary Variables

last updated: April 04, 2024

Product descriptions and identifiers¶

Crop Biomass 10 m¶

Forest Carbon Diligence¶

Canopy Height 30 m¶

Canopy Cover 30 m¶

Aboveground Live Carbon 30 m¶

Quality Assurance (QA) 30 m¶

Day of Year 30 m¶

Land Surface Temperature¶

Land Surface Temperature 100 m¶

Land Surface Temperature 1 km¶

Soil Water Content¶

Soil Water Content 100 m¶

Soil Water Content 1 km¶

Vegetation Optical Depth 1 km¶

Field Boundaries¶

Field Boundaries Sentinel-2 P1M¶

Planetary Variables types and IDs¶

Metadata-only subscriptions¶

Create a Planetary Variables Subscription¶

Parameters¶

Example POST create new subscription request¶

Example Response¶

Edit a Planetary Variables Subscription¶

Edit via PUT request¶

Edit via PATCH request¶

Monitor a Planetary Variable Subscription¶

Subscription states¶

Example GET all-subscriptions-owned-by-user request¶

Example GET¶

Example Response¶

Example GET a single subscription request¶

Example GET¶

Example Response¶

Example GET a filter-by status request¶

Example GET¶

Example Response¶

Get Planetary Variables subscription results¶

Raster Results¶

Metadata Results (Time Series)¶

Quality Flag Asset Results¶

Flag types¶

Examples¶

Example GET Results Metadata Request (JSON)¶

Example Response¶

Example correlating QF pixels with LST pixels¶

Example GET Results Metadata Request (CSV)¶

Example Response¶

Example GET Results Metadata Filter On item_datetime Request (CSV)¶

Example Response¶

Example GET Results Metadata Filter On source_type Request (CSV)¶

Example Response¶

Sensors for Planetary Variables¶

AMSR¶

NASA SMAP¶

ESA Sentinel¶

Radio frequencies bands¶

L-band¶

C-band¶

X-band¶

Edit via `PUT` request¶

Edit via `PATCH` request¶