Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/data/items/) # 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](#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](#item-types) 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](#assets) that can be derived from the `item's` source data. | Available Item Types | Description | | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | [PSScene](https://docs.planet.com/data/imagery/planetscope.md) | PlanetScope 3, 4, and 8 band scenes captured by the Dove satellite constellation | | [TanagerScene](https://docs.planet.com/data/imagery/tanager.md) | Tanager 420 band hyperspectral data captured by the Tanager satellite constellation | | [TanagerMethane](https://docs.planet.com/data/imagery/tanager.md) | Tanager methane detections as captured by the Tanager satellite constellation | | [REOrthoTile](https://docs.planet.com/data/imagery/rapideye.md) | RapidEye OrthoTiles captured by the RapidEye satellite constellation | | [REScene](https://docs.planet.com/data/imagery/rapideye.md) | Unorthorectified strips captured by the RapidEye satellite constellation | | [SkySatScene](https://docs.planet.com/data/imagery/skysat.md) | SkySat Scenes captured by the SkySat satellite constellation | | [SkySatCollect](https://docs.planet.com/data/imagery/skysat.md) | Orthorectified scene composite of a SkySat collection | | [SkySatVideo](https://docs.planet.com/data/imagery/skysat.md) | 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](https://docs.planet.com/data/imagery.md). ### Assets An `asset` describes a product derived from an [item's](#items) 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 ``` 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 tip To search for items in an area of interest, use the [search endpoints](https://docs.planet.com/develop/apis/data/item-search.md). 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 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 * Python SDK ``` 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] ] ] } }' ``` ``` import time from planet import Planet pl = Planet() geom = { "type": "Polygon", "coordinates": [ [ [-119.55363341, 51.0450587], [-119.4966749, 51.0450587], [-119.4966749, 51.16295449], [-119.55363341, 51.16295449], [-119.55363341, 51.0450587], ] ], } def get_item_coverage(item_type: str, item_id: str): item_type = "PSScene" item_id = "20240716_191918_05_2475" # use estimate mode for a quick response estimate = pl.data.get_item_coverage(item_type, item_id, geom, mode="estimate") print(estimate) # { # "status": "complete", # "clear_percent": 71 # } # UDM2 mode requires polling while a UDM2 data mask is activated. # Note: This is the default. result = pl.data.get_item_coverage(item_type, item_id, geom, mode="UDM2") while result["status"] == "activating": result = pl.data.get_item_coverage(item_type, item_id, geom) time.sleep(10) print(result) # { # "status": "complete", # "clear_percent": 73 # } ``` #### 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`](https://docs.planet.com/data/imagery/udm.md#udm21-product-bands) 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`](https://docs.planet.com/data/imagery/udm.md#metadata-fields). 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](https://docs.planet.com/develop/authentication.md), 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](#list-assets-for-an-item) 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.