Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/data/item-search/) # Item Search 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 be 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. - CURL - Python SDK ``` curl -X POST "https://api.planet.com/data/v1/quick-search?_sort=acquired%20asc&_page_size=50" \ -u "$PL_API_KEY:" \ -H "Content-Type: application/json" \ -d @- < Iterator[dict]: filter = data_filter.date_range_filter( field_name="acquired", gte=datetime.fromisoformat("2022-04-14T00:00:00Z"), lte=datetime.fromisoformat("2022-04-15T00:00:00Z"), ) return pl.data.search( ["PSScene"], search_filter=filter, sort="acquired asc", limit=10 ) ``` ### 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](https://docs.planet.com/develop/apis/data/items.md). * `filter`: is your structured search criteria. You can read more on [supported search filters here](#filters). * `asset_types`: is an optional search parameter filtered by [available asset types](https://docs.planet.com/data/imagery.md). * `geometry`: an optional field that contains either GeoJSON or a [Features API reference](https://docs.planet.com/develop/apis/features.md#feature-references). - CURL - Python SDK ``` curl -X POST https://api.planet.com/data/v1/quick-search \ -u "$PL_API_KEY:" \ -H "Content-Type: application/json" \ -d \ '{ "item_types":[ "PSScene" ], "geometry": { "type":"Polygon", "coordinates":[ [ [ 6.067543029785156, 45.859890320433756 ], [ 6.1969757080078125, 45.859890320433756 ], [ 6.1969757080078125, 45.95831029909359 ], [ 6.067543029785156, 45.95831029909359 ], [ 6.067543029785156, 45.859890320433756 ] ] ] }, "filter":{ "type":"AndFilter", "config":[ { "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" ] } ] } }' ``` ``` from datetime import datetime from planet import Planet, data_filter pl = Planet() def quick_search_example() -> Iterator[dict]: """ Example search with several different filters. """ filter = data_filter.and_filter( [ data_filter.date_range_filter( field_name="acquired", gte=datetime.fromisoformat("2022-04-14T00:00:00Z"), lte=datetime.fromisoformat("2022-04-15T00:00:00Z"), ), data_filter.geometry_filter( geom={ "type": "Polygon", "coordinates": [ [ [6.067543029785156, 45.859890320433756], [6.1969757080078125, 45.859890320433756], [6.1969757080078125, 45.95831029909359], [6.067543029785156, 45.95831029909359], [6.067543029785156, 45.859890320433756], ] ], } ), data_filter.string_in_filter( field_name="quality_category", values=["standard"] ), data_filter.asset_filter(asset_types=["ortho_analytic_8b"]), data_filter.range_filter(field_name="cloud_cover", gte=0.0, lte=0.60), data_filter.permission_filter(), ] ) return pl.data.search(["PSScene"], search_filter=filter, limit=10) ``` **Using a Features API reference as the AOI** info See [Features API](https://docs.planet.com/develop/apis/features.md) for more on defining areas of interest. * CURL * Python SDK ``` curl -X POST https://api.planet.com/data/v1/quick-search \ -u "$PL_API_KEY:" \ -H "Content-Type: application/json" \ -d @- < Iterator[dict]: filter = data_filter.date_range_filter( field_name="acquired", gte=datetime.fromisoformat("2022-04-14T00:00:00Z"), lte=datetime.fromisoformat("2022-04-15T00:00:00Z"), ) return pl.data.search( ["PSScene"], geometry="pl:features/my/{COLLECTION_ID}/{FEATURE_ID}", search_filter=filter, limit=10, ) ``` ### 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](https://docs.planet.com/data/imagery.md) and values for a particular item; properties may vary by item type ## 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`. - CURL - Python SDK ``` curl -X POST https://api.planet.com/data/v1/searches \ -u "$PL_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "name": "Saved Search Example", "__daily_email_enabled": false, "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": [ "ortho_analytic_4b_sr" ] } ] } }' ``` ``` from planet import Planet pl = Planet() def new_saved_search() -> dict: filter = data_filter.and_filter( [ data_filter.date_range_filter( field_name="acquired", gte=datetime.fromisoformat("2022-04-14T00:00:00Z"), lte=datetime.fromisoformat("2022-04-15T00:00:00Z"), ), data_filter.asset_filter(asset_types=["ortho_analytic_4b_sr"]), ] ) return pl.data.create_search( item_types=["PSScene"], search_filter=filter, name="Saved search example", enable_email=False, ) ``` ### 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 ## Run a Saved Search To get the results of a saved search, you can call the endpoint below, with the saved search id: * CURL * Python SDK ``` curl https://api.planet.com/data/v1/searches/${SEARCH_ID}/results \ -u "$PL_API_KEY:" ``` ``` from planet import Planet pl = Planet() def get_search_results(search_id: str) -> Iterator[dict]: return pl.data.run_search(search_id) ``` 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: * CURL * Python SDK ``` curl https://api.planet.com/data/v1/searches/ \ -u "$PL_API_KEY:" ``` ``` from planet import Planet pl = Planet() def list_searches() -> Iterator[dict]: return pl.data.list_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** * CURL * Python SDK ``` curl "https://api.planet.com/data/v1/searches/?_page_size=50&_sort=created%20asc&search_type=saved" \ -u "$PL_API_KEY:" ``` ``` from planet import Planet pl = Planet() def list_searches_with_sort() -> Iterator[dict]: return pl.data.list_searches(sort="created asc", search_type="saved") ``` ## Other Supported Search Operations See the [API Reference](https://docs.planet.com/develop/apis/data/reference.md) for more detail and examples of other operations you can run for Saved Searches. ## Filters Search supports four main filter types: * **[Field filters](#field-filters)** allow you to search items by item metadata. There are six field filter types, each supporting different data types and configurations. * **[Asset filters](#asset-filters)** allow you to search items by published asset types. * **[Permission filters](#permission-filters)** allow you to search items based on your download permissions. * **[Logical filters](#logical-filters)** allow you to combine multiple filters using logical operators to further expand or restrict your search. ## Field Filters Field filters support search by item metadata and require a mandatory `field_name` to indicate the relevant property targeted by the filter. Field filters are supported for all item metadata. For more detail on available item metadata, read more on item types and item properties in the [Items & Assets](https://docs.planet.com/develop/apis/data/items.md) tab. A full list of field filter types are described below. | Filter | Description | Supported configs | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- | | [DateRangeFilter](#daterangefilter) | Matches items with a specified timestamp property which falls within a specified range. | `gte`, `gt`, `lt` or `lte` | | [GeometryFilter](#geometryfilter) | Matches items with a footprint that intersects with a specified GeoJSON geometry. | GeoJSON object | | [NumberInFilter](#numberinfilter) | Matches items with a specified numerical property that matches a specified array of numbers. | array of numbers | | [RangeFilter](#rangefilter) | Matches items with a specified numerical property that falls within a specified range. | `gte`, `gt`, `lt` or `lte` | | [StringInFilter](#stringinfilter) | Matches items with a specified string property that fully matches a specified array of strings. Boolean properties are also supported with this filter type. | array of strings | | [UpdateFilter](#updatefilter) | Matches items by changes to a specified property made on or after a specified date, due to a republishing event. | `gt` or `gte` | * `gte`: Stands for "greater than or equal to (Value)". It is used to filter items where the specified property is greater than or equal to the provided value. * `gt`: Stands for "greater than (Value)". This is used similarly to "gte" but excludes the specified value itself. * `lt`: Stands for "less than (Value)". It is used to filter items where the specified property is less than the provided value. * `lte`: Stands for "less than or equal to (Value)". It is similar to "lt" but includes the specified value itself. * `gsd`: Stands for "ground sample distance". It represents the distance between consecutive pixel centers on the ground measured in meters. ### `DateRangeFilter` The `DateRangeFilter` can be used to search any property with a timestamp such as `acquired` or `published`. The filter's configuration is a nested structure with optional keys: `gte`, `gt`, `lt` or `lte`. Each corresponding value is an [RFC 3339](https://tools.ietf.org/html/rfc3339) date. **Example `DateRangeFilter`** ``` { "type": "DateRangeFilter", "field_name": "acquired", "config": { "gt": "2019-12-31T00:00:00Z", "lte": "2020-01-31T00:00:00Z" } } ``` *Returns all items acquired after midnight on Dec 31, 2019 and on or before January 31, 2020.* ### `GeometryFilter` The `GeometryFilter` can be used to search for items with a footprint geometry which intersects with the specified `geometry`. The filter's configuration supports `Point`, `MultiPoint`, `LineString`, `MultiLineString`, `Polygon`, and `MultiPolygon` GeoJSON objects. For best results, the geometry should meet [OpenGIS Simple Features Interface Specification](https://www.opengeospatial.org/standards/sfa) requirements. If an invalid GeoJSON object is supplied, the API will automatically attempt to correct the geometry and return matching search results. An optional relation field can be provided to specify the geometry boolean operation, which can be one of the following values: `intersects`, `contains`, `within`, or `disjoint`. * `intersects` (default) : Returns items whose footprint geometry partially or fully overlaps with the AOI. * `contains` : Returns items where the footprint geometry fully encloses the AOI. * `disjoint` : Returns items whose footprint geometry does not intersect with the AOI in any way. * `within` : Returns items whose entire footprint geometry is fully contained within the AOI. tip Use the `geometry` field with [Features API](https://docs.planet.com/develop/apis/features.md) references. **Example `GeometryFilter`** ``` { "type": "GeometryFilter", "field_name": "geometry", "relation": "intersects", "config": { "type": "Polygon", "coordinates": [ [ [-120.27282714843749, 38.348118547988065], [-120.27282714843749, 38.74337300148126], [-119.761962890625, 38.74337300148126], [-119.761962890625, 38.348118547988065], [-120.27282714843749, 38.348118547988065] ] ] } } ``` ### `NumberInFilter` The `NumberInFilter` can be used to search for items with numerical properties. It is useful for matching fields such as `gsd`. The filter's configuration is an array of numbers. **Example `NumberInFilter`** ``` { "type": "NumberInFilter", "field_name": "gsd", "config": [3] } ``` *Returns all items with a* `gsd` *value of 3.* ### `RangeFilter` The `RangeFilter` can be used to search for items with numerical properties. It is useful for matching fields that have a continuous range of values such as `cloud_cover` or `view_angle`. The filter's configuration is a nested structure with optional keys: `gte`, `gt`, `lt` or `lte`. **Example `RangeFilter`** ``` { "type": "RangeFilter", "field_name": "cloud_cover", "config": { "lte": 0.1 } } ``` *Returns all items with* `cloud_cover` *less than or equal to 10%.* ### `StringInFilter` The `StringInFilter` can be used to search for items with string properties such as `instrument` or `quality_category`. Boolean properties such as `ground_control` are also supported with the `StringInFilter`. The filter’s configuration is an array of strings. When multiple values are specified, an implicit “or” logic is applied, returning items with the given field matching any of the values. **Example `StringInFilter`** ``` { "type": "StringInFilter", "field_name": "quality_category", "config": ["standard", "test"] } ``` *Returns all items with a quality category of* `standard` *or* `test`*.* ### `UpdateFilter` The `UpdateFilter` can be used to filter items by changes to a specified metadata field value made after a specified date, due to a republishing event. This feature allows you to identify items that may have been republished with improvements or fixes, enabling you to keep your internal catalogs up-to-date, and to make more informed redownload decisions. The filter works for all items published on or after April 10, 2020. The filter accepts a field name and a `gt` or `gte` timestamp. While any field name may be specified, the primary fields which may be impacted by quality, usability, or rectification improvements are `geometry`, `quality_category`, `ground_control`, `publishing_stage`, and UDM or UDM2 fields (including `visible_percent`, `clear_percent`, `cloud_percent`, `heavy_haze_percent`, `light_haze_percent`, `snow_ice_percent`, `shadow_percent`, `cloud_cover`, `black_fill`, `usable_data`, and `anomalous_pixels`). **Example `UpdateFilter`** ``` { "type": "UpdateFilter", "field_name": "ground_control", "config": { "gt": "2020-04-15T00:00:00Z" } } ``` *Returns all items with a `ground_control` value which has changed on or after April 15, 2020.* To filter items by field value changes to multiple fields (For example, changes to `ground_control` *or* `quality_category`), multiple `UpdateFilters` can be used within a logical [AndFilter](#andfilter) or [OrFilter](#orfilter). ## Asset filters The `AssetFilter` can be used to search for items which have published a specified `asset_type`. This filter is commonly used to filter items by published asset types which: * May be published at delay after an item's first publish. `analytic_sr`, for instance, may be published up to 12 hours after an item first becomes available. * May not be available for the full catalog. `udm2`, for instance, is only available globally through July 2018. The filter's configuration is a list of asset types. When multiple values are specified, an implicit “or” logic is applied, returning all items which include any of the listed asset types. An [`AndFilter`](#andfilter) can be used to filter items by multiple asset types. ``` { "type": "AndFilter", "config": [ { "type": "AssetFilter", "config": ["analytic_sr"] }, { "type": "AssetFilter", "config": ["udm2"] } ] } ``` *Returns all items with published `analytic_sr` and `udm2` assets.* ## Permission Filters The `PermissionFilter` can be used to limit results to items that a user has permission to download, taking into consideration area of interest, time of interest, item type, and asset type download permissions. Its recommended configuration is an array which includes the `assets:download` permission. **Example `PermissionFilter`** ``` { "type": "PermissionFilter", "config": ["assets:download"] } ``` *Returns all items within the requester’s area and time of interest which have published assets the requester has permission to download.* **Tips for Using the `PermissionFilter` with Logical Filters:** * `OrFilter`: We *do not* recommend nesting the `assets:download` `PermissionFilter` in an `OrFilter`. In this context, it will continue to filter all results by AOI, TOI, item type, and asset type permissions. * `NotFilter`: We *do not* recommend not nesting the `assets:download` `PermissionFilter` in a `NotFilter`. This search will return no results. To filter items by published assets, use the `AssetFilter`. To limit those results by items with assets you have permission to download, combine the `AssetFilter` with the `assets:download` `PermissionFilter` using an `AndFilter`. ## Logical Filters Logical filters allow you to search on complex criteria, expressed across multiple fields, with a variety of conditions. You will most likely want to start your search with a single logical filter. The most common use of logical filters is a top-level `AndFilter` to ensure criteria across all field and permission filters are met. | Filter | Description | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | [AndFilter](#andfilter) | Matches items with properties or permissions which match *all* the nested filters. | | [OrFilter](#orfilter) | Matches items with properties or permissions which match *at least one* of the nested filters. | | [NotFilter](#notfilter) | Matches items with properties or permissions which *do not match* the nested filter. This filter type supports a single nested filter. | ### `AndFilter` The `AndFilter` can be used to limit results to items with properties or permissions which match *all* nested filters. It is most commonly used as a top-level filter to ensure criteria across all field and permission filters are met. **Example `AndFilter`** ``` { "type": "AndFilter", "config": [ { "type": "DateRangeFilter", "field_name": "acquired", "config": { "gte": "2020-01-01T00:00:00Z", "lte": "2020-01-31T00:00:00Z" } }, { "type": "StringInFilter", "field_name": "ground_control", "config": ["true"] }, { "type": "AssetFilter", "config": ["analytic_sr"] }, { "type": "PermissionFilter", "config": ["assets:download"] } ] } ``` *Returns all orthorectified items that were acquired from January 1st, 2020 through January 31st, 2020, have a published `analytic_sr` asset, and meet the requester's AOI, TOI, and item type/asset type download permissions.* ### `OrFilter` The `OrFilter` can be used to match items with properties or permissions which match *at least one* of the nested filters. **Example `OrFilter`** ``` { "type": "OrFilter", "config": [ { "type": "RangeFilter", "field_name": "visible_percent", "config": { "gte": 90 } }, { "type": "RangeFilter", "field_name": "usable_data", "config": { "gte": 0.9 } } ] } ``` *Returns all items that for which* `visible_percent` *is greater or equal to 90, or* `usable_data` *is greater or equal to 0.90. This example could be useful for a query of older items which may or may not have a `udm2` metadata available.* #### `NotFilter` The `NotFilter` can be used to match items with properties or permissions which *do not match* the nested filters. This filter only supports a single nested filter. Multiple `NotFilter` can be nested within an `AndFilter` to filter across multiple fields or permission values. **Example `NotFilter`** ``` { "type": "NotFilter", "config": { "type": "StringInFilter", "field_name": "quality_category", "config": ["test"] } } ``` *Filters out test items to return all items which have a* `quality_category` *of* `standard` *or* `test`*.* ## Stats The stats endpoint provides a quick way to determine the number of items which meet your search specifications. This endpoint allows you to specify a time interval and search filter and returns a histogram of item counts, grouped by interval, which match your filter criteria. This endpoint can be used to answer questions such as: * *How does availability of imagery with less than 10 percent cloud cover change seasonally in Jakarta?* * *How deep is the Planet 2019 SkySat archive over Shanghai?* * *How many items which meet my search criteria are published each hour?* ### Request Body The body of a stats request must include a search filter and time interval. * `filter` (required): is the search criteria. For more on supported filters, see the [Filters section](#filters). * `interval` (required): specifies the time interval of the returned histogram buckets; `hour`, `day`, `week`, `month`, or `year` * `item_types` (required): limits results by item type(s) * `utc_offset` (optional): offsets the start time of your histogram buckets to match your desired timezone (ISO 8601 UTC offset, ex. +1h or -8h) - CURL - Python SDK ``` curl -X POST https://api.planet.com/data/v1/stats \ -u "$PL_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "item_types": [ "PSScene" ], "interval": "day", "filter": { "type":"AndFilter", "config":[ { "type":"DateRangeFilter", "field_name":"acquired", "config":{ "gte":"2022-03-01T00:00:00Z", "lte":"2022-03-07T00:00:00Z" } }, { "type": "AssetFilter", "config": [ "ortho_analytic_8b" ] } ] }, "utc_offset": "-8h" }' ``` ``` from planet import Planet pl = Planet() def get_stats() -> dict: filter = data_filter.and_filter( [ data_filter.date_range_filter( field_name="acquired", gte=datetime.fromisoformat("2022-04-14T00:00:00Z"), lte=datetime.fromisoformat("2022-04-15T00:00:00Z"), ), data_filter.asset_filter(asset_types=["ortho_analytic_8b"]), ] ) return pl.data.get_stats( item_types=["PSScene"], interval="day", search_filter=filter ) ``` *Request for counts of all PlanetScope 4-band items with analytic\_sr assets acquired between February 1, 2020 and February 7, 2020, grouped by day in Pacific Standard Time.* The stats response returns an array of stats bucket results, each of which include a bucket start time and count of items which meet the request’s filter criteria.