Recommendation API filters

You can manipulate item filters when making the request.

Filter types

Note: For a detailed description of filter types, see the User Guide.

IQL filters

An IQL filter is a string built using the Items Query Language. It allows you to combine filters and apply logic such as IF statements to build criteria that an item must meet to be included in the recommendation response.

Elastic IQL filters let you supplement the recommendation result with items which don’t meet the filter criteria in case the criteria are too restrictive.

Important:

The “equals” operator is ==. A single = is not an operator in IQL.
In the IQL string, the spaces before and after the AND/OR operators are required.
When adding filters to POST requests, you must escape any " in the filter string in the request body, for example:

"additionalFilters": "brand!=\"foo\" AND brand!=\"bar baz\"",

Tip:

When you add filters to a campaign in the Synerise Web Application, you can use the API to fetch the campaign’s settings, including filters.
You can use this to learn IQL by seeing how filters created with the GUI are saved into IQL strings.

To see the filters, check the slots[].filterRules object in the response.

Distinct filters

Distinct filters regulate how many items with certain properties can be recommended at the same time.

In campaign result requests, the filters are set by the campaign and can’t be changed when making the request.
In model requests, you can add a distinct filter when making the request.

Manipulating filters in campaign results

In campaign requests, you can use the additionalFilters and additionalElasticFilters parameters to modify or replace the filters from the campaign settings.

When you do that, you must the use filtersJoiner and elasticFiltersJoiner parameters to set the logic of combining the filters:

AND means that an item must match both the filter you send and the one from the campaign.
OR means that an item must match the filter you send, the filter from the campaign, or both.
REPLACE means that an item must match the filter you send and the filter from the campaign is ignored.

Distinct filters are defined in the campaign settings and can’t be changed when making a request.

Examples:

In this example, the item must meet at least both of the following:

the conditions of elastic filter from the campaign
elastic filter: price must be more than 50

Usage example: a cart recommendation which shows items with a price that will increase the cart’s value to the threshold of free shipping.

curl --location 'https://api.synerise.com/recommendations/v2/recommend/campaigns?token=...' \
--header 'Content-Type: application/json' \
--data '{
    "clientUUID": "cf9e9b57-7776-51bc-b7bc-75cc75abdf59",
    "campaignId": "DkhvrZoTKthD",
    "additionalElasticFilters": "price.value>50",
    "elasticFiltersJoiner": "AND"
}'

Requests to a model

In requests to a model, you can add the following parameters:

filters is an IQL filter
elastic:filters is an elastic IQL filter

distinctFilter is an object:

"distinctFilter": {
"elastic": boolean, // when `true`, if there are not enough items which meet the criteria,
                    // other items can be added to meet the minimum number of items in the slot
"filters": // an array of filters
    [
        {
            "field": "color", // attribute name
            "maxNumItems": n, // max number of items with the same attribute value
            "levelRangeModifier": n // only used when field is 'category'.
                                    // Removes the last n category levels
        }
    ]
}

Important: The available filter types depend on the recommendation type. For details, refer to each endpoint’s reference documentation.

Example:
A request to the “Personalized” model with a filter that uses an attribute from the profile which made the request:

curl --location 'https://api.synerise.com/recommendations/v2/recommend/items/users/8ae22439-f72b-4fe7-98e5-da3217215c54?filters=colors%3D%3Dclient.attributes.favoriteColor&token=98A5FC55-0000-0000-0000-98339BDECAE6'