About the Subscriptions API¶

The Subscriptions API supports select raster processing tools which can be applied to imagery before delivery to reduce time spent in data post-processing.

Note

The Planetary Variables for Soil Water Content (SWC), Land Surface Temperature (LST), and Crop Biomass (BIOMASS-PROXY) include raster assets. These rasters are clipped to the subscription's AOI and no additional tools are supported for Planetary Variables through the Subscriptions API.

Tools schema¶

The schema for Subscriptions API tools is below.

Note

This schema varies slightly different from the tools schema of the Orders API.

"tools": [
    {
        "type": "tool-name",
        "parameters": {
            "parameter-1-name": "p1-value",
            "parameter-2-name": "p2-value"
        }
    }
]

Creating toolchains¶

To derive insights or perform any meaningful analysis, it is highly likely that multiple tools will be required to process the data. You can push Planet data through individual or several of these tools chained together to achieve the results you need.

Planet processes tool requests synchronously in an order that has been validated against prior methodology. Given the changing output of each tool, certain processes necessarily go before others. Other tool chains are arbitrarily chosen based on the inputs or the effects on the output. For example, although not required, it’s recommended to run the clip tool before reproject and bandmath in order to reduce processing time. But, depending on the clip geometry, clipping before reprojecting may produce undesirable edge effects. In that case, you would clip before reproject.

When using multiple tools in a subscription, you must request tools in a specific order in the request body in order to ensure each tool succeeds. The required order of tools is as follows:

harmonize
toar
clip, reproject, bandmath (can go in any order)
cloud_filter, bandmath (must be after a clip)
file_format

If the array you provide does not follow the sequence above, a 400 error is returned clarifying which tool must be declared before another.

Toolchain example¶

In this example, the ortho-analytic product is manipulated by three tools in the series: TOAR --> Reproject --> File format.

TOAR, reproject, and file format¶

"tools": [
    {
        "type": "toar",
        "parameters": {**b2** (string): An expression defining how output band 2 should be computed. (optional)
            "scale_factor": 10000
        }
    },
    {
        "type": "reproject",
        "parameters": {
            "projection": "EPSG:3857",
            "kernel": "near"
        }
    },
    {
        "type": "file_format",
        "parameters": {
            "format": "COG"
        }
    }
]

Supported tools¶

Band Math¶

The bandmath tool allows you to apply band math expressions to the bands of your input files to produce derived outputs and indices for analysis. Popular indices include NDVI (Normalized Difference Vegetation Index), EVI (Enhanced Vegetation Index), and NDWI (Normalized Difference Water Index).

The bands of the input file are referenced as b1, b2, b3, etc., where b1 equals “band 1”. For each band expression, the bandmath tool supports normal arithmetic operations and simple math operators offered in the Python numpy package. (For a list of supported mathematical functions, see Bandmath supported numpy math routines.)

Product inputs¶

The bandmath tool supports PlanetScope, SkySat, and RapidEye except for those with non-orthorectified images (designated as basic_* assets).

Parameters¶

The parameters of the bandmath tool define how each output band in the derivative product should be produced, referencing the product inputs' original bands. Band math expressions may not reference neighboring pixels, as non-local operations are not supported. The tool can calculate up to 15 bands for an item. Input band parameters may not be skipped. For example, if the b4 parameter is provided, then b1, b2, and b3 parameters are also required.

b1 (string): An expression defining how output band 1 should be computed. (required)
b2 (string): An expression defining how output band 2 should be computed. (optional)
b3 (string): An expression defining how output band 2 should be computed. (optional)
b4 (string): An expression defining how output band 2 should be computed. (optional)
b5 (string): An expression defining how output band 2 should be computed. (optional)
pixel_type (string): A value indicating what the output pixel type should be. By default this value will be "Auto", the same as the input file. "8U" (8bit unsigned), "16U" (16bit unsigned), "16S" (16bit signed), and "32R" (32bit floating point) may also be used depending on the type of equation or index being calculated. (optional)

Example request

"tools": [
  {
    "type": "bandmath",
    "parameters": {
      "b1": "b1",
      "b2": "b2",
      "b3": "b3",
      "b4": "arctan(b1)",
      "b5": "(b4-b3)/(b4+b3)",
      "pixel_type": "32R"
    }
  }
]

The output of this tool is an asset that includes all four bands of the original file, a fourth band that is the arc tangent of the the original first band, and a fifth band with NDVI values.

Tool outputs¶

One bandmath imagery output file is produced for each product asset, with output bands derived from the band math expressions. nodata pixels are processed with the band math equation. These files have “_bandmath” appended to their file names.

The tool passes through UDM, RPC, and XML files, and does not update values in these files.

Clip¶

The clip tool allows you to clip a scene to a specified area of interest (polygon or multipolygon) to limit your storage costs. clip may also be used as a billing management tool, depending on the Raster Tools Plan you’ve purchased.

Product inputs¶

The clip tool supports all item types except SkySatVideo, TanagerScene, and TanagerMethane and all asset types except for non-orthorectified, basic_* asset types.

Tool outputs¶

Imagery and udm files will be clipped to your area of interest. nodata pixels will be preserved. Xml file attributes “filename”, “numRows”, “numColumns” and “footprint” will be updated based on the clip results.

The clipped output files will have “_clip” appended to their file names. If the clip aoi is so large that full scenes may be delivered without any clipping, those files will not have “_clip” appended to their file name.

For catalog subscriptions, the delivered item metadata JSON file will also be updated. The metadata geometry will reflect the footprint of the item clipped to the clip tool's area of interest. Similarly, the UDM2 metadata values such as clear_percent may be updated and relevant to the clipped area of interest. These UDM2 metadata values are only updated if a UDM2 asset is included in the subscription.

Note

There might be discrepancies between an item's footprint and the area of its usable pixels. When clipping, this can result in a clipped AOI which does not intersect with any usable pixels of an image. In this case, an imagery file will not be delivered while auxiliary assets will continue to be delivered.

Parameters¶

aoi (dict): GeoJSON polygon or multipolygon defining the clip area, with up to 1,500 vertices. The minimum geographic area of any polygon or internal ring is one square meter.

Example request

"tools": [
    {
        "type": "clip",
        "parameters": {
            "aoi": {
                "type": "Polygon",
                "coordinates": [
                    [
                        [
                            -163.828125,
                            -44.59046718130883
                        ],
                        [
                            181.7578125,
                            -44.59046718130883
                        ],
                        [
                            181.7578125,
                            78.42019327591201
                        ],
                        [
                            -163.828125,
                            78.42019327591201
                        ],
                        [
                            -163.828125,
                            -44.59046718130883
                        ]
                    ]
                ]
            }
        }
    }
]

AOI geometry limits¶

While clipping an AOI with GeoJson, users should be aware of multipolygon limitations for successful subscription creation. Notable validation changes are due to the python-geojson + python-shapely validation process and may result in your subscription being rejected. The following geometries are invalid and will result in the failure of a subscription request:

GeoJSON Polygons with holes first will be rejected.
GeoJSON Polygons with multiple exterior rings will be rejected.
GeoJSON MultiPolygons with overlapping/intersecting Polygons will be rejected. The GeoJSON spec technically allows this, but is generally invalid geometry in many programs (PostGIS, Shapely, QGIS to name a few).
GeoJSON containing more than 1,500 vertices will be rejected.
Clipping outside contract AOI may result in a rejected order.

Cloud Filter¶

The cloud_filter tool allows you to filter out imagery that exceeds your provided per Area of Interest (AOI) cloud cover metadata thresholds after the scene has been clipped with the clip tool. This allows for more granular filtering that is based on the clip AOI, instead of the metadata of the entire scene.

Note

Always use this tool after the clip tool.

Product inputs¶

The cloud_filter tool only supports item types with UDM2 assets. This excludes the TanagerScene, TanagerMethane, Sentinel2L1C, and Landsat8L1G item types.

Parameters¶

clear_percent (int [0-100]): Percent of clear values in the dataset. Clear values represent scene content areas (non-blackfilled) deemed to be not impacted by cloud, haze, shadow, or snow. (optional)
cloud_percent (int [0-100]): Percent of cloud values in the dataset. Cloud values represent scene content areas (non-blackfilled) that contain opaque clouds which prevent reliable interpretation of the land cover content. (optional)
heavy_haze_percent (int [0-100]): Planet's UDM2.1 product launched 11/29/2023 does not include a heavy haze classification. Any non-zero values for this field were generated by the previous UDM2.0 product prior to 11/29/2023. Under UDM2.0’s definition: Percent of heavy haze values in the dataset. Heavy haze values represent scene content areas (non-blackfilled) that contain thin low altitude clouds, higher altitude cirrus clouds, soot and dust which allow fair recognition of land cover features, but not having reliable interpretation of the radiometry or surface reflectance. (optional)
light_haze_percent (int [0-100]): Percent of haze values in the dataset. Haze values represent regions of a scene (non-blackfilled) with thin, filamentous clouds, soot, dust, and smoke. You can see ground objects through haze (optional)
shadow_percent (int [0-100]): Percent of shadow values in the dataset. Shadow values represent scene content areas (non-blackfilled) not fully exposed to the solar illumination as a result of atmospheric transmission losses due to cloud, haze, soot, and dust, and therefore do not allow for reliable interpretation of the radiometry or surface reflectance. (optional)
snow_ice_percent (int [0‑100]): Percent of snow and ice values in dataset. Snow_ice values represent scene content areas (non-blackfilled) that are hidden below snow or ice. (optional)

Note

Each parameter should have one or two comparators (lte or gte) and a value in the integer range as specified above. See example below.

Example

"tools": [
  {
    "type": "cloud_filter",
    "parameters": {
      "cloud_percent": {"lte": 20}
    }
  }
]

Tool outputs¶

If a scene is not filtered, it will be delivered as you would expect. If a scene is filtered, then delivery will not be made.

Filtered scenes will be returned in the api.planet.com/subscriptions/v1/{id}/results/ endpoint, as a result with no output, containing a "filtered" key in its properties block.

Example

{
    "_links": {
        "_self": "https://api.planet.com/subscriptions/v1/d31a3663-6ead-4e3d-bf53-0ea2ab856c66/results"
    },
    "results": [
        {
            "id": "e310e1e3-7205-4b3f-a75c-a55faf517845",
            "status": "success", <--- still successful though
            "properties": {
                "filtered": "cloud_filter", <--- filtered for this reason
                "item_id": "20201129_151145_42_222b",
                "item_types": [
                    "PSScene"
                ]
            },
            "created": "2023-09-27T17:43:30.132674Z",
            "updated": "2023-09-27T17:52:12.636226Z",
            "completed": "2023-09-27T17:52:12.636226Z",
            "errors": {},
            "outputs": [] 
        }
    ]
}

File Format¶

The file_format tool allows you to convert imagery to Cloud Optimized GeoTIFF (ideal for light-weight, web-based workflows) or NITF 2.1 formats.

Product inputs¶

The file_format tool supports all item types except for TanagerScene and TanagerMethane and all asset types except for those with NITF images (designated as *_nitf assets).

Parameters¶

format (enum): The format of the tool output. Currently, the tool supports two formats:
- "COG": This option produces a tiled Cloud Optimized GeoTIFF, with LZW compression and powers of two overviews. You can find more information at Cloud Optimized GeoTIFF.
- "PL_NITF": This option converts the output to the National Imagery Transmission Format 2.1 specification. Find out more about the NITF 2.1 Interface Standard. The NITF format only supports WGS84 geographic and UTM projections. If your imagery is in a different projection, use the Reproject tool first.

Example

"tools": [
  {
    "type": "file_format",
    "parameters": {
      "format": "COG"
    }
  }
]

Tool outputs¶

One formatted imagery output file is produced for each asset. These files have “_file_format” appended to their file names.

The tool passes through UDM and XML files, and does not update values in these files.

Harmonization¶

The harmonize tool allows you to radiometrically harmonize imagery captured by one satellite instrument type to imagery captured by another.

Parameters¶

target_sensor (string): A value indicating to what sensor the input asset types should be calibrated. Each sensor value transforms items captured by a defined set of instrument IDs. Items which have not been captured by that defined set of instrument IDs are unaffected by (passed through) the harmonization operation.

Target sensor options¶

Sentinel-2¶

PSScene surface reflectance assets from PlanetScope instrument types (PS2.SD and PSB.SD) can be harmonized to Sentinel-2.
With the Sentinel-2 target sensor, the tool harmonizes PSScene surface reflectance asset types (ortho_analytic_8b_sr, ortho_analytic_4b_sr) to Sentinel-2 bands (blue, green, red, and narrow near-infrared (NIR)).
This sensor type requires that the surface reflectance asset and the supplemental Ortho UDM2 and XML (i.e., ortho_analytic_4b_xml, ortho_analytic_8b_xml) assets are included when creating a subscription.
Read more about the harmonization to Sentinel-2 in Scene Level Normalization and Harmonization of Planet Dove Imagery.

Example request

"tools": [
  {
    "type": "harmonize",
    "parameters": {
      "target_sensor": "Sentinel-2"
    }
  }
]

Tool outputs¶

One imagery output file with harmonized band values is delivered for each asset type. The transformation of each item depends on the instrument used to capture that item and its relationship to the target sensor. Files which have been transformed have "_harmonize" appended to their file names.

The Harmonization tool passes through UDM, RPC, and XML files, and does not update values in these files.

Reproject¶

The reproject tool allows you to reproject and resample imagery products to a new projected coordinate system and resolution.

Product inputs¶

The reproject tool supports all item types except for TanagerScene and TanagerMethane and all asset types except for those with non-orthorectified images (basic_* assets).

Tool outputs¶

One imagery output file reprojected to the target configuration is produced for each product asset. Udm files are also reprojected to the target configuration. These file outputs will have “_reproject” appended to their file names.

Parameters¶

projection (string): A coordinate system in the form EPSG:n (for example, EPSG:4326 for WGS84, EPSG:32611 for UTM 11 North (WGS84), or EPSG:3857 for Web Mercator). Well known text CRS values are also supported (for example, WGS84).
resolution (float): The pixel width and height in the output file. If not provided, the default is the resolution of the input item. This value is in meters unless the coordinate system is geographic (such as EPSG:4326), in which case, it is pixel size in decimal degrees.
kernel (string): The resampling kernel used. If not provided, the default is "near". UDM files always use "near". This parameter also supports "bilinear", "cubic", "cubicspline", "lanczos", "average", "mode", "min", "max", "med", "q1", and "q3" (see the gdalwarp "resampling_method" docs for details).

Example

"tools": [
  {
    "type": "reproject",
    "parameters": {
      "projection": "EPSG:4326",
      "kernel": "near"
    }
  }
]

Top of Atmosphere Reflectance (TOAR)¶

The Top of Atmosphere Reflectance (TOAR) tool converts Analytic assets from top of atmosphere (TOA) radiance to a TOA scaled reflectance. The Subscriptions API TOAR tool is only applicable to Analytic assets, which represent TOA radiance. The tool converts the pixel values to a scaled reflectance, accounting for varying solar irradiance based on the distance to the sun and geometry of incoming solar radiation. The resulting product is a top of atmosphere reflectance value, no atmospheric correction is applied.

Product inputs¶

The toar tool supports the analytic asset type for PSScene and REOrthoTile item types. In addition to the asset type, the corresponding XML metadata asset type is required. Pairs of analytic and XML asset types are listed below:

ortho_analytic_4b, ortho_analytic_4b_xml
ortho_analytic_8b, ortho_analytic_8b_xml
analytic, analytic_xml

Parameters¶

scale_factor (integer): Scale factor applied to convert 0.0 to 1.0 reflectance floating point values to a value that fits in 16bit integer pixels. The default is 10000. Values over 65535 could result in high reflectances not fitting in 16bit integers.

Example

"tools": [
  {
    "type": "toar",
    "parameters": {
      "scale_factor": 10000
    }
  }
]

Tool outputs¶

One 16bit imagery output file, holding scaled reflectance values, produced for each analytic asset. These files have “_toar” appended to their file names. The tool also passes through the corresponding XML assets.

We are continually working to improve our technical documentation and support. Please help by sharing your experience with us.

Send Us Your Feedback

Tools

last updated: November 20, 2024

About the Subscriptions API¶

Tools schema¶

Creating toolchains¶

Toolchain example¶

TOAR, reproject, and file format¶

Supported tools¶

Band Math¶

Product inputs¶

Parameters¶

Tool outputs¶

Clip¶

Product inputs¶

Tool outputs¶

Parameters¶

AOI geometry limits¶

Cloud Filter¶

Product inputs¶

Parameters¶

Tool outputs¶

File Format¶

Product inputs¶

Parameters¶

Tool outputs¶

Harmonization¶

Parameters¶

Target sensor options¶

Sentinel-2¶

Tool outputs¶

Reproject¶

Product inputs¶

Tool outputs¶

Parameters¶

Top of Atmosphere Reflectance (TOAR)¶

Product inputs¶

Parameters¶

Tool outputs¶