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

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 any valid 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 this tutorial 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",
      "beta"
   ]
}

Returns all items with a quality category of standard or beta.

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 identify items which may have been republished with improvements or fixes, enabling you to keep your internal catalogs up-to-date and 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, 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

"filter": {  
   "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

"filter": {  
   "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

"filter": {  
   "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 beta.