Quick & Saved Search

last updated: March 27, 2024

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 are acquired asc, acquired desc, published asc, and published desc. When unspecified, published desc is 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.

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 result
    • assets: references a set of asset activation links for each published asset of the item
    • thumbnail: 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 item
  • assets: lists all the assets that have been published for this particular item
  • geometry: is the footprint geometry for this particular item
  • id: is the item id for this particular item
  • properties: 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 to true, 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 to false.

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: true if emails are enabled, and false if not enabled
  • _self: is an endpoint for the specific search
  • _results: is an endpoint to execute the saved search and see results
  • created: is the timestamp when the saved search was created
  • filter: lists the structured search criteria
  • id: is the saved search identifier
  • last_executed: is the timestamp when the saved search was last executed
  • name: is the name of the saved search
  • updated: 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"
}

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 are created asc and created desc. When unspecified, created desc is the default value. This parameter may not be used with the _page parameter.
  • search_type: allows you to filter searches by search type. Supported values are any, quick, and saved. When unspecified, any is 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.


Rate this guide: