Items¶
In the Planet API, an item is an entry in our catalog, and generally
represents a single logical observation (or scene) captured by a satellite.
Each item is defined by an item_type, which represents the
class of spacecraft and/or processing level of the item. Assets (or
products, such as visual or analytic) can be 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-time at which the imagery was captured.geometry- An item's physical footprint, described as GeoJSON.published- Date-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 with one another. Whenever possible, properties that are 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.
Planet operates the PlanetScope (PS), RapidEye (RE), and SkySatf Earth-imaging constellations. Imagery is collected and processed in a variety of formats to serve different use cases, be it mapping, deep learning, disaster response, precision agriculture, or simple temporal image analytics to create rich information products.
PlanetScope satellite imagery is captured as a continuous strip of single frame images known as “scenes.” Scenes are derived from multiple generations of PlanetScope satellites. Older-generation of PlanetScope satellites acquired a single RGB (red, green, blue) frame or a split-frame with a RGB half and a NIR (near-infrared) half, depending on the capability of the satellite. The new generation of PlanetScope satellites (PS2.SD and PSB.SD) acquire images with a multistripe frame with bands divided between RGBNIR (PS2.SD) or RGBNIR, green I, yellow and coastal blue (PSB.SD).
Planet offers two product lines for PlanetScope imagery: a Basic Scene product and an Ortho Scene product. The Basic Scene product is a scaled Top of Atmosphere Radiance (at sensor) and sensor-corrected product. The Basic Scene product is designed for users with advanced image processing and geometric correction capabilities. The product is not orthorectified or corrected for terrain distortions. Ortho Scenes represent the single-frame image captures as acquired by a PlanetScope satellite with additional post processing applied.
Item Types¶
An item_type represents the class of spacecraft and/or processing level of an item. 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.
All items within an item_type group will have identical schemas with no nullified or optional properties. Items across item_types may also share identical properties, and generally have the same schema and semantics to facilitate cross item_type searching using shared properties. As an example, both REOrthoTile and PSScene items have acquired and published properties. It can be assumed that these properties have the same meaning across both item_types.
Whenever possible, item data is sliced in a similar manner across item_types.
| Available Item Types | Description |
|---|---|
| PSScene | PlanetScope 3, 4, and 8 band scenes captured by the Dove 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 |
| Landsat8L1G | Landsat8 Scenes provided by USGS Landsat8 satellite |
| Sentinel2L1C | Copernicus Sentinel-2 Scenes provided by ESA Sentinel-2 satellite |
Assets¶
An asset describes a product that can be 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 a different representation of the same item using different processing steps. (To view all possible asset values for an item type you're interested in, select that item type, above.) As an 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, checkout the item type specifics in this section.
Item Publishing Lifecycle¶
An item's publishing stage will help you understand when the right time is to download an item, based on whether your pipeline needs to optimize for data latency or data accuracy.
Publishing stage is only available for PlanetScope and SkySat items: PSScene, SkySatScene, SkySatCollect, SkySatVideo. It supports the following values, availability and prevalence of each varying by item type:
preview: Lowest latency, lowest fidelity. Data is unrectified; metadata changes are expected upon subsequent republishing.standard: Standard latency, standard fidelity. Data is stable and rectified, but subject to minimal metadata changes upon republishing.finalized: Highest latency, highest fidelity. Data is stable and rectified, no additional metadata changes are expected (barring any bug fixes or new quality improvements)
Preview Stage¶
Applicable only to unrectifiable, open water or cloud PSScene (less than 20% of all PSScene items) and all SkySatScene items.
- "Preview" PSScene items typically published about 4 to 6 hours before they will be republished as
standard(if they are rectifiable). If an image is still marked aspreviewafter 48 hours of acquisition, it will remain in thepreviewstate and not move to the next. - "Preview" SkySatScene items (L1A assets) are typically published two hours before they will
berectified and republished asfinalized.
Upon republishing to standard or finalized, significant metadata changes are expected. If the data is unrectifiable, it will remain in the preview stage.
Standard Stage¶
Applicable to all PSScene items. With the exception of unrectifiable, open water/cloudy PSScene imagery, all of PlanetScope publishing will start in the standard stage. Note: this stage is not used for SkySat publishing.
All standard PlanetScope items will be republished to a finalized stage and may be subject to minimal change upon republishing as more scenes within a strip are published.
Finalized Stage¶
Applicable to all PSScene, SkySatCollect, SkySatVideo, and rectifiable PSScene and SkySatScene items. While no further republishing or metadata changes are expected as part of standard publishing for finalized items, Planet's catalog is dynamic and we will republish items as bug fixes, new metadata fields, new asset types, and broader quality improvements are released. You can read more on our UpdateFilter feature to learn about ways we support redownloading to filter on these enhancements.
- For PSScene items,
finalizeddata will be available approximately 12-24 hours after an item reachesstandardstage. - For SkySatScene items,
finalizeddata will be available approximately 2 hours after an item is published aspreview - All SkySatCollect and SkySatVideo items will start and end in the
finalizedstate
We are continually working to improve our technical documentation and support. Please help by sharing your experience with us.