Log inSuggest an edit

Download a subarea

This guide explains how to download a subarea of a Planet image, saving time, bandwidth and storage. We will use an exciting new feature of the GDAL library, VSI Curl, which queries a part of a GeoTIFF file using an HTTP Range request.

  1. Activate an image containing your AOI
  2. Create a GeoJSON file of your AOI
  3. Download only the AOI

You will need,

  • Python 2.7 or 3
  • GDAL 2.1.0+ - conda install gdal=2.1.0
  • requests - pip install requests
  • retrying - pip install retrying
  • Your Planet API Key in your environment:
export PL_API_KEY=a3a64774d30c4749826b6be445489d3b # (not a real key)

Planet Imagery Product Compatability: all ItemTypes & Asset Types.

Step 1. Activate a scene containing your Subarea

First, we will activate a scene of a stretch of agricultural land in Yuma, AZ, with the Planet API client.

planet data download --activate-only --item-type PSScene3Band --asset-type visual --string-in id 20161109_173041_0e0e --quiet

Activation will take ~8 minutes. Run the command above again until you see a URL in the 'location' element of the response.

A full-size Planet Scene of Agricultural land in Yuma, AZ

Step 2. Create a GeoJSON file of your Subarea

Define the geometry of the subarea you'd like to download in GeoJSON format, by drawing it at geojson.io:

Save the GeoJSON to a file e.g. subarea.geojson,

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type":"Polygon",
        "coordinates":[
          [
             [
                -114.176423930378903,
                32.691933554346988
             ],
             [
                -114.176423930378903,
                32.685249521402788
             ],
             [
                -114.168019741897595,
                32.685249521402788
             ],
             [
                -114.168019741897595,
                32.691933554346988
             ],
             [
                -114.176423930378903,
                32.691933554346988
             ]
          ]
        ]
      }
    }
  ]
}

Step 3. Download the Subarea

Next let's request a download URL for this image from the Planet Data API. Note, you must do this every time you wish to download your subarea, as these download URLs expire after 1 hour.

from osgeo import gdal
from requests.auth import HTTPBasicAuth
import os
import requests

item_id = "20161109_173041_0e0e"
item_type = "PSScene3Band"
asset_type = "visual"
item_url = 'https://api.planet.com/data/v1/item-types/{}/items/{}/assets'.format(item_type, item_id)

# Request a new download URL
result = requests.get(item_url, auth=HTTPBasicAuth(os.environ['PLANET_API_KEY'], ''))
download_url = result.json()[asset_type]['location']

Prefix the download URL with '/vsicurl/' to use the VSI Curl driver. Then call GDAL Warp, passing it an output file name, this URL, our subarea GeoJSON, a projection (in this case, the one used by GeoJSON.io), and 'cropToCutline = True'.

vsicurl_url = '/vsicurl/' + download_url
output_file = item_id + '_subarea.tif'

# GDAL Warp crops the image by our AOI, and saves it
gdal.Warp(output_file, vsicurl_url, dstSRS = 'EPSG:4326', cutlineDSName = 'subarea.geojson', cropToCutline = True)

Within a couple of seconds, you'll have an image of just the subarea in your directory.


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