You can filter products that you receive in recommendation requests. A condition query can filter each field of the response. The filter parameter should be passed to the request as a query string to do this. You can see the example below:
https://recommendation.api.useinsider.com?....&filter=[{field}][{operator}][{value}]
Filtering Syntax
The filter parameter comprises 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 to represent field and value relations. You can use operators to filter products smartly and efficiently. They have symbols and aliases. You can use either one in the filtering syntax.
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 the filter range values. |
| Note | Accepts colon (:) separated two values where the left one is the lower bound and the right one is the 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 the filter range values. |
| Note | Accepts colon (:) separated 2 values where the left one is the lower bound and the right one is the upper bound. |
| Example | [color][>!<][150:450] [color][nbtw][150:450] |
Exists
| Symbol | ? |
| Alias | xst |
| Description | If the value is 1, it returns all products whose field exists. If the value is 0, it returns all products whose field does not exist. |
| Note | Only accept 0 and 1 as a value. |
| Example | get products doesn’t have the 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 a 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 using the || operator. Every operator except the between operator supports it. 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 the 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.