Search 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.

Filter	Description	Supported Configs
DateRangeFilter	Matches items with a specified timestamp property which falls within a specified range.	`gte`, `gt`, `lt` or `lte`
GeometryFilter	Matches items with a footprint that intersects with a specified GeoJSON geometry.	GeoJSON object
NumberInFilter	Matches items with a specified numerical property that matches a specified array of numbers.	array of numbers
RangeFilter	Matches items with a specified numerical property that falls within a specified range.	`gte`, `gt`, `lt` or `lte`
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	Matches items by changes to a specified property made on after a specified date, due to a republishing event.	`gt` or `gte`

gte: Stands for "greater than or equal to (Value)". It's used to filter items where the specified property is greater than or equal to the provided value.
gt: Stands for "greater than (Value)". It's used similarly to "gte" but excludes the specified value itself.
lt: Stands for "less than (Value)". It's used to filter items where the specified property is less than the provided value.
lte: Stands for "less than or equal to (Value)". It's 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 on 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 object. 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.

Pro Tip

Check out the Planet School tutorial GeoJSON and Areas of Interest (AOIs) for more on defining an area of interest.

Example GeometryFilter

{
   "type":"GeometryFilter",
   "field_name":"geometry",
   "config":{
      "type":"Polygon",
      "coordinates":[
         [
            [
               -120.27282714843749,
               38.348118547988065
            ],
            [
               -120.27282714843749,
               38.74337300148126
            ],
            [
               -119.761962890625,
               38.74337300148126
            ],
            [
               -119.761962890625,
               38.348118547988065
            ],
            [
               -120.27282714843749,
               38.348118547988065
            ]
         ]
      ]
   }
}

Returns all items which intersect with the specified geometry.

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 (i.e. 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.

Caution

We are deprecating support for asset type permission filters (i.e. assets.<asset_type>:download).

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. In most cases, you’ll want to start your search with a single logical filter.

The most common use of logical filters is to have a top-level AndFilter to ensure criteria across all field and permission filters are met.

Filter	Description
AndFilter	Matches items with properties or permissions which match all the nested filters.
OrFilter	Matches items with properties or permissions which match at least one of the nested filters.
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.90
         }
      }
   ]
}

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 NotFilters 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.

We are continually working to improve our technical documentation and support. Please help by sharing your experience with us.

Send Us Your Feedback

Search Filters

last updated: September 04, 2024

Field Filters¶

DateRangeFilter¶

GeometryFilter¶

NumberInFilter¶

RangeFilter¶

StringInFilter¶

UpdateFilter¶

Asset Filters¶

Permission Filters¶

Logical Filters¶

AndFilter¶

OrFilter¶

NotFilter¶