Subscribing to Planetary Variables

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¶

Biomass Proxy 10m¶

Biomass Proxy 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 (10m x 10m). 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 Biomass Proxy Planetary Variables using the Subscriptions API.

Land Surface Temperature¶

Planet’s 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, 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 100m¶

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

Land Surface Temperature 1km¶

Satellite observed land surface temperature using multi-frequency microwave sensor technology and patented methodology. 1km 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 100m¶

Satellite observed volumetric soil water content at 100 meter resolution.

Soil Water Content 1km¶

Satellite observed volumetric soil water content at 1KM resolution.

Vegetation Optical Depth 1km¶

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.

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	Biomass Proxy 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-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.
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.

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"
}

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.
canceled: The subscription was canceled 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, Biomass Proxy, 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 Biomass Proxy 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: August 30, 2023

Product descriptions and identifiers¶

Biomass Proxy 10m¶

Land Surface Temperature¶

Land Surface Temperature 100m¶

Land Surface Temperature 1km¶

Soil Water Content¶

Soil Water Content 100m¶

Soil Water Content 1km¶

Vegetation Optical Depth 1km¶

Planetary Variables types and IDs¶

Metadata-only subscriptions¶

Create a Planetary Variables Subscription¶

Parameters¶

Example POST create new subscription request¶

Example Response¶

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¶