Skip to main content

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 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 -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 @- <<EOF
{
  "item_types":[
    "PSScene"
  ],
  "filter": {
    "type":"DateRangeFilter",
    "field_name":"acquired",
    "config":{
        "gte":"2022-04-14T00:00:00Z",
        "lte":"2022-04-15T00:00:00Z"
    }
  }
}
EOF

Request Body​

The body of a quick search must include item type(s) and a filter.

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"
            ]
         }
      ]
   }
}'

Using a Features API reference as the AOI

info

See Features API for more on defining areas of interest.

curl -X POST https://api.planet.com/data/v1/quick-search \
  -u "$PL_API_KEY:" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "item_types":[
      "PSScene"
  ],
  "geometry": {
    "type": "ref",
    "content": "pl:features/my/${COLLECTION_ID}/${FEATURE_ID}"
  },
  "filter": {
    "type":"DateRangeFilter",
    "field_name":"acquired",
    "config":{
        "gte":"2022-04-14T00:00:00Z",
        "lte":"2022-04-15T00:00:00Z"
    }
  }
}
EOF

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

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 -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"
             ]
      	  }
       ]
    }
}'

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

To get the results of a saved search, you can call the endpoint below, with the saved search id:

curl https://api.planet.com/data/v1/searches/${SEARCH_ID}/results \
  -u "$PL_API_KEY:"

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 https://api.planet.com/data/v1/searches/ \
  -u "$PL_API_KEY:"

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 "https://api.planet.com/data/v1/searches/?_page_size=50&_sort=created%20asc&search_type=saved" \
  -u "$PL_API_KEY:"

Other Supported Search Operations​

See the API Reference for more detail and examples of other operations you can run for Saved Searches.

Filters​

Search supports four main filter types:

  • 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 allow you to search items by published asset types.
  • Permission filters allow you to search items based on your download permissions.
  • 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 tab.

A full list of field filter types are described below.

FilterDescriptionSupported configs
DateRangeFilterMatches items with a specified timestamp property which falls within a specified range.gte, gt, lt or lte
GeometryFilterMatches items with a footprint that intersects with a specified GeoJSON geometry.GeoJSON object
NumberInFilterMatches items with a specified numerical property that matches a specified array of numbers.array of numbers
RangeFilterMatches items with a specified numerical property that falls within a specified range.gte, gt, lt or lte
StringInFilterMatches 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
UpdateFilterMatches 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 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 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 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 or 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 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.

FilterDescription
AndFilterMatches items with properties or permissions which match all the nested filters.
OrFilterMatches items with properties or permissions which match at least one of the nested filters.
NotFilterMatches 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.
  • 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 -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"
}'

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.

Last updated on