Tools & toolchains

last updated: June 13, 2022

Using tools

The API offers much more than just the ability to bulk order items. Using Tools, you can pre-process the data before it is delivered to you. An Order can have a single or a chain of tools applied to the raw imagery.

In this example, we show how to use the Clip tool. Clip basically crops the imagery to the provided boundary. The API payload can be read as: Activate 20170614_113217_3163208_RapidEye-5 analytic bundle and then clip the imagery to the specified AOI, and return download URL for the result.

Refer to the Tools Reference for detailed specs of available tools.

{
  "name": "just clip",
  "products": [
    {
      "item_ids": [
        "20170614_113217_3163208_RapidEye-5"
      ],
      "item_type": "REOrthoTile",
      "product_bundle": "analytic"
    }
  ],
  "tools": [
    {
      "clip": {
        "aoi": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                -163.828125,
                -44.59046718130883
              ],
              [
                181.7578125,
                -44.59046718130883
              ],
              [
                181.7578125,
                78.42019327591201
              ],
              [
                -163.828125,
                78.42019327591201
              ],
              [
                -163.828125,
                -44.59046718130883
              ]
            ]
          ]
        }
      }
    }
  ]
}

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. When using multiple tools in an order, the sequence of tools processed is as follows:

  • harmonize
  • toar
  • clip
  • reproject
  • bandmath
  • tile
  • file_format

Even if the array you provide does not follow the sequence above, the tool items are executed in the sequence above.

Toolchain example

In this example, the REOrthoTile analytic product is manipulated by three tools in series: TOAR --> Reproject --> Tile. See the Tools Reference section to determine which toolchains you can use today.

TOAR, Reproject, and Tile

{
  "name": "toar and reproject",
  "products": [
    {
      "item_ids": [
        "20170614_113217_3163208_RapidEye-5"
      ],
      "item_type": "REOrthoTile",
      "product_bundle": "analytic"
    }
  ],
  "tools": [
    {
      "toar": {
        "scale_factor": 10000
      }
    },
    {
      "reproject": {
        "projection": "WGS84",
        "kernel": "cubic"
      }
    },
    {
      "tile": {
        "tile_size": 1232,
        "origin_x": -180,
        "origin_y": -90,
        "pixel_size": 0.000027056277056,
        "name_template": "C1232_30_30_{tilex:04d}_{tiley:04d}"
      }
    }
  ]
}

Rate this guide: