The Data API supports two main types of search: Quick Search and Saved Search
- Quick Search is recommended for one-off, ad-hoc searches of the Planet catalog.
- Saved Search is recommended for searches you use frequently. Saved searches are persisted for the duration of your access period and can be easily retrieved and executed for repeat use. You can also enable Saved Search email notifications to receive daily updates with newly published imagery which meets your search criteria.
Quick Search¶
Quick search is the easiest way to search the Planet catalog for ad-hoc, everyday use. Quick searches will remain available via the API for repeat use for 30 days.
Query Parameters¶
Quick search supports several query parameters to format your results.
_page_size: limits the number of results to returned per page. It may only be used at the start of pagination._sort: allows you to sort search results by ascending or descending acquired time or published time. Supported values areacquired asc,acquired desc,published asc, andpublished desc. When unspecified,published descis the default value.
Example Query Parameters
https://api.planet.com/data/v1/quick-search?_sort=acquired asc&_page_size=50
Request Body¶
The body of a quick-search must include item type(s) and a filter.
item_types: is a list of item types filtered by your search. You can read more on available item types here.filter: is your structured search criteria. You can read more on supported search filters here.asset_types: is an optional search parameter filterered by available asset types here.
Example Request Body
POST https://api.planet.com/data/v1/quick-search
{
"item_types":[
"PSScene"
],
"filter":{
"type":"AndFilter",
"config":[
{
"type":"GeometryFilter",
"field_name":"geometry",
"config":{
"type":"Polygon",
"coordinates":[
[
[
6.067543029785156,
45.859890320433756
],
[
6.1969757080078125,
45.859890320433756
],
[
6.1969757080078125,
45.95831029909359
],
[
6.067543029785156,
45.95831029909359
],
[
6.067543029785156,
45.859890320433756
]
]
]
}
},
{
"type":"DateRangeFilter",
"field_name":"acquired",
"config":{
"gte":"2022-04-14T00:00:00Z",
"lte":"2022-04-15T00:00:00Z"
}
},
{
"type":"StringInFilter",
"field_name":"quality_category",
"config":[
"standard"
]
},
{
"type":"AssetFilter",
"config":[
"ortho_analytic_8b"
]
},
{
"type":"RangeFilter",
"config":{
"gte":0,
"lte":0.6
},
"field_name":"cloud_cover"
},
{
"type":"PermissionFilter",
"config":[
"assets:download"
]
}
]
}
}
Response Schema¶
A Quick Search response includes metadata and links for items matching your search criteria. The number of results included is based on the page size and additional links are provided to enable pagination.
Page links reference different pages of the returned search results.
_self: references the current page of search results_first: references the first page of the search results_next: references the next page of the search results
Features include additional detail on each item returned in the search results.
_links:_self: is an endpoint for this specific item resultassets: references a set of asset activation links for each published asset of the itemthumbnail: is a Tile Service API endpoint, which hosts a thumbnail of the item
_permissions: lists all of your asset download permissions which apply to this particular itemassets: lists all the assets that have been published for this particular itemgeometry: is the footprint geometry for this particular itemid: is the item id for this particular itemproperties: lists all metadata fields and values for a particular item; properties may vary by item type
Example Response
{
"_links": {
"_first": "https://api.planet.com/data/v1/searches/5ff575bd0a8c4b3aa108c6bfaa529587/results?_page=eyJwYWdlX3NpemUiOiAyNTAsICJzb3J0X2J5IjogInB1Ymxpc2hlZCIsICJzb3J0X2Rlc2MiOiB0cnVlLCAic29ydF9zdGFydCI6IG51bGwsICJzb3J0X2xhc3RfaWQiOiBudWxsLCAic29ydF9wcmV2IjogZmFsc2UsICJxdWVyeV9wYXJhbXMiOiB7fX0%3D",
"_next": "https://api.planet.com/data/v1/searches/5ff575bd0a8c4b3aa108c6bfaa529587/results?_page=eyJwYWdlX3NpemUiOiAyNTAsICJzb3J0X2J5IjogInB1Ymxpc2hlZCIsICJzb3J0X2Rlc2MiOiB0cnVlLCAic29ydF9zdGFydCI6ICIyMDIyLTA0LTE1VDE3OjA0OjM4LjAwMDAwMFoiLCAic29ydF9sYXN0X2lkIjogIjIwMjIwNDE0XzEwMTkxNl83OV8yNDBhIiwgInNvcnRfcHJldiI6IGZhbHNlLCAicXVlcnlfcGFyYW1zIjoge319",
"_self": "https://api.planet.com/data/v1/searches/5ff575bd0a8c4b3aa108c6bfaa529587/results?_page=eyJwYWdlX3NpemUiOiAyNTAsICJzb3J0X2J5IjogInB1Ymxpc2hlZCIsICJzb3J0X2Rlc2MiOiB0cnVlLCAic29ydF9zdGFydCI6IG51bGwsICJzb3J0X2xhc3RfaWQiOiBudWxsLCAic29ydF9wcmV2IjogZmFsc2UsICJxdWVyeV9wYXJhbXMiOiB7fX0%3D"
},
"features": [
{
"_links": {
"_self": "https://api.planet.com/data/v1/item-types/PSScene/items/20220414_101919_00_240a",
"assets": "https://api.planet.com/data/v1/item-types/PSScene/items/20220414_101919_00_240a/assets/",
"thumbnail": "https://tiles.planet.com/data/v1/item-types/PSScene/items/20220414_101919_00_240a/thumb"
},
"_permissions": [
"assets.basic_analytic_4b:download",
"assets.basic_analytic_4b_rpc:download",
"assets.basic_analytic_4b_xml:download",
"assets.basic_analytic_8b:download",
"assets.basic_analytic_8b_xml:download",
"assets.basic_udm2:download",
"assets.ortho_analytic_4b:download",
"assets.ortho_analytic_4b_sr:download",
"assets.ortho_analytic_4b_xml:download",
"assets.ortho_analytic_8b:download",
"assets.ortho_analytic_8b_sr:download",
"assets.ortho_analytic_8b_xml:download",
"assets.ortho_udm2:download",
"assets.ortho_visual:download"
],
"assets": [
"basic_analytic_4b",
"basic_analytic_4b_rpc",
"basic_analytic_4b_xml",
"basic_analytic_8b",
"basic_analytic_8b_xml",
"basic_udm2",
"ortho_analytic_4b",
"ortho_analytic_4b_sr",
"ortho_analytic_4b_xml",
"ortho_analytic_8b",
"ortho_analytic_8b_sr",
"ortho_analytic_8b_xml",
"ortho_udm2",
"ortho_visual"
],
"geometry": {
"coordinates": [
[
[
5.95456036106261,
45.903977558439216
],
[
5.894418694239513,
45.71873410766648
],
[
6.336370462891481,
45.64820921278849
],
[
6.397913442243694,
45.83198472407456
],
[
5.95456036106261,
45.903977558439216
]
]
],
"type": "Polygon"
},
"id": "20220414_101919_00_240a",
"properties": {
"acquired": "2022-04-14T10:19:19.007955Z",
"anomalous_pixels": 0,
"clear_confidence_percent": 98,
"clear_percent": 97,
"cloud_cover": 0,
"cloud_percent": 0,
"ground_control": true,
"gsd": 4,
"heavy_haze_percent": 0,
"instrument": "PSB.SD",
"item_type": "PSScene",
"light_haze_percent": 0,
"pixel_resolution": 3,
"provider": "planetscope",
"published": "2022-04-15T17:04:44Z",
"publishing_stage": "finalized",
"quality_category": "standard",
"satellite_azimuth": 103.3,
"satellite_id": "240a",
"shadow_percent": 0,
"snow_ice_percent": 3,
"strip_id": "5570053",
"sun_azimuth": 150.2,
"sun_elevation": 50.3,
"updated": "2022-04-15T20:53:48Z",
"view_angle": 3.1,
"visible_confidence_percent": 74,
"visible_percent": 100
},
"type": "Feature"
},
{
"_links": {
"_self": "https://api.planet.com/data/v1/item-types/PSScene/items/20220414_101916_79_240a",
"assets": "https://api.planet.com/data/v1/item-types/PSScene/items/20220414_101916_79_240a/assets/",
"thumbnail": "https://tiles.planet.com/data/v1/item-types/PSScene/items/20220414_101916_79_240a/thumb"
},
"_permissions": [
"assets.basic_analytic_4b:download",
"assets.basic_analytic_4b_rpc:download",
"assets.basic_analytic_4b_xml:download",
"assets.basic_analytic_8b:download",
"assets.basic_analytic_8b_xml:download",
"assets.basic_udm2:download",
"assets.ortho_analytic_4b:download",
"assets.ortho_analytic_4b_sr:download",
"assets.ortho_analytic_4b_xml:download",
"assets.ortho_analytic_8b:download",
"assets.ortho_analytic_8b_sr:download",
"assets.ortho_analytic_8b_xml:download",
"assets.ortho_udm2:download",
"assets.ortho_visual:download"
],
"assets": [
"basic_analytic_4b",
"basic_analytic_4b_rpc",
"basic_analytic_4b_xml",
"basic_analytic_8b",
"basic_analytic_8b_xml",
"basic_udm2",
"ortho_analytic_4b",
"ortho_analytic_4b_sr",
"ortho_analytic_4b_xml",
"ortho_analytic_8b",
"ortho_analytic_8b_sr",
"ortho_analytic_8b_xml",
"ortho_udm2",
"ortho_visual"
],
"geometry": {
"coordinates": [
[
[
5.999163695183379,
46.04148258266974
],
[
5.938510217497761,
45.85631756620983
],
[
6.381913829835591,
45.78592106408607
],
[
6.443192005557489,
45.969523303104324
],
[
5.999163695183379,
46.04148258266974
]
]
],
"type": "Polygon"
},
"id": "20220414_101916_79_240a",
"properties": {
"acquired": "2022-04-14T10:19:16.797043Z",
"anomalous_pixels": 0,
"clear_confidence_percent": 98,
"clear_percent": 96,
"cloud_cover": 0,
"cloud_percent": 0,
"ground_control": true,
"gsd": 4,
"heavy_haze_percent": 0,
"instrument": "PSB.SD",
"item_type": "PSScene",
"light_haze_percent": 0,
"pixel_resolution": 3,
"provider": "planetscope",
"published": "2022-04-15T17:04:38Z",
"publishing_stage": "finalized",
"quality_category": "standard",
"satellite_azimuth": 103.4,
"satellite_id": "240a",
"shadow_percent": 0,
"snow_ice_percent": 4,
"strip_id": "5570053",
"sun_azimuth": 150.4,
"sun_elevation": 50.2,
"updated": "2022-04-15T20:53:42Z",
"view_angle": 3.1,
"visible_confidence_percent": 73,
"visible_percent": 100
},
"type": "Feature"
}
],
"type": "FeatureCollection"
}
Saved Search¶
Saved Search is a helpful option for managing searches that you use frequently. Saved Searches can be easily retrieved and executed for repeated use and optionally support daily email notifications for newly published imagery which meets your search criteria.
Request Body¶
In addition to item types and filters required in a quick-search, the body of a saved search requires a name. There is also an option to enable daily email notifications for new imagery updates.
name: name of the Saved Search__daily_email_enabled: if set totrue, an email will be delivered daily between 00:00:00 and 00:02:00 UTC with an Explorer link to all imagery that meets your search criteria published within the last 24 hours. By default, this value will be set tofalse.
Example Request Body
{
"name": "Saved Search Example",
"__daily_email_enabled": true,
"item_types": [
"PSScene"
],
"filter": {
"type":"AndFilter",
"config":[
{
"type":"DateRangeFilter",
"field_name":"acquired",
"config":{
"gte":"2020-01-01T00:00:00Z",
"lte":"2020-01-31T00:00:00Z"
}
},
{
"type": "AssetFilter",
"config": [
"analytic_sr"
]
}
]
}
}
Response Schema¶
The Saved Search response includes all details of the saved search:
__daily_email_enabled:trueif emails are enabled, andfalseif not enabled_self: is an endpoint for the specific search_results: is an endpoint to execute the saved search and see resultscreated: is the timestamp when the saved search was createdfilter: lists the structured search criteriaid: is the saved search identifierlast_executed: is the timestamp when the saved search was last executedname: is the name of the saved searchupdated: is the timestamp when the saved search was last updated
Example Response
{
"__daily_email_enabled": true,
"_links": {
"_self": "https://api.planet.com/data/v1/searches/3b5cc5df661b4ff89ca70dfdeede238f",
"results": "https://api.planet.com/data/v1/searches/3b5cc5df661b4ff89ca70dfdeede238f/results"
},
"created": "2020-03-03T20:40:36.825325Z",
"filter": {
"config": [
{
"config": {
"gte": "2020-01-01T00:00:00Z",
"lte": "2020-01-31T00:00:00Z"
},
"field_name": "acquired",
"type": "DateRangeFilter"
},
{
"config": [
"analytic_sr"
],
"type": "AssetFilter"
}
],
"type": "AndFilter"
},
"id": "3b5cc5df661b4ff89ca70dfdeede238f",
"item_types": [
"PSScene"
],
"last_executed": null,
"name": "Saved Search Example",
"search_type": "saved",
"updated": "2020-03-03T20:40:36.825325Z"
}
Run a Saved Search¶
To get the results of a saved search, you can call the endpoint below, with the saved search id:
https://api.planet.com/data/v1/searches/{search_id}/results
This endpoint accepts the same query parameters (_page_size, sort) and returns the same response schema as the quick-search endpoint.
List Searches¶
To get a list of historical searches, you can call the endpoint below:
https://api.planet.com/data/v1/searches
This endpoint supports the _page and _page_size query parameters, in addition to:
_sort: allows you to sort searches by ascending or descending created time. Supported values arecreated ascandcreated desc. When unspecified,created descis the default value. This parameter may not be used with the_pageparameter.search_type: allows you to filter searches by search type. Supported values areany,quick, andsaved. When unspecified,anyis the default value, returning all searches.
Example Query Parameters
https://api.planet.com/data/v1/searches?_page_size=50&_sort=created asc&search_type=saved
Other Supported Search Operations¶
See our API Reference documentation for more detail and examples of other operations you can run for Saved Searches.
We are continually working to improve our technical documentation and support. Please help by sharing your experience with us.