Log inSuggest an edit

Search Endpoint

Table of Contents

  1. General Concepts
  2. Search Filters

The Search API allows for the creation and management of structured search objects across item types.

1. General Concepts

The search APIs allow users to express more complex searches. They allow users to express boolean conditions, filter on multiple values, and to query using large geometries.

We persist every search in order to spare users from having to repeat their original search arguments in a post payload when paginating across result sets. For users that wish to execute ad-hoc queries, this would impose additional overhead of first creating a search, obtaining its ID and then issuing a second request to retrieve the search results.

As a convenience for creating ad-hoc queries, the Quick Search operation accepts a payload format similar to a Saved Search with the exception that a name is not required and that results are returned immediately.

Unlike saved searches, quick searches are not guaranteed to persist. For those wishing to exclude quick searches from the list of searches, use the search_type parameter with a value of saved.

2. Search Filters

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

Filters can be 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.

FilterDescription
NotFilterInverts a list of nested filters.
AndFilterMatches any Item that matches all the nested filters.
OrFilterMatches any Item that matches any of the nested filters.

Example:

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

Field Filters

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

FilterDescription
DateRangeFilterMatches dates that fall within a range.
GeometryFilterMatches using GeoJSON geometry.
NumberInFilterMatches any number within the array of provided numbers.
RangeFilterMatches numbers that fall within a range.
StringInFilterMatches any string within the array of provided strings.

Examples

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.

{
  "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.

{
  "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.

{
  "type": "NumberInFilter",
  "field_name": "bit_depth",
  "config": [12]
}
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.

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

StringInFilter

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

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

Special Filters

Permission Filter

The PermissionFilter allows for filtering data according to the active user's permissions to that data.

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

The config property accepts an array of permission names. Examples of valid values are:

  • assets:download: One or more assets types may be activated and downloaded.
  • assets.visual:download: Visual assets may be activated and downloaded.
  • assets.analytic:download: Analytic assets may be activated and downloaded.

Common Tasks

Posting to the create search API endpoint creates a saved search.

POST https://api.planet.com/data/v1/searches/

Request:

{
  "name": "My Funky Search",
  "item_types": ["PSOrthoTile"],
  "filter": {
    "type": "OrFilter",
    "config": [
      {
        "field_name": "published",
        "config": {
          "gte": "2015-10-01T00:00:00Z"
        },
        "type": "DateRangeFilter"
      }
    ]
  }
}

Response:

{
  "created": "2016-01-01T00:00:00Z",
  "updated": null,
  "last_executed": null,
  "filter": { ... },
  "id": "a5dbfae0a5dbfae0",
  "name": "My Funky Search"
}

In the future, if you need to refer to a previously created search, use the ListSearches operation to obtain a list of all saved searches:

GET https://api.planet.com/data/v1/searches/?search_type=saved

Response:

{
  "searches": [
    {
      "created": "2016-01-01T00:00:00Z",
      "filter": { ... },
      "id": "a5dbfae0a5dbfae0",
      "item_types": ["PSOrthoTile"],
      "last_executed": null,
      "name": "My Funky Search",
      "updated": "2016-01-01T00:00:00Z",
      "updated": null
    }
  ],
  ...
}

Once a search has been created, you can use the generated identifier (see the id attribute within the response). To execute the query:

GET https://api.planet.com/data/v1/searches/a5dbfae0a5dbfae0/results

Response:

{
    "features": {
        {
            "id": "20141011_0c4a",
            ...
        },
        {
            "id": "20141010_0c4b",
            ...
        },
    },
    ...
}

When you want to utilize the expressive power of the Search API for ad-hoc queries without going through the saved search workflow, look towards Quick Search.

Refer to Quick Search vs. Saved Search for additional details on the important differences between Quick and Saved searches.

POST https://api.planet.com/data/v1/quick-search`

Request:

{
  "item_types": ["PSOrthoTile"],
  "filter": {
    "type": "OrFilter",
    "config": [
      {
        "field_name": "published",
        "config": {
          "gte": "2015-10-01T00:00:00Z"
        },
        "type": "DateRangeFilter"
      }
    ]
  }
}

Response:

{
  "features": {
    {
      "id": "20141011_0c4a",
      ...
    },
    {
      "id": "20141010_0c4b",
      ...
    },
  },
  ...
}