---
title: "Facet filtering reference"
slug: "facet-filtering-reference"
abstract: "Reference information for filtering facets using the Search and Recommendation API for Sitecore Search, specific to the facet.types.filter.values object."
---
# Facet filtering reference

To filter facets, use the `facet.types.filter` object. You can specify whether you want to do AND or OR filtering, whether you want the values in this facet to change dynamically based on filters in other facets, and whether you want to use complex nested filters, among other things. Refer to the [use cases and sample calls](https://doc.sitecore.com/search/en/developers/search-developer-guide/integrating-using-rest-apis/using-the-search-and-recommendation-api-to-create-search-experiences/filtering-facets.html "Filtering facets") that showcase a variety of facet filtering.

This topic is specific to the `search.facet.types.filter.values` object. For general facet filtering reference, see the [Search and Recommendation detailed API reference](https://doc.sitecore.com/search/en/developers/search-and-recommentation-api/index.html).

The following table describes the keys that the `search.facet.types.filter.values` object can take:

| Key | Type | Description | Value |
| --- | --- | --- | --- |
| `values` | `array of strings`<br><br>`array of filter objects` | Required.<br><br>The filter details for this facet.<br><br>To do simple facet filtering by facet IDs, pass an array of strings.<br><br>To do complex facet filtering with operators like `lte` (less than or equal to), `geoDistance`, `not`, for example, pass an array of objects. | For simple facet filtering:<br><br>```json<br>"values": ["facet_id123", "facet_id456", "facet_id789"]<br>```<br><br>For complex facet filtering:<br><br>```json<br>{<br>   "type": "and",<br>   "filters": [<br>      {<br>         "type": "lte",<br>         "value": "1000"<br>      },<br>      {<br>         "type": "gte",<br>         "value": "200"<br>      },<br>      {<br>         "type": "not",<br>         "filter": {<br>            "type": "eq",<br>            "value": "350"<br>         }<br>      }<br>   ]<br>}<br>``` |

## Simple facet filtering

To do simple facet filtering by facet IDs, pass an array of strings as the value for the `search.facet.types.filter.values` key. The **Filtering a term facet** section of [Filtering facets](https://doc.sitecore.com/search/en/developers/search-developer-guide/integrating-using-rest-apis/using-the-search-and-recommendation-api-to-create-search-experiences/filtering-facets.html "Filtering facets") has a sample call.

The following table describes the keys that the `search.facet.types.filter.values` object requires if it is of the `array of strings` type.

| Key | Type | Description |
| --- | --- | --- |
| `values` | `array of strings` | Optional. Pass an array of strings.<br><br>Array of facet IDs that you want to filter by.<br><br>Pass only facet IDs. Don't pass facet values.<br><br>For example:<br><br>```json<br>"values": ["facet_id123", "facet_id456", "facet_id789"]<br>``` |

## Complex facet filtering

To do complex facet filtering with operators like `lte` (less than or equal to), `geoDistance`, `not`, for example, pass an array of filter objects as the value for the `search.facet.types.filter.values` key. The **Using complex facet filters** section of [Filtering facets](https://doc.sitecore.com/search/en/developers/search-developer-guide/integrating-using-rest-apis/using-the-search-and-recommendation-api-to-create-search-experiences/filtering-facets.html "Filtering facets") has sample calls.

The following table describes the keys that the `search.facet.types.filter.values` object takes if it is of the `array of filter objects` type.

| Key | Type | Description |
| --- | --- | --- |
| values | Array of objects of the following types:stringallOf facet filter objectand facet filter objectanyOf facet filter objecteq facet filter objectgeoDistance facet filter objectgeoWithin facet filter objectgt facet filter objectgte facet filter objectlt facet filter objectlte facet filter objectnot facet filter objector facet filter object | Facet filtering objects you want to use. |

## Filter objects

### and facet filter object

To add nested facet filters, all of which have to match to get a result, use the `and` facet filter object. This facet filter object is recursive.

The following table describes the keys the `and` facet filter object takes:

| Key | Type | Description |
| --- | --- | --- |
| type | string | Required.Set as and.Operator of the facet filter object. |
| filters | Array of objects of the following types:stringallOf facet filter objectand facet filter objectanyOf facet filter objecteq facet filter objectgeoDistance facet filter objectgeoWithin facet filter objectgt facet filter objectgte facet filter objectlt facet filter objectlte facet filter objectnot facet filter objector facet filter object | Required.Array of facet filter objects or facet IDs. The filtering conditions of all objects must be satisfied. |

For example, you nest `lte`, `gte`, and `not` facet filter objects within the `and` facet filter object. In doing this, you request results that satisfy the conditions of being greater than an amount, less than an amount, and not equal to an amount.

Here's a sample `and` facet filter object:

```csharp
{
   "type": "and",
   "filters": [
      {
         "type": "lte",
         "value": "1000"
      },
      {
         "type": "gte",
         "value": "200"
      },
      {
         "type": "not",
         "filter": {
            "type": "eq",
            "value": "350"
         }
      }
   ]
}
```

### anyOf facet filter object

To get results that match any given value, use the `anyOf` facet filter object.

The following table describes the keys the `anyOf` facet filter object takes:

| Key | Type | Description |
| --- | --- | --- |
| `type` | `string` | Required.<br><br>Set as `anyOf`.<br><br>Operator of the facet filter object. |
| `values` | Array of `string` or `number` values | Required.<br><br>Facet values you want to filter by, any of which can match to get results.<br><br>Only pass facet values. Don't pass facet IDs. The values must be of the type of the attribute on which the filter is applied on. |

Here's a sample `anyOf` facet filter object:

```JSON
{
   "type": "anyOf",
   "values": [
      "History",
      "Science Fiction",
      "Classics"
   ]
}
```

### allOf facet filter object

To get results that match all the given values, use the `allOf` facet filter object.

The following table describes the keys the `allOf` facet filter object takes:

| Key | Type | Description |
| --- | --- | --- |
| `type` | `string` | Required.<br><br>Set as `allOf`.<br><br>Operator of the facet filter object. |
| `values` | Array of `string` or `number` values | Required.<br><br>Facet values you want to filter by, all of which must match to get results.<br><br>Only pass facet values. Don't pass facet IDs. The values must match the type of the attribute on which the filter is applied on. |

### eq facet filter object

To get results that match a given value, use the `eq` facet filter object.

The following table describes the keys the `eq` facet filter object takes:

| Key | Type | Description |
| --- | --- | --- |
| `type` | `string` | Required.<br><br>Set as `eq`.<br><br>Operator of the facet filter object. |
| `value` | `string` or `number` | Required.<br><br>Facet value that must be matched to get a result.<br><br>Only pass facet values. Don't pass facet IDs. The value must be of the type of the attribute on which the filter is applied on. |

Here's a sample `eq` facet filter object:

```JSON
{
   "type": "eq",
   "value": "Science Fiction"
}
```

### geoDistance facet filter object

To get results within a circular area you define, use the `geoDistance` facet filter object.

The following table describes the keys the `geoDistance` facet filter object takes:

| Key | Type | Description |
| --- | --- | --- |
| type | string | Required.Set as geoDistance.Operator of the facet filter object. |
| distance | string | Required.Radius of the circular geographical area where you want Search to find suitable content items.Enter a number followed by a unit of distance. Don't add spaces. For example, enter 8.6ft or 86km.Supported units are:in (inches)ft (feet)yd (yards)mi (miles)nmi (nautical miles)km (kilometers)m (meters)cm (centimeters)mm (millimeters) |
| lat | number | Latitude of the visitor's location. Together, lat and lon define the center of the circle where you want to filter results.Use the decimal degrees (DD) format. Don't use spaces.For example, pass -77.0089.If you do not specify a value here, Search looks in the geo context object for a latitude value. If there is no geo context object, Search infers the approximate latitude from the visitor's IP address. |
| lon | number | Longitude of the visitor's location. Together, lat and lon define the center of the circle where you want to filter results.Use the decimal degrees (DD) format. Don't use spaces.For example, pass -120.0017.If you do not specify a value here, Search looks in the geo context object for a latitude value. If there is no geo context object, Search infers the approximate latitude from the visitor's IP address. |

Here's a sample `geoDistance` facet filter object:

```JSON
{
   "type": "geoDistance",
   "distance": "50km",
   "lat": -59.11309610169502,
   "lon": -37.329354589260596
}
```

### geoWithin facet filter object

To get results within a defined polygonal area, use the `geoWithin` facet filter object.

The following table describes the keys the `geoWithin` facet filter object takes:

| Key | Type | Description |
| --- | --- | --- |
| `type` | `string` | Required.<br><br>Set as `geoWithin`.<br><br>Operator of the facet filter object. |
| `coordinates` | Array of [`coordinates`](https://doc.sitecore.com/search/en/developers/search-developer-guide/integrating-using-rest-apis/using-the-search-and-recommendation-api-to-create-search-experiences/filtering-facets/facet-filtering-reference.html#UUID-9247a2a9-b634-ac53-c017-c614e3e267a7_para-idm1823394165145314) objects. | Coordinates that form the polygonal area where Search looks for results.<br><br>The `lat` and `lon` keys of this object define one vertex of the polygon. For example, if you define four vertexes, Search creates a four-sided area to filter results within.<br><br>Define at least three points. |

**coordinates object**

Pass at least three `coordinates` objects for Search to create a polygonal area.

The following table describes the keys the `coordinates` object takes:

| Key | Type | Description |
| --- | --- | --- |
| `lat` | `number` | Latitude of a vertex of the polygonal area where you want Search to look for results.<br><br>Use the decimal degrees (DD) format. Don't use spaces.<br><br>For example, pass `-77.0089`. |
| `lon` | `number` | Longitude of a vertex of the polygonal area where you want Search to look for results.<br><br>Use the decimal degrees (DD) format. Don't use spaces.<br><br>For example, pass `-120.0017`. |

Here's a sample `geoWithin` facet filter object:

```JSON
{
   "type": "geoWithin",
   "coordinates": [
      {
         "lat": 43.194852,
         "lon": -79.570522
      },
      {
         "lat": 43.176515,
         "lon": -79.929493
      },
      {
         "lat": 43.521512,
         "lon": -79.912504
      },
      {
         "lat": 43.871014,
         "lon": -78.780655
      }
   ]
}
```

### gt facet filter object

To get results greater than a given value, use the `gt` facet filter object. You can only use this facet filter object with histogram facets.

The following table describes the keys the `gt` facet filter object takes:

| Key | Type | Description |
| --- | --- | --- |
| `type` | `string` | Required.<br><br>Set as `gt`.<br><br>Operator of the facet filter object. |
| `value` | `string` or `number` | Required.<br><br>Facet value to use as a threshold to get results greater than.<br><br>Only pass facet values. Don't pass facet IDs. |

Here's a sample `gt` facet filter object:

```csharp
{
   "type": "gt",
   "value": 999
}
```

### gte facet filter object

To get results greater than or equal to a given value, use the `gte` facet filter object. You can only use this facet filter object with histogram facets.

The following table describes the keys the `gte` facet filter object takes:

| Key | Type | Description |
| --- | --- | --- |
| `type` | `string` | Required.<br><br>Set as `gte`.<br><br>Operator of the facet filter object. |
| `value` | `string` or `number` | Required.<br><br>Facet value to use as a threshold to get results greater than or equal to.<br><br>Only pass facet values. Don't pass facet IDs. |

Here's a sample `gte` facet filter object:

```csharp
{
   "type": "gte",
   "value": 1000
}
```

### lt facet filter object

To get results less than a given value, use the `lt` facet filter object. You can only use this facet filter object with histogram facets.

The following table describes the keys the `lt` facet filter object takes:

| Key | Type | Description |
| --- | --- | --- |
| `type` | `string` | Required.<br><br>Set as `lt`.<br><br>Operator of the facet filter object. |
| `value` | `string` or `number` | Required.<br><br>Facet value to use as a threshold to get results less than.<br><br>Only pass facet values. Don't pass facet IDs. |

Here's a sample `lt` facet filter object:

```csharp
{
   "type": "lt",
   "value": 1000
}
```

### lte facet filter object

To get results less than or equal to a given value, use the `lte` facet filter object. You can only use this facet filter object with histogram facets.

The following table describes the keys the `lte` facet filter object takes:

| Key | Type | Description |
| --- | --- | --- |
| `type` | `string` | Required.<br><br>Set as `lte`.<br><br>Operator of the facet filter object. |
| `value` | `string` or `number` | Required.<br><br>Value to use as a threshold to get results less than or equal to.<br><br>Only pass facet values. Don't pass facet IDs. |

Here's a sample `lte` facet filter object:

```csharp
{
   "type": "lte",
   "value": 999
}
```

### not facet filter object

To add nested facet filters, none of which have to match to get a result, use the `not` facet filter object. This facet filter object is recursive.

The following table describes the keys the `not` facet filter object takes:

| Key | Type | Description |
| --- | --- | --- |
| type | string | Required.Set as not.Operator of the facet filter object. |
| filter | Object of the following types or string facet IDstringallOf facet filter objectand facet filter objectanyOf facet filter objecteq facet filter objectgeoDistance facet filter objectgeoWithin facet filter objectgt facet filter objectgte facet filter objectlt facet filter objectlte facet filter objectnot facet filter objector facet filter object | Required.Facet filter object or string facet ID. |

Here's a sample `not` facet filter object:

```csharp
{
   "type": "not",
   "filter":"facet_id123"
}
```

### or facet filter object

To add nested facet filters, any of which have to match to get a result, use the `or` facet filter object. This facet filter object is recursive.

The following table describes the keys the `or` facet filter object takes:

| Key | Type | Description |
| --- | --- | --- |
| type | string | Required.Set as or.Operator of the facet filter object. |
| filters | Array of objects of the following types:stringallOf facet filter objectand facet filter objectanyOf facet filter objecteq facet filter objectgeoDistance facet filter objectgeoWithin facet filter objectgt facet filter objectgte facet filter objectlt facet filter objectlte facet filter objectnot facet filter objector facet filter object | Required.Array of facet filter objects or string facet IDs. The filtering conditions of at least one object or facet ID must be satisfied. |

For example, you nest `lte`, `gte`, and `eq` facet filter objects within the `or` facet filter object. In doing this, you request results that satisfy the conditions of either being greater than an amount, less than an amount, or equal to an amount.

Here's a sample `or` facet filter object:

```csharp
{
   "type": "or",
   "filters": [
      {
         "type": "lte",
         "value": "150"
      },
      {
         "type": "gte",
         "value": "350"
      },
      {
         "type": "eq",
         "value": "200"
      }
   ]
}
```