Log inSuggest an edit

Clip images to AOI

"Clip and Ship" is a Planet service to clip satellite imagery to a user-defined geometry. The beta version of the service has an API endpoint at https://api.planet.com/compute/ops/clips/v1/ and allows for clipping one image at a time.

This guide will walk users through a common workflow for the "Clip and Ship" service, using both Planet Explorer and the Clips API interface. Users can consult the API reference for more technical details about the Clips API.

  1. Define an Area of Interest (AOI) and create a geojson geometry
  2. Identify the image you want to clip and its asset parameters
  3. Clip an image to a user-defined geometry
  4. Poll the Clips API for the status of the clip operation
  5. Download the clipped image and associated files

Requirements for this guide are:

  • $PL_API_KEY: Planet Data API key, stored as an environment variable
  • $CAS_URL: Clip and Ship API endpoint at https://api.planet.com/compute/ops/clips/v1/, stored as an environment variable
  • Area of Internest (AOI): user-defined area of interest, represented as a polygon in geojson format
  • Optional: jq, a command-line JSON processor

Step 1. Define an Area of Interest (AOI) and create a geojson geometry

The Clip and Ship service accepts a single AOI, represented by a polygon in geojson format. If your AOI is in another format, you can use a web service called geojson.io to convert it, or you can create a new AOI and export it as geojson. See below for an example AOI near Chico, California, created using geojson.io.

Step 2. Identify the image you want to clip and its asset parameters

Upload your AOI or draw a new AOI in Planet Explorer. Identify an intersecting image that you want to clip. Get the item_id, item_type, and asset_type for that image. In the example below, we selected one PlanetScope scene that contains our entire AOI.

Querying the Data API directly to filter and identify an image to clip

Users can query the Data API directly and follow the common workflows outlined in the reference documentation to search, filter, and identify the parameters for imagery of interest that intersects the AOI.

Step 3. Clip and image to a user-defined geometry

A note about Authentication The protected Clips API endpoint at https://api.planet.com/compute/ops/clips/v1/ requires that a client provide an API key with each request. For Basic HTTP Authentication, set the username field to the API key and leave the password field blank. The commands below assume the path to the endpoint is stored in an environment variable $CAS_URL.

curl -u $PL_API_KEY: -v $CAS_URL | jq
    

The full request to the Clip and Ship service must include the aoi, item_id, item_type, and asset_type parameters, and should be structured like this:

curl -u $PL_API_KEY: -X POST -H "Content-Type: application/json" $CAS_URL -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"
      }
    ]
}' | jq

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

 {
  "_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"
    }
  ]
}
    

Step 4. Poll the API to check the status of the operation

You can check the status of the operation by querying the API with the unique clip id via GET $CAS_URL/<id>.

For example,

curl -u $PL_API_KEY: $CAS_URL/dce3f314-3bf2-451a-aca0-1ad67f412bc9 | jq

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 and will return a download link in the results embedded in the json.

Step 5. Download the clipped item and associated files

When the clip is ready, the query will return a download URL.

{
  "_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>"
    ]
  }, 

You can download the bundle of clipped files -- in this case GeoTIFF and XML files -- by copying the results link in the json response and pasting it in a browser. Or you can issue a curl command to download the bundle to a zip file, like this:

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

The file is only available for five minutes. After that, the download token expires and you will have to fetch the clip again.

If you have any trouble with this guide, let us know at support@planet.com.