Log inSuggest an edit

Common Workflows for the Data API

Table of Contents

  1. Filter Items
  2. Activate Asset
  3. Download Asset

The following are examples of how the Data API could be used to accomplish various tasks. These only exist for the sake of demonstration.

Filter Items

Item filtering is accomplished using the search capability.

Using the QuickSearch operation, fetch a set of items across the REOrthoTile and PSOrthoTile item types having a black_fill below 0.3 like so:

curl -XPOST https://api.planet.com/data/v1/quick-search -H 'Content-Type:application/json' -d '{
    "name": "REOrthoTile",
    "item_types": ["REOrthoTile", "PSOrthoTile"],
    "filter": {
        "type": "AndFilter",
        "config": [
            {
                "type": "RangeFilter",
                "field_name": "black_fill",
                "config": {
                    "lte": 0.3
                }
            }
        ]
    }
}' -u "$PL_API_KEY:"

Such a query generally returns more results than desired. To filter this list down to a more reasonable set, common strategies include filering by the items footprint via the geometry attribute in conjunction with a GeometryFilter, and it's acquisition time via a DateRangeFilter on the acquired attribute.

For example, the following request searches for Rapideye Ortho Tiles items taken between September 1, 2016 and October 1, 2016 in a bounding box around San Francisco:

curl -XPOST https://api.planet.com/data/v1/quick-search -H 'Content-Type:application/json' -d '{
    "name": "REOrthoTile",
    "item_types": ["REOrthoTile"],
    "filter": {
        "type": "AndFilter",
        "config": [
            {
                "type": "DateRangeFilter",
                "field_name": "acquired",
                "config": {
                    "gte": "2016-09-01T00:00:00Z",
                    "lte": "2016-10-01T00:00:00Z"
                }
            },
            {
              "type": "GeometryFilter",
              "field_name": "geometry",
              "config": {
                "type": "Polygon",
                "coordinates": [
                  [
                    [
                      -122.53738403320312,
                      37.69305769827658
                    ],
                    [
                      -122.53738403320312,
                      37.820632846207864
                    ],
                    [
                      -122.3444366455078,
                      37.820632846207864
                    ],
                    [
                      -122.3444366455078,
                      37.69305769827658
                    ],
                    [
                      -122.53738403320312,
                      37.69305769827658
                    ]
                  ]
                ]
              }
            }
        ]
    }
}' -u "$PL_API_KEY:"

The available filters are specific to each item type, and can be discovered via their item properties schema.

Find Items with Downloadable Assets

The _permissions property identifies which assets a client may download for a given item. This property may be filtered in a similar manner to other item attributes using the PermissionFilter.

The following QuickSearch request filters the returned items to those with any downloadable asset:

curl -XPOST https://api.planet.com/data/v1/quick-search -H 'Content-Type:application/json' -d '{
    "name": "REOrthoTile",
    "item_types": ["REOrthoTile", "PSOrthoTile"],
    "filter": {
        "type": "AndFilter",
        "config": [
            {
                "type": "PermissionFilter",
                "config": ["assets:download"]
            }
        ]
    }
}' -u "$PL_API_KEY:"

Activate an Asset File

Using REOrthoTile as our ItemTypeID and 20160909_140034_2334314_RapidEye-2 as our ItemID, we start with a assets list operation:

curl -u "$PL_API_KEY:" https://api.planet.com/data/v1/item-types/REOrthoTile/items/20160909_140034_2334314_RapidEye-2/assets/

The response contains a collection of assets, one of which is an inactive analytic asset:

{
  "analytic": {
    "_links": {
      "_self": "https://api.planet.com/data/v1/assets/eyJpIjogIjIwMTYwOTA5XzE0MDAzNF8yMzM0MzE0X1JhcGlkRXllLTIiLCAiYyI6ICJSRU9ydGhvVGlsZSIsICJ0IjogImFuYWx5dGljIiwgImN0IjogIml0ZW0tdHlwZSJ9",
      "activate": "https://api.planet.com/data/v1/assets/eyJpIjogIjIwMTYwOTA5XzE0MDAzNF8yMzM0MzE0X1JhcGlkRXllLTIiLCAiYyI6ICJSRU9ydGhvVGlsZSIsICJ0IjogImFuYWx5dGljIiwgImN0IjogIml0ZW0tdHlwZSJ9/activate",
      "type": "https://api.planet.com/data/v1/asset-types/analytic"
    },
    "_permissions": [
      "download"
    ],
    "status": "inactive",
    "type": "analytic"
  },
  ...
}

To activate this asset we can issue either a POST or GET request against its activation url:

curl -u "$PL_API_KEY:" https://api.planet.com/data/v1/assets/eyJpIjogIjIwMTYwOTA5XzE0MDAzNF8yMzM0MzE0X1JhcGlkRXllLTIiLCAiYyI6ICJSRU9ydGhvVGlsZSIsICJ0IjogImFuYWx5dGljIiwgImN0IjogIml0ZW0tdHlwZSJ9/activate

The response is a 202, which indicates the request to activate the file was accepted and is now processing.

We can then repeat the initial request, polling until the "analytic" asset's status becomes active. Once this happens, the file will be ready for download and a download url will be present.

Download an Asset File

Using REOrthoTile as our ItemTypeID and 20160909_140034_2334314_RapidEye-2 as our ItemID, we start with a operation to list all assets for an item:

curl -u "$PL_API_KEY:" https://api.planet.com/data/v1/item-types/REOrthoTile/items/20160909_140034_2334314_RapidEye-2/assets/

The response contains a collection of assets:

{
  "analytic": {
    "_links": {
      "_self": "https://api.planet.com/data/v1/assets/eyJpIjogIjIwMTYwOTA5XzE0MDAzNF8yMzM0MzE0X1JhcGlkRXllLTIiLCAiYyI6ICJSRU9ydGhvVGlsZSIsICJ0IjogImFuYWx5dGljIiwgImN0IjogIml0ZW0tdHlwZSJ9",
      "activate": "https://api.planet.com/data/v1/assets/eyJpIjogIjIwMTYwOTA5XzE0MDAzNF8yMzM0MzE0X1JhcGlkRXllLTIiLCAiYyI6ICJSRU9ydGhvVGlsZSIsICJ0IjogImFuYWx5dGljIiwgImN0IjogIml0ZW0tdHlwZSJ9/activate",
      "type": "https://api.planet.com/data/v1/asset-types/analytic"
    },
    "_permissions": [
      "download"
    ],
    "status": "inactive",
    "type": "analytic"
  },
  "analytic_xml": {
    "_links": {
      "_self": "https://api.planet.com/data/v1/assets/eyJpIjogIjIwMTYwOTA5XzE0MDAzNF8yMzM0MzE0X1JhcGlkRXllLTIiLCAiYyI6ICJSRU9ydGhvVGlsZSIsICJ0IjogImFuYWx5dGljX3htbCIsICJjdCI6ICJpdGVtLXR5cGUifQ",
      "activate": "https://api.planet.com/data/v1/assets/eyJpIjogIjIwMTYwOTA5XzE0MDAzNF8yMzM0MzE0X1JhcGlkRXllLTIiLCAiYyI6ICJSRU9ydGhvVGlsZSIsICJ0IjogImFuYWx5dGljX3htbCIsICJjdCI6ICJpdGVtLXR5cGUifQ/activate",
      "type": "https://api.planet.com/data/v1/asset-types/analytic_xml"
    },
    "_permissions": [
      "download"
    ],
    "status": "inactive",
    "type": "analytic_xml"
  },
  "udm": {
    "_links": {
      "_self": "https://api.planet.com/data/v1/assets/eyJpIjogIjIwMTYwOTA5XzE0MDAzNF8yMzM0MzE0X1JhcGlkRXllLTIiLCAiYyI6ICJSRU9ydGhvVGlsZSIsICJ0IjogInVkbSIsICJjdCI6ICJpdGVtLXR5cGUifQ",
      "activate": "https://api.planet.com/data/v1/assets/eyJpIjogIjIwMTYwOTA5XzE0MDAzNF8yMzM0MzE0X1JhcGlkRXllLTIiLCAiYyI6ICJSRU9ydGhvVGlsZSIsICJ0IjogInVkbSIsICJjdCI6ICJpdGVtLXR5cGUifQ/activate",
      "type": "https://api.planet.com/data/v1/asset-types/udm"
    },
    "_permissions": [
      "download"
    ],
    "status": "inactive",
    "type": "udm"
  },
  "visual": {
    "_links": {
      "_self": "https://api.planet.com/data/v1/assets/eyJpIjogIjIwMTYwOTA5XzE0MDAzNF8yMzM0MzE0X1JhcGlkRXllLTIiLCAiYyI6ICJSRU9ydGhvVGlsZSIsICJ0IjogInZpc3VhbCIsICJjdCI6ICJpdGVtLXR5cGUifQ",
      "activate": "https://api.planet.com/data/v1/assets/eyJpIjogIjIwMTYwOTA5XzE0MDAzNF8yMzM0MzE0X1JhcGlkRXllLTIiLCAiYyI6ICJSRU9ydGhvVGlsZSIsICJ0IjogInZpc3VhbCIsICJjdCI6ICJpdGVtLXR5cGUifQ/activate",
      "type": "https://api.planet.com/data/v1/asset-types/visual"
    },
    "_permissions": [
      "download"
    ],
    "expires_at": "2016-09-09T23:50:52.343159",
    "location": "https://api.planet.com/data/v1/download?token=eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJiT1FVNG5nM2IwVUJmellqN1BsRWgyM1RJQTNJZU9QMWhITEthTDNjazl1Y0xaZUxYTUo3TmdFVEVMY0h6cGV2ZTRsWFBIbXZLMGhkTkkxU0dLMXh1dz09IiwiaXRlbV90eXBlX2lkIjoiUkVPcnRob1RpbGUiLCJ0b2tlbl90eXBlIjoidHlwZWQtaXRlbSIsImV4cCI6MTQ3MzQ2NTA1MiwiaXRlbV9pZCI6IjIwMTYwOTA5XzE0MDAzNF8yMzM0MzE0X1JhcGlkRXllLTIiLCJhc3NldF90eXBlIjoidmlzdWFsIn0.HzHQT1GspD5gXic805DgxYUPvj0iq4OBIIrWSTsWyF4kUivHVOOeSvuRvrqPvLsrF6evpesvEncr1WTBrcWKcw",
    "status": "active",
    "type": "visual"
  },
  "visual_xml": {
    "_links": {
      "_self": "https://api.planet.com/data/v1/assets/eyJpIjogIjIwMTYwOTA5XzE0MDAzNF8yMzM0MzE0X1JhcGlkRXllLTIiLCAiYyI6ICJSRU9ydGhvVGlsZSIsICJ0IjogInZpc3VhbF94bWwiLCAiY3QiOiAiaXRlbS10eXBlIn0",
      "activate": "https://api.planet.com/data/v1/assets/eyJpIjogIjIwMTYwOTA5XzE0MDAzNF8yMzM0MzE0X1JhcGlkRXllLTIiLCAiYyI6ICJSRU9ydGhvVGlsZSIsICJ0IjogInZpc3VhbF94bWwiLCAiY3QiOiAiaXRlbS10eXBlIn0/activate",
      "type": "https://api.planet.com/data/v1/asset-types/visual_xml"
    },
    "_permissions": [
      "download"
    ],
    "expires_at": "2016-09-09T23:50:52.419200",
    "location": "https://api.planet.com/data/v1/download?token=eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJDSWhQejNxSHhhZG1HTFNyS09OMGNqVVMrQ2JsejZXbEdDSmh6SVpYaHZMbGkvMk1veStiRnlvTU42L2J1d0FkV3NpRW9hWHZtd1VuM2dmbXNtZndXZz09IiwiaXRlbV90eXBlX2lkIjoiUkVPcnRob1RpbGUiLCJ0b2tlbl90eXBlIjoidHlwZWQtaXRlbSIsImV4cCI6MTQ3MzQ2NTA1MiwiaXRlbV9pZCI6IjIwMTYwOTA5XzE0MDAzNF8yMzM0MzE0X1JhcGlkRXllLTIiLCJhc3NldF90eXBlIjoidmlzdWFsX3htbCJ9.dBjmtZsm56m_AgLJhgS9PCXI5Tq4kUKjIxepm_Rujj1s2ewghRalDY47cKrR900SkTD3EQ01U8utNx-aVqOe2g",
    "status": "active",
    "type": "visual_xml"
  }
}

Since the visual asset has an active "http" file, we simply make an HTTP GET request against the provided location:

curl -u "$PL_API_KEY:" -L "https://api.planet.com/data/v1/download?token=eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJiT1FVNG5nM2IwVUJmellqN1BsRWgyM1RJQTNJZU9QMWhITEthTDNjazl1Y0xaZUxYTUo3TmdFVEVMY0h6cGV2ZTRsWFBIbXZLMGhkTkkxU0dLMXh1dz09IiwiaXRlbV90eXBlX2lkIjoiUkVPcnRob1RpbGUiLCJ0b2tlbl90eXBlIjoidHlwZWQtaXRlbSIsImV4cCI6MTQ3MzQ2NTA1MiwiaXRlbV9pZCI6IjIwMTYwOTA5XzE0MDAzNF8yMzM0MzE0X1JhcGlkRXllLTIiLCJhc3NldF90eXBlIjoidmlzdWFsIn0.HzHQT1GspD5gXic805DgxYUPvj0iq4OBIIrWSTsWyF4kUivHVOOeSvuRvrqPvLsrF6evpesvEncr1WTBrcWKcw" > 20160909_140034_2334314_RapidEye-2_visual.tif

The response will contain the binary image data.