Searches & Filtering

The search APIs allow for both simple and complex item searches. Complex searches support boolean conditions, multiple values, geometries using GeoJSON and others. You can also save, retrieve,and execute searches that you use frequently for easy use later.

The Planet API persists every search to prevent having to repeat the original search arguments in a POST payload when paginating across a result sets. Unlike saved searches, quick searches are not guaranteed to persist. For those wishing to exclude quick-searches from their list of searches, use the search_type parameter with the value of saved.

As a convenience for creating ad-hoc queries, the quick-search operation accepts a payload format similar to a saved search except that the name parameter is not required and the search results are returned immediately.

Search Filters

Every search requires a filter that can be one of many different types. By utilizing AndFilter or OrFilter, complex criteria can be expressed across multiple fields, with a variety of conditions.

Filters are divided into logical filters and field filters. All field filters require a field_name and a filter-specific config. Logical filters do not target any specific field and operate on a nested filter, as in the case of the NotFilter, or on a list of filters as with AndFilter and OrFilter.

Logical Filters

In most cases, you'll want to start your search with a single logical filter. Though it is perfectly legal to have a search consisting of a single field filter, multiple filters are a common requirement. The most common case is to have a top-level AndFilter housing a list of individual field filters.

Filter Description
AndFilter Matches any Item that matches all the nested filters
OrFilter Matches any Item that matches any of the nested filters
NotFilter Inverts a list of nested filters

Example AndFilter

{  
   "type":"AndFilter",
   "config":[  
      {  
         "type":"DateRangeFilter",
         "field_name":"acquired",
         "config":{  
            "gte":"2016-02-01T00:00:00Z",
            "lte":"2016-03-01T00:00:00Z"
         }
      },
      {  
         "type":"StringInFilter",
         "field_name":"satellite_id",
         "config":[  
            "RapidEye-3"
         ]
      }
   ]
}

Field Filters

Field filters have a mandatory field_name which indicates the relevant property targeted by the filter.

Filter Description Supported Configs
DateRangeFilter Matches dates that fall within a range. gte, gt, lt or lte
GeometryFilter Matches using a GeoJSON geometry. GeoJSON object
NumberInFilter Matches any number within an array of provided numbers. array of numbers
RangeFilter Matches numbers that fall within a range. gte, gt, lt or lte
StringInFilter Matches any string within an array of provided strings. array of strings
PermissionFilter Matches any permission within an array of provided permissions. array of permission names

DateRangeFilter

The filter's config value is a nested structure with optional keys for each of gte, gt, lt or lte. Each corresponding value is an RFC 3339 date.

Example DateRangeFilter

 {  
   "type":"DateRangeFilter",
   "field_name":"acquired",
   "config":{  
      "gt":"2016-01-01T00:00:00Z",
      "lte":"2016-03-01T00:00:00Z"
   }
}

GeometryFilter

The filter's config value may be any valid GeoJSON object.

Pro Tip

If you are confused about this, try this tutorial.

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

NumberInFilter

The filter's config value is an array of numbers. Generally useful for matching an enumerated field.

Example NumberInFilter

 {  
   "type":"NumberInFilter",
   "field_name":"bit_depth",
   "config":[  
      12,
      13,
      14
   ]
}

RangeFilter

The filter's config value is a nested structure with optional keys for each of gte, gt, lt or lte. Each corresponding value must be a number.

Example RangeFilter

 {  
   "type":"RangeFilter",
   "field_name":"pixel_resolution",
   "config":{  
      "gte":5,
      "lt":10
   }
}

StringInFilter

The filter's config value is an array of strings.

Example StringInFilter

 {  
   "type":"StringInFilter",
   "field_name":"id",
   "config":[  
      "20151201_160047_2059806_RapidEye-3",
      "20151201_160106_2059304_RapidEye-3"
   ]
}

PermissionFilter

The filter's config value is an array of permission types.

Example PermissionFilter

 {  
   "type":"PermissionFilter",
   "config":[  
      "assets:download",
      "assets.visual:download",
      "assets.analytic:download"
   ]
}