- 08 May 2024
- 3 Minutes to read
Filtering Recommendation Responses
- Updated on 08 May 2024
- 3 Minutes to read
You can filter products that you receive in recommendation requests. A condition query can filter each field of the response. To do this, the filter parameter should be passed to the request as a query string. You can see the example below;
https://recommendation.api.useinsider.com?....&filter=[{field}][{operator}][{value}]
Filtering Syntax
The filter parameter consists of AND (*) and OR (|) operators. You can chain filters by using these operators. The syntax example is:
?filter=( F1 * ( F2 | ( F3 * F4 ) )
Use case examples
With this filter, you receive the products with the price.USD more than 100.
?filter=[price.USD][>][100]
With this filter, the products you receive have category = car and color = red.
?filter=([category][~][car] * [color][=][red])
Operators
Operators are used for representing field and value relations. You can use operators while filtering products smartly and easily. They have symbols and aliases. In the filtering syntax, you can use either one.
Greater Than
Symbol | > |
Alias | gt |
Description | Returns all products whose field’s value is greater than the filter value. |
Example | [price.EUR][>][150] [price.EUR][gt][150] |
Greater Than or Equal
Symbol | >= |
Alias | gte |
Description | Returns all products whose field’s value is greater than or equal to the filter value. |
Example | [price.EUR][>=][150] [price.EUR][gte][150] |
Lower Than
Symbol | < |
Alias | lt |
Description | Returns all products whose field’s value is lower than the filter value. |
Example | [price.EUR][<][150] [price.EUR][lt][150] |
Lower Than or Equal
Symbol | <= |
Alias | lte |
Description | Returns all products whose field’s value is lower than or equal to the filter value. |
Example | [price.EUR][<=][150] [price.EUR][lte][150] |
Contains
Symbol | ~ |
Alias | ctn |
Description | Returns all products whose field’s items contain the filter value. |
Note | The field of the filter must be a type of array. |
Example | [category][~][clothes] [category][ctn][clothes] |
Does not Contain
Symbol | !~ |
Alias | nctn |
Description | Returns all products whose field’s items do not contain the filter value. |
Note | The field of the filter must be a type of array. |
Example | [category][!~][clothes] [category][nctn][clothes] |
Equal to
Symbol | = |
Alias | is |
Description | Returns all products whose field’s value is equal to the filter value. |
Example | [color][=][Blue] [color][is][Blue] |
Not Equal to
Symbol | != |
Alias | nis |
Description | Returns all products whose field’s value is not equal to the filter value. |
Example | [color][!=][Red] [color][nis][Red] |
Between
Symbol | >< |
Alias | btw |
Description | Returns all products whose field’s value is between filter range values. |
Note | Accepts colon (:) separated 2 values where the left one is lower bound and the right one is upper bound. |
Example | [color][><][150:450] [color][btw][150:450] |
Not Between
Symbol | >!< |
Alias | nbtw |
Description | Returns all products whose field’s value is not between filter range values. |
Note | Accepts colon (:) separated 2 values where the left one is lower bound and the right one is upper bound. |
Example | [color][>!<][150:450] [color][nbtw][150:450] |
Exists
Symbol | ? |
Alias | xst |
Description | If the value is 1, returns all products whose field exists. If the value is 0, returns all products whose field does not exist. |
Note | Only accept 0 and 1 as a value. |
Example | get products doesn’t have EUR field [price.EUR][?][0] [price.EUR][xst][0] |
Example | get products have TRY field [price.TRY][?][1] [price.TRY][xst][1] |
Date Field Values
Insider tries to parse every filter value for date fields; if it fails to parse simplified date expression, it will use it as a raw value. This allows us to use literal dates as values in the date filters. Date fields are created_at and modified_at. It is supported by every operator except between and not between operators because the between operator uses a colon to separate lower and upper bounds. However, the date fields have their colons such as 2022-09-30 15:45:00.
The most appropriate operators to use for date fields are:
After | > |
Before | < |
Is | = |
Is Not | != |
Date filters also allow unit values such as now, w for week, d for day, and h for hour. In addition, you can use + and - to add or subtract units. You can see the examples below;
get products that created last week [created_at][>][now-1w]
get products that last created 2 days ago [created_at][<=][now-2d]
In, Not-In Values
You can match fields' values with more than one value. To do so, you need to separate values by the || operator. It is supported by every operator except the between operator. You can see the examples below;
get products whose name is shoes, pants or t-shirt [name][=][shoes||pants||t-shirt]
get products whose color is not red and blue [color][!=][red||blue]
Advanced Filtering
You might need more than one filter in some cases. You can chain filters by using AND, OR operators, and parentheses. The AND operator is represented by * and OR operator is represented by |. You can see the examples below;
get products whose price.USD is greater than 200 and the color is red ([price.USD][>][200]*[color][=][red])
get products whose price.TRY is between 100 and 400, and color is red or discount is greater than 0 (([price.TRY][><][100:400]*[color][=][red])|[discount.TRY][>][0])
Limitations
- The depth limit is 15.
- Filter count limit 50.
- There is no filter count limit by depth as long as the total number of filters is not bigger than 50 and the filter depth is not bigger than 15.