Filters and Sorting

To implement filters and sorting options with the search products and content endpoint, you must first configure your desired filters and sorting options in Search Studio.

Product Filters

Possible filter types for product search include: category, text (also known as multiselect), numeric, and Boolean. If there are products in the result set that match the configured filters, then these filters will be returned as filterOptions in the API response. The filters will be returned in the order defined in Search Studio.

If a filter option is configured and not being returned in the API response, check whether a “Show Above” percentage is set. This percentage, set to 0% by default, determines when a filter should be displayed. If the color filter is set to 20%, and only 15/100 results have a color value, then the color filter will not be displayed.

Each filter returned in the filterOptions array has a type.

• TREE: this type is used for category filters to indicate the filter can be displayed as a tree
• COLLECTION: this type is used for textual filters to indicate the filter can be displayed as a collection of possible filter values
• COLOR: this type is used for color filters and returns a hex code so that the filter values can be displayed as swatches if desired. (Note: To indicate a filter is a color filter, you must activate the “Treat as Color Filter” setting in Search Studio by editing the color filter option and checking this box.)
• RANGE: this type is used for numeric filters intended to be displayed as range filters. Each filter with this type will have minimum/maximum values as well as the counts for each value in between.
• BUCKET: this type is used for numeric filters intended to be displayed as buckets. This filter type can be configured in Search Studio to break numeric data into a desired number of buckets. The API response returns the number of products that fit into each bucket, and the bucket ranges. For example, a price filter using buckets might have 3 buckets for products ranging between $100-400: $100-200, $200-300, and $300-400.
• NUMERIC_VALUES: this type is used for numeric filters where each numeric value should be displayed as its own checkbox. This is useful in scenarios where there are a small number of numeric values and the desired behavior is to filter for an exact number. For example, if you want to filter for a notebook with 2 USB ports.
• BOOLEAN: this type is used for true/false filters

When a customer selects a filter option, you should send a new request with this filter set in the filters parameter.

The filters parameter expects a JSON array containing filters for product search OR content search (NOT both at the same time).

Filter Examples

Here are some examples for product filters (but remember to rely on the JSON answer to ensure you are passing valid names and values):

CATEGORY

[{"name":"Category", "type":"products", "values":[{"name":"Dishwashers"}]}]

TEXT

[{"name":"Certification", "type":"products", "values":[{"name":"Organic"}]}]

For text filters where customers can select multiple options at the same time, you will see that the filter option still appears in the filterOptions array after you have applied the first selected filter to the results. For example, if you have a filter “Certification”, and a user clicks “Organic”, send the request like in the example above. The products returned will be products with the certification “Organic.” If some of those organic products also have a Fair Trade certification, then you will see in the filterOptions array that there are additional filter values relevant for the customer. If the customer then selects the filter “Fair Trade”, your new request should include:

[{"name":"Certification", "type":"products", "values":[{"name":"Organic"},{"name":"Fair Trade"}]}]

This process can be repeated until there are no additional filter options available.

RANGE

[{"name":"Rating", "type":"products", "min":4.0, "max":5.0}]

BUCKET

[{"name":"Rating", "type":"products", "values":[{"name":"4.5 - 5.0"}]}]

NUMERIC_VALUES

[{"name":"Number of USB ports", "type":"products", "values":[{"value":"2"}]}]

BOOLEAN

[{"name":"Free Shipping", "type":"products", "values":[{"value":"true"}]}]

In addition to filtering based on the filter options returned in the API response, you may also use conceptIdNames or database ids to filter for any attribute in your product data. In this case, the filter does not need to be configured in Search Studio first. This kind of programmatic filtering can be useful in cases where a filter should be applied, but not displayed in the frontend.

You can find conceptIdNames and database ids when you open an attribute in the Data Platform or using the concept API endpoint. The conceptIdName is created based on the incoming product data, so it should align with your product feed. For example, if you have a field called Brand, you should expect to find a textual attribute with the conceptIdName BRAND.

[{"conceptIdName": "BRAND", "type":"products", "values":[{"conceptIdName": "BRAND_#_BRANDNAME"}]}]

OR

[{"id":"277092785", "type":"products", "values":[{"id":"279261367"}]}]

Content Filters

We distinguish between product and content filters, and it is not possible to filter for both at the same time. If you have content pages in your search, such as blog articles, you can set up data points that can be used as content filters. A common data point might be publication date or tags/topics. Content filers are also configured in Search Studio under Filters and Sorting.

Here is an example for content search:

[{"name":"Topics", "type":"content", "values":[{"value":"Beach"}]}]

Sorting Products

Any numeric or Boolean attribute can be used to create a sorting option in Search Studio. Only sorting options that have been configured will work with the sort parameter. When configuring sorting options, you must create both the ascending and descending option if required (e.g., to sort by price in both directions.)

The sort parameter expects a string containing the name of the sorting option. For example, to sort by price from low to high, you might have configured this sorting option:

Price (low to high)

In your API request, you can activate this sorting option like this:

"sort": "Price (low to high)",

Similar to programmatic filtering option described above, you can sort by any numeric or Boolean attribute using the sortComplex parameter, even if the sorting option has not been configured in Search Studio.

sortComplex expects a JSON object containing the conceptIdName or key and a sorting direction (ASC for ascending, DESC for descending):

{"conceptIdName": "PRICE", "direction":"ASC"}

or

{"key": "277092657", "direction":"ASC"}

You can also use sortComplex to apply a different ranking strategy than the one used by default across all search queries. For this type of sorting, you need the rankingStrategyId from Search Studio. The parameter will look like this:

{"rankingStrategyId":"6672d6564f23963fbb4b0a78", "type":"STRATEGY"}

Sorting Content

If you have numeric or date data points, you can also set up sorting options for content pages in Search Studio.