Skip to main content

Items and Assets

Items​

In the Data API, an item is an entry in our catalog, and generally represents a single logical observation (or scene) captured by a satellite. Items have assets, which are the downloadable products derived from the item's source data.

All items have a standard (or shared) set of properties. A few examples of shared properties are:

  • acquired - Date and time at which the imagery was captured.
  • geometry - An item's physical footprint, described as GeoJSON.
  • published - Date and time at which this item was added to the API.

Items also have additional properties that are specific to the item_type of the item. All items of a given item_type share all properties. Whenever possible, properties identically named between different item_types will have the same schema and semantics. For example, acquired is an RFC-3339 timestamp in all items where it appears, enabling meaningful comparisons across item_types.

Item Types​

An item_type represents an imagery product. All items have an associated item_type. Each item_type has a specific list of asset_types that can be derived from the item's source data.

Available Item TypesDescription
PSScenePlanetScope 3, 4, and 8 band scenes captured by the Dove satellite constellation
TanagerSceneTanager 420 band hyperspectral data captured by the Tanager satellite constellation
TanagerMethaneTanager methane detections as captured by the Tanager satellite constellation
REOrthoTileRapidEye OrthoTiles captured by the RapidEye satellite constellation
RESceneUnorthorectified strips captured by the RapidEye satellite constellation
SkySatSceneSkySat Scenes captured by the SkySat satellite constellation
SkySatCollectOrthorectified scene composite of a SkySat collection
SkySatVideoFull motion videos collected by a single camera from any of the active SkySats

For more information about our scene data products, including an overview of each item type, see Planet Imagery.

Assets​

An asset describes a product derived from an item's source data, and can be used for various analytic, visual or other purposes. Assets are generally either image data or metadata. items have many assets available for production and download, each representing the same item using different processing steps. For example, an item may have a visual or an analytic asset. The visual asset is intended for display, while the analytic can be used for further processing.

For a complete listing of asset_types available for each item_type, see the product page links in the table above.

Items and Assets in the Data API​

Data API supports listing item types, retrieving item and asset metadata, and activating and downloading assets.

info

While the Data API supports activating and downloading single assets, we recommend most customers use the Orders API or Subscriptions API for delivery.

List Item Types​

Available item types can be listed using the /data/v1/item-types endpoint.

curl https://api.planet.com/data/v1/item-types/ \
  -u "$PL_API_KEY:"

To list only a single item type:

curl https://api.planet.com/data/v1/item-types/PSScene \
  -u "$PL_API_KEY:"

Get an Individual Item by Item ID​

tip

To search for items in an area of interest, use the search endpoints.

If you know an item ID, you can look it up:

curl https://api.planet.com/data/v1/item-types/PSScene/items/20240716_191918_05_2475 \
  -u "$PL_API_KEY:"

The response contains metadata, a list of supported assets for this item, and a list of assets that your user account has download access to.

_permissions:

The _permissions block displays assets that you are authorized to download. Downloading assets consumes quota.

List Assets for an Item​

To list assets for an individual item, use the /data/v1/item-types/${ITEM_TYPE}/${ITEM_ID}/assets endpoint:

curl https://api.planet.com/data/v1/item-types/PSScene/items/20240716_191918_05_2475/assets \
  -u "$PL_API_KEY:"

Estimate Clear Coverage over an Individual Item with a Custom AOI​

The Data API provides an endpoint that will recompute the clear coverage for a user-provided AOI in a scene. This can be used if you are looking for a clear percentage over a specific area, rather than the percentage provided for the entire scene.

curl -X POST https://api.planet.com/data/v1/item-types/PSScene/items/20240716_191918_05_2475/coverage \
  -u "$PL_API_KEY:" \
  -H "Content-Type: application/json" \
  -d \
'{
"geometry": {
   "type": "Polygon",
   "coordinates":[
      [
         [-119.55363341,51.0450587],
         [-119.4966749,51.0450587],
         [-119.4966749,51.16295449],
         [-119.55363341,51.16295449],
         [-119.55363341,51.0450587]
      ]
   ]
}
}'

Query parameters​

The coverage endpoint supports mode and band query parameters to define how the operation is performed.

  • mode: Specifies the method used for coverage calculation.
    • UDM2 (default)
      • Activates the ortho_udm2 asset and re-computes clear coverage over the provided AOI. Activation may take several minutes. This option supports polling, recommended every 10 seconds.
    • estimate
      • Provides a rough estimate based on browse imagery. Will return results synchronously. The results may incorrectly classify snow or roofs.
  • band: Defines the specific band to extract from the ortho_udm2 asset. This parameter is only supported when mode=UDM2.
    • clear (default)
    • cloud
    • snow_ice
    • cloud_shadow
    • light_haze
    • heavy_haze

Item Previews​

The Data API provides previews of Planet imagery data as thumbnails. A thumbnail is a down-sampled PNG version of an item's visual asset that can be used to preview the image without needing to download a full GeoTIFF. The thumbnail URL is advertised by the key thumbnail in the _links dictionary of an item's metadata.

Item preview authentication​

For item previews, in addition to other methods described in Authentication, you may also provide an api_key parameter to the URL.

https://tiles.planet.com/data/v1/item-types/PSScene/items/20160223_174714_0c72/thumb?api_key=${PL_API_KEY}

Size​

The thumbnail by default is 256×256 pixels, and can be scaled up to 512×512 by passing in the width parameter and setting it to values up to 512. If you have download access to the visual asset, you can scale the thumbnail higher by setting the width parameter to a maximum of 2048.

Adjusting the width of a thumbnail​

To adjust the width of a thumbnail, add the ?width= parameter to the thumbnail URL. Here is how you can scale a thumbnail to 512 pixels:

https://tiles.planet.com/data/v1/item-types/PSScene/items/20160223_174714_0c72/thumb?api_key=${PL_API_KEY}&width=1024

Activating and Downloading Assets​

The list assets response lists asset metadata along with an activation link for each asset. Use the activation link to activate an asset.

info

Assets take several minutes to activate. You may poll the asset list endpoint to wait for the status of an asset to update to active.

Assets already activated (their status is in active state) will include a location. This is a link that can be used to download the asset.

warning

Downloading assets consumes quota.

Last updated on