Log inSuggest an edit

Common Workflows for the Clips API

Table of Contents

  1. Getting started
  2. Clip an image to a user-defined geometry
  3. Poll the Clips API for the status of the clip operation
  4. Download a zipped file with the image and associated files

Getting started

Information about authentication, error messages, and rate limits for all Planet APIs can be found in the API Mechanics section of reference documentation. The "Clip and Ship" service adheres to the rate limit for operation endpoints: 5 requests per second, per API key. Users can refer to the common workflows for the Data API for tips on using the Data API to search, filter, and identify imagery of interest that intersects with their Area of Interest (AOI).

Clip a target image to a user-defined geometry

In the beta version of the "Clip and Ship" service, the following Planet Imagery Products are available to the clip operation:

ASSET_MAPPING = {
    'PSScene3Band': {
        'visual': 'visual,visual_xml',
        'analytic': 'analytic,analytic_xml,udm',
        'analytic_dn': 'analytic_dn,analytic_dn_xml,udm',
    },
    'PSScene4Band': {
        'visual': 'visual,visual_xml',
        'analytic': 'analytic,analytic_xml,udm',
        'analytic_dn': 'analytic_dn,analytic_dn_xml,udm',
    },
    'PSOrthoTile': {
        'visual': 'visual,visual_xml',
        'analytic': 'analytic,analytic_xml,udm',
        'analytic_dn': 'analytic_dn,analytic_dn_xml,udm',
    },
    'REOrthoTile': {
        'visual': 'visual,visual_xml',
        'analytic': 'analytic,analytic_xml,udm',
    },
}

When making clip requests to the Clips API, users must specify the following:

  • the geometry of their AOI as a geojson polygon object via the aoi parameter
  • their target image via the item_id, item_type, and asset_type parameters The POST request can be structured like this, with the Planet API key stored as environment variable $PL_API_KEY:
curl -X POST https://api.planet.com/compute/ops/clips/v1 -H "Content-Type: application/json" -d '{
    "aoi": {
                "type": "Polygon",
                "coordinates": [
                    [
                    [-122.04540252685548,39.630151307924194],
                    [-122.04591751098631,39.61640012616186],
                    [-122.11166381835936,39.589947866228904],
                    [-122.09793090820311,39.583730118967985],
                    [-122.07956314086915,39.582936323839206],
                    [-122.02136993408203,39.58240712203527],
                    [-121.98806762695311,39.6206315500488],
                    [-121.99304580688477,39.630151307924194],
                    [-122.04540252685548,39.630151307924194]

                    ]
                ]
            },
    "targets": [
      {
        "item_id": "20170423_180617_0f52",
        "item_type": "PSScene3Band",
        "asset_type": "visual"
      }
    ]
}' -u "$PL_API_KEY:"

The request will return a json response with a unique clip id for each clip operation executed.

 {
  "_links": {
    "_self": "https://api.planet.com/compute/ops/clips/v1/dce3f314-3bf2-451a-aca0-1ad67f412bc9",
    "results": null
  },
  "aoi": {
    "coordinates": [
      [
        [
          -122.04540252685548,
          39.630151307924194
        ],
        [
          -122.04591751098631,
          39.61640012616186
        ],
        [
          -122.11166381835936,
          39.589947866228904
        ],
        [
          -122.09793090820311,
          39.583730118967985
        ],
        [
          -122.07956314086915,
          39.582936323839206
        ],
        [
          -122.02136993408203,
          39.58240712203527
        ],
        [
          -121.98806762695311,
          39.6206315500488
        ],
        [
          -121.99304580688477,
          39.630151307924194
        ],
        [
          -122.04540252685548,
          39.630151307924194
        ]
      ]
    ],
    "type": "Polygon"
  },
  "created_on": "2017-05-08T14:30:28.676Z",
  "id": "dce3f314-3bf2-451a-aca0-1ad67f412bc9",
  "last_modified": "2017-05-08T14:30:28.676Z",
  "state": "running",
  "targets": [
    {
      "asset_type": "visual",
      "item_id": "20170423_180617_0f52",
      "item_type": "PSScene3Band"
    }
  ]
}
  

Poll the Clips API to check the status of the clip operation.

Users can check the status of the operation via a GET request to the Clips API using the unique clip id for the operation. For example,

curl https://api.planet.com/compute/ops/clips/v1/dce3f314-3bf2-451a-aca0-1ad67f412bc9 -u $PL_API_KEY:

While the clip operation is still running, the json response will show state: running. When the operation is complete, a query to the Clips API will indicate state: succeeded.

Download the zipped file with the clipped image and associated files

When the clip is ready, the query will return a download URL embedded in the json in results field.

{
  "_links": {
    "_self": "https://api.planet.com/compute/ops/clips/v1/dce3f314-3bf2-451a-aca0-1ad67f412bc9",
    "results": [
      "https://api.planet.com/data/v1/download?token=<very long string token>"
    ]
  }, 

Users can download a zipped file of the clipped image and metadata -- in this case GeoTIFF and XML files -- by copying the results link in the json response and pasting it in a web browser. Or users can issue a curl command to download the zipped files to a designated directory, like this:

curl -L “https://api.planet.com/data/v1/download?token=<>”\
 > path-to-image-directory/files.zip -u $PL_API_KEY: 

The token in the download URL will expire after five mintues.