Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/features/filtering/)

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

| Field         | Collections | Features | Description                                                                                                                        |
| ------------- | ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `id`          | ✗           | ✓        | Feature ID                                                                                                                         |
| `hashid`      | ✓           | ✓        | immutable opaque internal identifier. see [Feature Reference](https://docs.planet.com/develop/apis/features.md#feature-references) |
| `title`       | ✓           | ✗        | Collection title                                                                                                                   |
| `description` | ✓           | ✗        | Collection description                                                                                                             |

### Filter Collections by Title

* CURL

```
curl https://api.planet.com/features/v1/ogc/my/collections?title=my-collection \

  -u "$PL_API_KEY:"
```

### Filter Features by ID

* CURL

```
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

```
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

```
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

```
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

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

| View    | Description                                    |
| ------- | ---------------------------------------------- |
| `items` | Full features with complete geometry (default) |
| `wkb64` | Geometry encoded as WKB base64                 |
| `basic` | Exclude geometry from response                 |
| `refs`  | Minimal information only                       |

#### Example: Basic View (No Geometry)

* CURL

```
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