Log inSuggest an edit

Items and Assets

Table of Contents

  1. Item Type
  2. Item
  3. Asset

The Data API represents Planet imagery data in item type, item and asset objects.

Objects

Item Type

An item type is used to model imagery data sharing schemas and capabilities. Examples include PSOrthoTile and REOrthoTile representing PlanetScope Ortho Tiles and RapidEye Ortho Tiles respectively.

Two different item types may have define identical properties. For example, both REOrthoTile and PSOrthoTile have acquired, published, and black_fill properties. These properties are guaranteed to have the same schema, faciliating cross-item type searches across shared properties.

They may also have their own distinct fields that are specific to a given item type.

What constitutes an Item Type?

All data within an item type should have identical schemas with no nullified or optional properties. For example, all PSOrthoTile items are guaranteed to have a grid_cell attribute as well as view_angle. Additionally, the data tends to be sliced in a similar manner: all PSOrthoTile items are segmented along the RapidEye Level 3A grid.

Individual PlanetScope scenes, however, are exposed in two different item types named PSScene3Band and PSScene4Band. Since neither of these have been segmented to any grid, they do not have properties such as grid_cell. And unlike, REOrthoTile and PSOrthoTile, PSScenes3Band and PSScenes4Band have varying footprints.

A list of item types available in the Planet API may be found in the table below:

Item TypeDescription
PSScene3BandPlanetScope Scenes
PSScene4BandPlanetScope Scenes
PSOrthoTilePlanetScope OrthoTiles
REOrthoTileRapidEye OrthoTiles
RESceneRapidEye Scenes (unorthorectified strips)
SkySatSceneSkySat Scenes
Landsat8L1GLandsat8 Scenes
Sentinel2L1CCopernicus Sentinel-2 Scenes

Item

An item represents a single logical image. All items will have a common set of properties, such as:

  • acquired: date-time at which the image was captured
  • geometry: physical area represented by the item, described as a GeoJSON feature
  • published: date-time at which this item was added to the API

Additional properties are specific to the item type of the item. The item type to which an item belongs defines its schema and all items of a given item type share the this schema.

Wherever possible, attributes that are identically named between two different item types will have the same schema and semantics. For example, acquired is an RFC-3339 timestamp in all item types where it appears, enabling comparsions across item types.

To find REOrthoTile or PSOrthoTile acquired since October 28, 2015:

curl -XPOST https://api.planet.com/data/v1/quick-search -H 'Content-Type:application/json' -d '{
    "item_types": ["PSOrthoTile", "REOrthoTile"],
    "filter": {
        "type": "AndFilter",
        "config": [
            {
                "type": "DateRangeFilter",
                "field_name": "acquired",
                "config": {
                    "gte": "2015-10-28T00:00:00Z"
                }
            }
        ]
    }
}' -u "$PL_API_KEY:"

Asset

An asset describes a file that is available for download. An item may have several assets, each of which represents the item using different processing steps. For example, an item may have a visual and an analytic asset. The visual asset is intended for display, while the analytic asset is fit for further processing. These assets represent different data, however, they both represent the same logical image capture and share a single footprint.

The most common assets for PlanetScope, RapidEye, and Skysat imagery are listed in the table below:

Asset TypeDescription
analyticRadiometrically-calibrated analytic image stored as 16-bit scaled radiance
analytic_xmlAnalytic image metadata in XML format
visualVisual image with color-correction
visual_xmlVisual image metadata in XML format
udmUsable data mask

Activating an Asset File

The status of an asset may be: inactive, activating or active. Before an asset can be downloaded, it must be made active by making an HTTP POST request to the activate link provided in the API reponse.

MD5 digest

The API will show the md5 digest of any active asset so that the user may compare their copy of the data with what the Planet API is currently providing. The md5 digest can help the user detect incomplete or corrup downloads as well as inform the user when the asset has changed.