Skip to main content

Filtering Collections and Features

The Features API supports flexible filtering on both Collections and Features. You can filter by built-in fields, custom properties, and geometry boundaries.

Overview​

Filtering options:

  • Text filters: title, description, id, hashid
  • Property filters: custom properties filter
  • Sorting: created_date, title, id
  • Pagination: limit, offset

Features exclusive parameters: bbox (spatial), _view (format)

Other: error handling, performance tips

Text Filters​

Filter by standard fields like ID, title, and description.

FieldCollectionsFeaturesDescription
id✗✓Feature ID
hashid✓✓Granero Ref
title✓✗Collection title
description✓✗Collection description

Filter Collections by Title​

curl https://api.planet.com/features/v1/ogc/my/collections?title=my-collection \
  -u "$PL_API_KEY:"

Filter Features by ID​

curl https://api.planet.com/features/v1/ogc/my/collections/${COLLECTION_ID}/items?id=my-feature \
  -u "$PL_API_KEY:"

Fuzzy Matching​

Use the ~ prefix for fuzzy matching on text fields:

GET /collections/{collectionId}/items?id=~feature

Property Filters​

Filter custom properties. Any non-reserved parameter is treated as a property filter.

Reserved parameters: admin_view, limit, offset, api_key, sort, id, hashid, view, title, description, can_write, shared, org_id, org_override, bbox, and any parameter starting with _

Basic Property Filtering​

Filter features by any custom property:

curl https://api.planet.com/features/v1/ogc/my/collections/${COLLECTION_ID}/items?category=imagery \
  -u "$PL_API_KEY:"

Advanced Property Filtering​

For complex property structures, use double underscores (__) to access nested properties and array indices.

{ "properties": { "a": ["b"], "c": { "d": 1 } } }
GET /collections/{collectionId}/items?a__0=b    # access array elements by index (__ + index)
GET /collections/{collectionId}/items?c__d=1    # nested objects
GET /collections/{collectionId}/items?a=~b      # fuzzy match on array values
GET /collections/{collectionId}/items?c=~d      # fuzzy match on nested keys/values

Sorting​

Sort results by specific fields using the sort query parameter. Use a - prefix for descending order.

Collections can be sorted by:

  • created_date
  • title

Features can be sorted by:

  • id

Example: Sort Collections​

curl https://api.planet.com/features/v1/ogc/my/collections?sort=-created_date \
  -u "$PL_API_KEY:"

Example: Sort Features​

GET /collections/{collectionId}/items?sort=-id

Pagination​

Control the number of results returned and navigate through large result sets using limit and offset parameters.

  • limit: Maximum number of results to return per request
  • offset: Number of results to skip before returning results
curl https://api.planet.com/features/v1/ogc/my/collections/${COLLECTION_ID}/items?limit=50&offset=100 \
  -u "$PL_API_KEY:"

Features Exclusive Parameters​

The following filtering capabilities are exclusive to Features (not available for Collections).

Bounding Box​

Filter features by geographic area using a bounding box. The bbox parameter accepts four comma-separated values representing the minimum longitude, minimum latitude, maximum longitude, and maximum latitude.

Format: bbox=minlon,minlat,maxlon,maxlat

curl https://api.planet.com/features/v1/ogc/my/collections/${COLLECTION_ID}/items?bbox=-109,37,-102,41 \
  -u "$PL_API_KEY:"

Response Views​

Control the format and content of returned features using the _view query parameter.

ViewDescription
itemsFull features with complete geometry (default)
wkb64Geometry encoded as WKB base64
basicExclude geometry from response
refsMinimal information only

Example: Basic View (No Geometry)​

curl https://api.planet.com/features/v1/ogc/my/collections/${COLLECTION_ID}/items?_view=basic \
  -u "$PL_API_KEY:"

Other View Options​

GET /collections/{collectionId}/items?_view=items
GET /collections/{collectionId}/items?_view=wkb64
GET /collections/{collectionId}/items?_view=refs

Error Handling​

Unsupported Property​

If you filter on a property that does not exist, you will get an empty result set (no features match).

Invalid Filter Value​

GET /collections/{collectionId}/items?size=

Returns: 400 Bad Request

Invalid Query Parameter​

GET /collections?invalid_param=value

If the parameter is not a known reserved parameter, it is treated as a property filter.

If the property does not exist on your collections, you will get an empty result.

Performance Considerations​

  • Filters on indexed fields (id, hashid, etc.) perform well
  • Property filters on custom fields may require table scans for large datasets
  • Use bbox filters to reduce the search area when working with geospatial data
  • For large result sets, use limit and offset for pagination
Last updated on