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 Types | Description |
---|---|
PSScene | PlanetScope 3, 4, and 8 band scenes captured by the Dove satellite constellation |
TanagerScene | Tanager 420 band hyperspectral data captured by the Tanager satellite constellation |
TanagerMethane | Tanager methane detections as captured by the Tanager satellite constellation |
REOrthoTile | RapidEye OrthoTiles captured by the RapidEye satellite constellation |
REScene | Unorthorectified strips captured by the RapidEye satellite constellation |
SkySatScene | SkySat Scenes captured by the SkySat satellite constellation |
SkySatCollect | Orthorectified scene composite of a SkySat collection |
SkySatVideo | Full 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.
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
curl https://api.planet.com/data/v1/item-types/ \
-u "$PL_API_KEY:"
To list only a single item type:
- CURL
curl https://api.planet.com/data/v1/item-types/PSScene \
-u "$PL_API_KEY:"
Get an Individual Item by Item ID
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
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
- Python SDK
curl https://api.planet.com/data/v1/item-types/PSScene/items/20240716_191918_05_2475/assets \
-u "$PL_API_KEY:"
from typing import Iterator
from planet import Planet
pl = Planet()
def get_item_assets(item_type: str, item_id: str) -> dict:
return pl.data.list_item_assets(item_type, item_id)
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
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.
- Activates the
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 theortho_udm2 asset
. This parameter is only supported whenmode=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.
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.
Downloading assets consumes quota.