Downloading Imagery with Data API

Overview¶

This API Quickstart Guide will walk you through how to download your first image from the Planet Data API. See guide "Getting Started" guide for instructions on using this guide and acquiring a Planet API key. See Step 1: Searching for Imagery for a guide to searching for images in the Planet API.

Downloading a large amount of imagery from our API can be tricky, when you're done with this tutorial you may want to check out: Large AOI Best Practices.

Accessing a Single Item¶

In the last section, we learned how to search for items that interest us.

Items are identified by their ItemType and ItemId, here is one of the items from our Guide to Searching for Imagery.

ItemType: REOrthoTile
ItemId: 20160707_195147_1057916_RapidEye-1

An easy way to visualize this item before we download it would be to extract its geometry coordinates and view its footprint in geojson.io:

curl -L -H "Authorization: api-key $PL_API_KEY" \
    'https://api.planet.com/data/v1/item-types/REOrthoTile/items/20160707_195147_1057916_RapidEye-1' \
    | jq '.geometry' | geojsonio

Asset Types¶

In general, a single satellite image can be provided in many different formats for different use cases. Some users might want color corrected products that can be viewed on the web, some might want raw image data for scientific purposes.

In the Planet Data API, these different item options are called Assets and items usually have multiple asset types.

We can see what asset types are availiable for a certain item by adding /assets to the item url.

curl -L -H "Authorization: api-key $PL_API_KEY" \
    'https://api.planet.com/data/v1/item-types/REOrthoTile/items/20160707_195147_1057916_RapidEye-1/assets' \
    | jq 'keys'
[
  "analytic",
  "analytic_xml",
  "udm",
  "visual",
  "visual_xml"
]

Asset Activation¶

An important thing to know about the API is that it does not pre-generate Assets so they are not always immediately availiable to download.

You can see that the visual asset for this item has the status "inactive", so we need to activate it.

curl -L -H "Authorization: api-key $PL_API_KEY" \
    'https://api.planet.com/data/v1/item-types/REOrthoTile/items/20160707_195147_1057916_RapidEye-1/assets/' \
    | jq .visual.status
"inactive"

Depending on the amount of Assets you want to activate, the activation step can take time to complete. A best practice is to activate your desired items and then periodically check the status until it becomes "active".

In practice, you will probably need to activate several assets at a time. But for now, let's just activate one:

examples/activation.py

import os
import requests

item_id = "20160707_195147_1057916_RapidEye-1"
item_type = "REOrthoTile"
asset_type = "visual"

# setup auth
session = requests.Session()
session.auth = (os.environ['PL_API_KEY'], '')

# request an item
item = \
  session.get(
    ("https://api.planet.com/data/v1/item-types/" +
    "{}/items/{}/assets/").format(item_type, item_id))

# extract the activation url from the item for the desired asset
item_activation_url = item.json()[asset_type]["_links"]["activate"]

# request activation
response = session.post(item_activation_url)

print response.status_code

➜  python examples/activation.py
204 # HTTP 204: Success, No Content to show

Asset Downloading¶

Let's check on our asset

➜  curl -L -H "Authorization: api-key $PL_API_KEY" \
    'https://api.planet.com/data/v1/item-types/REOrthoTile/items/20160707_195147_1057916_RapidEye-1/assets/' \
    | jq .visual.status
"active" # perfect

Now that the visual asset is active, we can finally get to the good stuff, downloading the image. When an asset is active the direct link to download is present on the asset object in the "location" field:

➜  curl -L -H "Authorization: api-key $PL_API_KEY" \
    'https://api.planet.com/data/v1/item-types/REOrthoTile/items/20160707_195147_1057916_RapidEye-1/assets/' \
    | jq .visual.location

"https://api.planet.com/data/v1/download?token=eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJwUDNCNU9aYVFKUnN2WGsydmF3UVpLL2ZWci9DZWk0bG82OGJuT2NRR2laZ01EcFBTUnpsSWdHNGlZM2R5YTZWQ2xHdDROeFBka29Kb295a1BvdktPUT09IiwiaXRlbV90eXBlX2lkIjoiUkVPcnRob1RpbGUiLCJ0b2tlbl90eXBlIjoidHlwZWQtaXRlbSIsImV4cCI6MTQ3Mzc1MDczOCwiaXRlbV9pZCI6IjIwMTYwNzA3XzE5NTE0N18xMDU3OTE2X1JhcGlkRXllLTEiLCJhc3NldF90eXBlIjoidmlzdWFsIn0.lhRgqIggvnRoCgUVX3hgaNYDQIdU09wVaImxv3a_vuGjfzC7_OteYeViboeiZYBH2_eMdWT5ZWDz2BZiAWkXlQ"

You can CURL that direct link or copy it into a web browser to download the image.

➜  curl -L -H "Authorization: api-key $PL_API_KEY" \
    'https://api.planet.com/data/v1/download?token=eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJwUDNCNU9aYVFKUnN2WGsydmF3UVpLL2ZWci9DZWk0bG82OGJuT2NRR2laZ01EcFBTUnpsSWdHNGlZM2R5YTZWQ2xHdDROeFBka29Kb295a1BvdktPUT09IiwiaXRlbV90eXBlX2lkIjoiUkVPcnRob1RpbGUiLCJ0b2tlbl90eXBlIjoidHlwZWQtaXRlbSIsImV4cCI6MTQ3Mzc1MDczOCwiaXRlbV9pZCI6IjIwMTYwNzA3XzE5NTE0N18xMDU3OTE2X1JhcGlkRXllLTEiLCJhc3NldF90eXBlIjoidmlzdWFsIn0.lhRgqIggvnRoCgUVX3hgaNYDQIdU09wVaImxv3a_vuGjfzC7_OteYeViboeiZYBH2_eMdWT5ZWDz2BZiAWkXlQ' \
> redding.tiff

You should now be the proud owner of a brand new visual RapidEye asset.

high res tiff

Next Guide: Best practices when working with large AOIs¶

---

Rate this guide: