Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/data/reference/) # Data API Reference * Items and Assets * getList Asset Types * getGet Asset Type * getList Item Types * getGet Item Type * getGet Item * getList Item Assets * postcloud coverage estimate * getList Item Versions * getGet Item Version * Item Search * postQuick Search * getList Saved Searches * postCreate Saved Search * delDelete Saved Search * getGet Saved Search * putUpdate Saved Search * getRun Saved Search * Item Stats * postSearch Stats [API docs by Redocly](https://redocly.com/redoc/) # Planet Data API (1.0.0) Download OpenAPI specification:[Download](https://docs.planet.com/redocusaurus/data-api-spec.yaml) The Planet Data API serves all Planet Labs imagery to public clients. This is the general spec that governs the common API objects and operations. ## [](#tag/Items-and-Assets)Items and Assets ## [](#tag/Items-and-Assets/operation/ListAssetTypes)List Asset Types List all asset types available to the authenticated user. 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. These are referred to as `asset_types`. [Learn more about asset types](https://docs.planet.com/develop/apis/data/items/#assets) ##### Authorizations: *basic* ### Responses **200** List of asset types. get/asset-types https\://api.planet.com/data/v1/asset-types ### Response samples * 200 Content type application/json Copy Expand all Collapse all `{ "_links": { "_self": "string" }, "asset_types": [ { "_links": { "_self": "string" }, "display_description": "string", "display_name": "string", "id": "string", "md5_digest": "string" } ] }` ## [](#tag/Items-and-Assets/operation/GetAssetType)Get Asset Type Get an asset type by id. 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. These are referred to as `asset_types`. [Learn more about asset types](https://docs.planet.com/develop/apis/data/items/#assets) ##### Authorizations: *basic* ##### path Parameters | | | | ----------------------- | ---------------------------- | | asset\_type\_idrequired | stringAsset type identifier. | ### Responses **200** Asset type details. **404** The requested asset type does not exist. get/asset-types/{asset\_type\_id} https\://api.planet.com/data/v1/asset-types/{asset\_type\_id} ### Response samples * 200 * 404 Content type application/json Copy Expand all Collapse all `{ "_links": { "_self": "string" }, "display_description": "string", "display_name": "string", "id": "string", "md5_digest": "string" }` ## [](#tag/Items-and-Assets/operation/ListItemTypes)List Item Types List all item types available to the authenticated user. 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 set of supported `asset_types` which may be produced for a given item. [Learn more about item types](https://docs.planet.com/develop/apis/data/items/#item-types) ##### Authorizations: *basic* ### Responses **200** List of item types. get/item-types https\://api.planet.com/data/v1/item-types ### Response samples * 200 Content type application/json Copy Expand all Collapse all `{ "_links": { "_self": "string" }, "item_types": [ { "_links": { "_self": "string" }, "display_description": "string", "display_name": "string", "id": "string", "supported_asset_types": [ "analytic" ] } ] }` ## [](#tag/Items-and-Assets/operation/GetItemType)Get Item Type Get an item type by id. 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 set of supported `asset_types` which may be produced for a given item. [Learn more about item types](https://docs.planet.com/develop/apis/data/items/#item-types) ##### Authorizations: *basic* ##### path Parameters | | | | ---------------------- | --------------------------- | | item\_type\_idrequired | stringItem type identifier. | ### Responses **200** Item type details. **404** The requested item type does not exist. get/item-types/{item\_type\_id} https\://api.planet.com/data/v1/item-types/{item\_type\_id} ### Response samples * 200 * 404 Content type application/json Copy Expand all Collapse all `{ "_links": { "_self": "string" }, "display_description": "string", "display_name": "string", "id": "string", "supported_asset_types": [ "analytic" ] }` ## [](#tag/Items-and-Assets/operation/GetItem)Get Item Get an item by id and item type. 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. [Learn more about items](https://docs.planet.com/develop/apis/data/items/#items) ##### Authorizations: *basic* ##### path Parameters | | | | ---------------------- | --------------------------- | | item\_type\_idrequired | stringItem type identifier. | | item\_idrequired | stringItem identifier. | ### Responses **200** Item details. **404** The requested item does not exist for the given item type. get/item-types/{item\_type\_id}/items/{item\_id} https\://api.planet.com/data/v1/item-types/{item\_type\_id}/items/{item\_id} ### Response samples * 200 * 404 Content type application/json Copy Expand all Collapse all `{ "_links": { "_self": "string", "assets": "string", "thumbnail": "string" }, "_permissions": null, "assets": null, "geometry": { "relation": "intersects", "type": "Polygon" }, "id": "string", "properties": { "acquired": "2019-08-24T14:15:22Z", "anomalous_pixels": 0.1, "black_fill": 0.1, "cloud_cover": 0.1, "columns": 0, "epsg_code": 0, "gsd": 0.1, "item_type": "string", "origin_x": 0, "origin_y": 0, "pixel_resolution": 0, "provider": "string", "published": "2019-08-24T14:15:22Z", "rows": 0, "satellite_id": "string", "sun_azimuth": 0.1, "sun_elevation": 0.1, "updated": "2019-08-24T14:15:22Z", "usable_data": 0.1, "view_angle": 0.1 } }` ## [](#tag/Items-and-Assets/operation/ListItemAssets)List Item Assets List all assets available for an item. 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. These are referred to as `asset_types`. [Learn more about asset types](https://docs.planet.com/develop/apis/data/items/#assets) ##### Authorizations: *basic* ##### path Parameters | | | | ---------------------- | --------------------------- | | item\_type\_idrequired | stringItem type identifier. | | item\_idrequired | stringItem identifier. | ### Responses **200** List of available assets. **404** The requested item does not exist for the given item type. get/item-types/{item\_type\_id}/items/{item\_id}/assets https\://api.planet.com/data/v1/item-types/{item\_type\_id}/items/{item\_id}/assets ### Response samples * 200 * 404 Content type application/json Copy Expand all Collapse all `{ "_links": { "_self": "string", "activate": "string", "type": "string" }, "_permissions": [ "download" ], "expires_at": "2019-08-24T14:15:22Z", "location": "string", "status": "inactive", "type": "string" }` ## [](#tag/Items-and-Assets/operation/CloudCoverage)cloud coverage estimate gets coverage estimate ##### Authorizations: *basic* ##### path Parameters | | | | ---------------------- | --------------------------- | | item\_type\_idrequired | stringItem type identifier. | | item\_idrequired | stringItem identifier. | ##### query Parameters | | | | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | mode | stringEnum: "UDM2" "estimate"The mode to calculate coverage. - `UDM2` -> Activate the ortho\_udm2 asset and compute clear coverage over the provided AOI. Activation may take several minutes. This option supports polling. (default) - `estimate` -> Will not activate the asset. Provides a rough estimate based on browse imagery. Will return results more quickly. | | band | stringEnum: "clear" "snow\_ice" "cloud\_shadow" "light\_haze" "heavy\_haze" "cloud" "cirrus"The UDM2 band used to calculate coverage. | ##### Request Body schema: application/jsonrequired The area of the cloud coverage request. ### Responses **201** Cloud coverage status and clear percentage estimate. **404** The requested item does not exist for the given item type. post/item-types/{item\_type\_id}/items/{item\_id}/coverage https\://api.planet.com/data/v1/item-types/{item\_type\_id}/items/{item\_id}/coverage ### Request samples * Payload Content type application/json No sample ### Response samples * 201 * 404 Content type application/json Copy `{ "clear_percent": 0, "status": "string" }` ## [](#tag/Items-and-Assets/operation/ListItemVersions)List Item Versions List all data versions available for an item. ##### Authorizations: *basic* ##### path Parameters | | | | ---------------------- | --------------------------- | | item\_type\_idrequired | stringItem type identifier. | | item\_idrequired | stringItem identifier. | ### Responses **200** List of available data versions as a FeatureCollection. **404** The requested item does not exist for the given item type. get/item-types/{item\_type\_id}/items/{item\_id}/versions https\://api.planet.com/data/v1/item-types/{item\_type\_id}/items/{item\_id}/versions ### Response samples * 200 * 404 Content type application/json Copy Expand all Collapse all `{ "_links": { "_self": "string" }, "features": [ { "_links": { "_self": "string", "assets": "string", "thumbnail": "string" }, "_permissions": null, "assets": null, "geometry": { "relation": "intersects", "type": "Polygon" }, "id": "string", "properties": { "acquired": "2019-08-24T14:15:22Z", "anomalous_pixels": 0.1, "black_fill": 0.1, "cloud_cover": 0.1, "columns": 0, "epsg_code": 0, "gsd": 0.1, "item_type": "string", "origin_x": 0, "origin_y": 0, "pixel_resolution": 0, "provider": "string", "published": "2019-08-24T14:15:22Z", "rows": 0, "satellite_id": "string", "sun_azimuth": 0.1, "sun_elevation": 0.1, "updated": "2019-08-24T14:15:22Z", "usable_data": 0.1, "view_angle": 0.1 } } ], "type": "FeatureCollection" }` ## [](#tag/Items-and-Assets/operation/GetItemVersion)Get Item Version Get a specific data version of an item. ##### Authorizations: *basic* ##### path Parameters | | | | ---------------------- | --------------------------------- | | item\_type\_idrequired | stringItem type identifier. | | item\_idrequired | stringItem identifier. | | data\_versionrequired | stringThe data version timestamp. | ### Responses **200** Item details for the specified version. **404** The requested version does not exist for the given item. get/item-types/{item\_type\_id}/items/{item\_id}/versions/{data\_version} https\://api.planet.com/data/v1/item-types/{item\_type\_id}/items/{item\_id}/versions/{data\_version} ### Response samples * 200 * 404 Content type application/json Copy Expand all Collapse all `{ "_links": { "_self": "string", "assets": "string", "thumbnail": "string" }, "_permissions": null, "assets": null, "geometry": { "relation": "intersects", "type": "Polygon" }, "id": "string", "properties": { "acquired": "2019-08-24T14:15:22Z", "anomalous_pixels": 0.1, "black_fill": 0.1, "cloud_cover": 0.1, "columns": 0, "epsg_code": 0, "gsd": 0.1, "item_type": "string", "origin_x": 0, "origin_y": 0, "pixel_resolution": 0, "provider": "string", "published": "2019-08-24T14:15:22Z", "rows": 0, "satellite_id": "string", "sun_azimuth": 0.1, "sun_elevation": 0.1, "updated": "2019-08-24T14:15:22Z", "usable_data": 0.1, "view_angle": 0.1 } }` ## [](#tag/Item-Search)Item Search ## [](#tag/Item-Search/operation/QuickSearch)Quick Search Executes a structured item search. The search APIs allow for both simple and complex `item` searches. Complex searches support boolean conditions, multiple values, geometries using GeoJSON and others. You can also save, retrieve and execute searches that you use frequently for easy use later. [Learn more about searching](https://docs.planet.com/develop/apis/data/item-search/#filters) ##### Authorizations: *basic* ##### query Parameters | | | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | \_page\_size | integer \ \[ 0 .. 250 ]Default: 250Number of results to return per page. This may only be used at the start of pagination. This may not be provided with the "\_page" parameter. | | \_sort | stringDefault: "published desc"Enum: "acquired asc" "acquired desc" "published asc" "published desc"Field and direction to order results by. This may not be provided with the "\_page" parameter. | ##### Request Body schema: application/jsonrequired The structured search criteria. | | | | ------------------- | --------------------------------------------------------- | | asset\_types | Array of stringsThe asset types to include in the search. | | filter | object (Filter)Structured search criteria. | | geometry | object (GeoJSONGeometry)A GeoJSON geometry. | | item\_typesrequired | Array of stringsThe item types to include in the search. | | name | string^.{1,64}$The name of the saved search. | ### Responses **200** List of items that match search criteria. **400** There was an error executing the search. post/quick-search https\://api.planet.com/data/v1/quick-search ### Request samples * Payload Content type application/json Copy Expand all Collapse all `{ "asset_types": [ "string" ], "filter": { "type": "string" }, "geometry": { "relation": "intersects", "type": "Polygon" }, "item_types": [ "string" ], "name": "string" }` ### Response samples * 200 * 400 Content type application/json Copy Expand all Collapse all `{ "_links": { "_self": "string", "_first": "string", "_next": "string" }, "features": [ { "_links": { "_self": "string", "assets": "string", "thumbnail": "string" }, "_permissions": null, "assets": null, "geometry": { "relation": "intersects", "type": "Polygon" }, "id": "string", "properties": { "acquired": "2019-08-24T14:15:22Z", "anomalous_pixels": 0.1, "black_fill": 0.1, "cloud_cover": 0.1, "columns": 0, "epsg_code": 0, "gsd": 0.1, "item_type": "string", "origin_x": 0, "origin_y": 0, "pixel_resolution": 0, "provider": "string", "published": "2019-08-24T14:15:22Z", "rows": 0, "satellite_id": "string", "sun_azimuth": 0.1, "sun_elevation": 0.1, "updated": "2019-08-24T14:15:22Z", "usable_data": 0.1, "view_angle": 0.1 } } ] }` ## [](#tag/Item-Search/operation/ListSearches)List Saved Searches List all saved searches available to the authenticated user. ##### Authorizations: *basic* ##### query Parameters | | | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | \_page | stringToken representing a specific page of results. This should never be constructed manually. | | \_page\_size | integer \ \[ 0 .. 250 ]Default: 250Number of results to return per page. This may only be used at the start of pagination. This may not be provided with the "\_page" parameter. | | \_sort | stringDefault: "created desc"Enum: "created desc" "created asc"Field and direction to order results by. This may not be provided with the "\_page" parameter. | | search\_type | stringDefault: "any"Enum: "any" "saved" "quick"Search type filter. | ### Responses **200** List of saved searches. get/searches https\://api.planet.com/data/v1/searches ### Response samples * 200 Content type application/json Copy Expand all Collapse all `{ "_links": { "_self": "string", "_first": "string", "_next": "string", "_prev": "string" }, "searches": [ { "__daily_email_enabled": false, "_links": { "_self": "string", "thumbnail": "string" }, "created": "2019-08-24T14:15:22Z", "filter": { "type": "string" }, "id": "string", "last_executed": "2019-08-24T14:15:22Z", "name": "string", "updated": "2019-08-24T14:15:22Z" } ] }` ## [](#tag/Item-Search/operation/CreateSearch)Create Saved Search Create a new saved search. ##### Authorizations: *basic* ##### Request Body schema: application/jsonrequired The structured search criteria. | | | | ------------------------- | --------------------------------------------------------- | | \_\_daily\_email\_enabled | booleanSend a daily email when new results are added. | | asset\_types | Array of stringsThe asset types to include in the search. | | filterrequired | object (Filter)Structured search criteria. | | item\_typesrequired | Array of stringsThe item types to include in the search. | | namerequired | string^.{1,64}$The name of this saved search. | ### Responses **200** Saved search details. **400** There was an error creating your saved search. post/searches https\://api.planet.com/data/v1/searches ### Request samples * Payload Content type application/json Copy Expand all Collapse all `{ "__daily_email_enabled": true, "asset_types": [ "string" ], "filter": { "type": "string" }, "item_types": [ "string" ], "name": "string" }` ### Response samples * 200 * 400 Content type application/json Copy Expand all Collapse all `{ "__daily_email_enabled": false, "_links": { "_self": "string", "thumbnail": "string" }, "created": "2019-08-24T14:15:22Z", "filter": { "type": "string" }, "id": "string", "last_executed": "2019-08-24T14:15:22Z", "name": "string", "updated": "2019-08-24T14:15:22Z" }` ## [](#tag/Item-Search/operation/DeleteSearch)Delete Saved Search Delete an existing saved search. ##### Authorizations: *basic* ##### path Parameters | | | | ------------------ | ------------------------------ | | search\_idrequired | stringSaved search identifier. | ### Responses **204** Saved search successfully deleted. **404** The requested saved search does not exist. delete/searches/{search\_id} https\://api.planet.com/data/v1/searches/{search\_id} ### Response samples * 404 Content type application/json Copy Expand all Collapse all `{ "field": { "property1": [ { "message": "string" } ], "property2": [ { "message": "string" } ] }, "general": [ { "message": "string" } ] }` ## [](#tag/Item-Search/operation/GetSearch)Get Saved Search Get a saved search by id. ##### Authorizations: *basic* ##### path Parameters | | | | ------------------ | ------------------------------ | | search\_idrequired | stringSaved search identifier. | ### Responses **200** Saved search details. **404** The requested saved search does not exist. get/searches/{search\_id} https\://api.planet.com/data/v1/searches/{search\_id} ### Response samples * 200 * 404 Content type application/json Copy Expand all Collapse all `{ "__daily_email_enabled": false, "_links": { "_self": "string", "thumbnail": "string" }, "created": "2019-08-24T14:15:22Z", "filter": { "type": "string" }, "id": "string", "last_executed": "2019-08-24T14:15:22Z", "name": "string", "updated": "2019-08-24T14:15:22Z" }` ## [](#tag/Item-Search/operation/UpdateSearch)Update Saved Search Update an existing saved search. ##### Authorizations: *basic* ##### path Parameters | | | | ------------------ | ------------------------------ | | search\_idrequired | stringSaved search identifier. | ##### Request Body schema: application/jsonrequired The structured search criteria. | | | | ------------------------- | --------------------------------------------------------- | | \_\_daily\_email\_enabled | booleanSend a daily email when new results are added. | | asset\_types | Array of stringsThe asset types to include in the search. | | filterrequired | object (Filter)Structured search criteria. | | item\_typesrequired | Array of stringsThe item types to include in the search. | | namerequired | string^.{1,64}$The name of this saved search. | ### Responses **200** Saved search details. **400** There was an error updating your saved search. put/searches/{search\_id} https\://api.planet.com/data/v1/searches/{search\_id} ### Request samples * Payload Content type application/json Copy Expand all Collapse all `{ "__daily_email_enabled": true, "asset_types": [ "string" ], "filter": { "type": "string" }, "item_types": [ "string" ], "name": "string" }` ### Response samples * 200 * 400 Content type application/json Copy Expand all Collapse all `{ "__daily_email_enabled": false, "_links": { "_self": "string", "thumbnail": "string" }, "created": "2019-08-24T14:15:22Z", "filter": { "type": "string" }, "id": "string", "last_executed": "2019-08-24T14:15:22Z", "name": "string", "updated": "2019-08-24T14:15:22Z" }` ## [](#tag/Item-Search/operation/ExecuteSearch)Run Saved Search Executes a saved search. ##### Authorizations: *basic* ##### path Parameters | | | | ------------------ | ------------------------------ | | search\_idrequired | stringSaved search identifier. | ##### query Parameters | | | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | \_page | stringToken representing a specific page of results. This should never be constructed manually. | | \_page\_size | integer \ \[ 0 .. 250 ]Default: 250Number of results to return per page. This may only be used at the start of pagination. This may not be provided with the "\_page" parameter. | | \_sort | stringDefault: "published desc"Enum: "acquired asc" "acquired desc" "published asc" "published desc"Field and direction to order results by. This may not be provided with the "\_page" parameter. | ### Responses **200** List of items that match search criteria. **404** The requested saved search does not exist. get/searches/{search\_id}/results https\://api.planet.com/data/v1/searches/{search\_id}/results ### Response samples * 200 * 404 Content type application/json Copy Expand all Collapse all `{ "_links": { "_self": "string", "_first": "string", "_next": "string" }, "features": [ { "_links": { "_self": "string", "assets": "string", "thumbnail": "string" }, "_permissions": null, "assets": null, "geometry": { "relation": "intersects", "type": "Polygon" }, "id": "string", "properties": { "acquired": "2019-08-24T14:15:22Z", "anomalous_pixels": 0.1, "black_fill": 0.1, "cloud_cover": 0.1, "columns": 0, "epsg_code": 0, "gsd": 0.1, "item_type": "string", "origin_x": 0, "origin_y": 0, "pixel_resolution": 0, "provider": "string", "published": "2019-08-24T14:15:22Z", "rows": 0, "satellite_id": "string", "sun_azimuth": 0.1, "sun_elevation": 0.1, "updated": "2019-08-24T14:15:22Z", "usable_data": 0.1, "view_angle": 0.1 } } ] }` ## [](#tag/Item-Stats)Item Stats ## [](#tag/Item-Stats/operation/Stats)Search Stats Returns a date bucketed histogram of items matching a filter ##### Authorizations: *basic* ##### Request Body schema: application/jsonrequired The structured search criteria. | | | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | asset\_types | Array of stringsThe asset types to include in the stats. | | filterrequired | object (Filter)Structured search criteria. | | intervalrequired | stringEnum: "hour" "day" "week" "month" "year"The size of the histogram date buckets. | | item\_typesrequired | Array of stringsThe item types to include in the stats. | | utc\_offset | stringA "ISO 8601 UTC offset" (e.g. +01:00 or -08:00) that can be used to adjust the buckets to a users time zone. It is optional. | ### Responses **200** List of item stats aggregated over the interval given. **400** There was an error executing the stats. post/stats https\://api.planet.com/data/v1/stats ### Request samples * Payload Content type application/json Copy Expand all Collapse all `{ "asset_types": [ "string" ], "filter": { "type": "string" }, "interval": "hour", "item_types": [ "string" ], "utc_offset": "string" }` ### Response samples * 200 * 400 Content type application/json Copy Expand all Collapse all `{ "buckets": [ { "count": 0, "start_time": "2019-08-24T14:15:22Z" } ], "interval": "hour", "utc_offset": "string" }`