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

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

Key

Type

Description

Value

values

array of strings

array of filter objects

Required.

The filter details for this facet.

To do simple facet filtering by facet IDs, pass an array of strings.

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:

RequestResponse
"values": ["facet_id123", "facet_id456", "facet_id789"]

For complex facet filtering:

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

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

Array of facet IDs that you want to filter by.

Pass only facet IDs. Don't pass facet values.

For example:

RequestResponse
"values": ["facet_id123", "facet_id456", "facet_id789"]

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

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:

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:

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

Set as anyOf.

Operator of the facet filter object.

values

Array of string or number values

Required.

Facet values you want to filter by, any of which can match to get results.

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:

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

Set as allOf.

Operator of the facet filter object.

values

Array of string or number values

Required.

Facet values you want to filter by, all of which must match to get results.

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.

Set as eq.

Operator of the facet filter object.

value

string or number

Required.

Facet value that must be matched to get a result.

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:

RequestResponse
{
   "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:

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

Set as geoWithin.

Operator of the facet filter object.

coordinates

Array of coordinates objects.

Coordinates that form the polygonal area where Search looks for results.

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.

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.

Use the decimal degrees (DD) format. Don't use spaces.

For example, pass -77.0089.

lon

number

Longitude of a vertex of the polygonal area where you want Search to look for results.

Use the decimal degrees (DD) format. Don't use spaces.

For example, pass -120.0017.

Here's a sample geoWithin facet filter object:

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

Set as gt.

Operator of the facet filter object.

value

string or number

Required.

Facet value to use as a threshold to get results greater than.

Only pass facet values. Don't pass facet IDs.

Here's a sample gt facet filter object:

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

Set as gte.

Operator of the facet filter object.

value

string or number

Required.

Facet value to use as a threshold to get results greater than or equal to.

Only pass facet values. Don't pass facet IDs.

Here's a sample gte facet filter object:

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

Set as lt.

Operator of the facet filter object.

value

string or number

Required.

Facet value to use as a threshold to get results less than.

Only pass facet values. Don't pass facet IDs.

Here's a sample lt facet filter object:

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

Set as lte.

Operator of the facet filter object.

value

string or number

Required.

Value to use as a threshold to get results less than or equal to.

Only pass facet values. Don't pass facet IDs.

Here's a sample lte facet filter object:

RequestResponse
{
   "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 ID

Required.

Facet filter object or string facet ID.

Here's a sample not facet filter object:

RequestResponse
{
   "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:

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:

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

Do you have some feedback for us?

If you have suggestions for improving this article,