Offer search - Filters

On the following filters

• an AND operator is applied between filters

• an OR operator is applied in the filter

For instance: &query=nike air max&filterBy=color:red blue&filterBy=brandId:12352&filterLowerThan=price:100 means that we want some nike air max and the (color red or color blue) and a specific brand and the price lower than 100.

Filter by a full text search on the offer

The full text search is mainly applied on title and description fields within the offers.

Filter on specific fields

Filter target

An offer have fields, those fields

• are in a specific distribution (discrete or continuous)

• have a type (string, date, float, long, boolean...)

• have possible actions, one of those actions is canFilter

To know the details on fields, there are several possibilities:

• on the coding phase you can see possible actions and distribution in the model details

• on runtime this information is available

  • on fields metadata in the response

  • on facets in the response when requested

Filter syntax

The syntax is the following to filter on a specific field:

<filterOperator>=<filterKey>:<firstValue> <secondValue>

• The filterKey is provided by the facet.

• The filterOperator depends on the field distribution also provided by the facet.

The API apply an OR operator between each value of a filter.

Warning:

• the client should wrapp all the filter values with the " character so that all values with a space (values separator in the syntax) or a character : (separator between filterKey and values in the syntax) are properly handled.

• the client should be consistent in the way is wrapping or not the values: either all the values are wrapped or none.

So for instance on the facet ethicalType,

• The filterKey is ethicalType

• The filterOperator is filterBy.

We can use it this way:

You can use several filters on a request. The API apply an AND operator between each filter.

Filter error cases

• The client should make sure the field exists.

• The client should make sure the field can be filtered.

• The client should respect the field type.

• The client should respect the field domain.

• The client should respect the field distribution.

• The client should use only once a filterKey, otherwise it doesn't make sense: fields are not multivalued.

Examples:

Filter on discrete distribution

Fields can have discrete values. For instance: offerId, merchantId, brandId, categoryId, codeEan... To know which field has a discrete distribution, use fieldsMeta parameters and check the canFilter and distribution property.

A filter is usually used after a facet. This one expose the distribution of the field. See the facets usage.

If the distribution of a field is discrete, the available filterOperator is filterBy only.

Each separated filterBy parameter is interpreted as an AND. Thus, if by mistake you put in your query something similar to &filterBy=merchantId:77&filterBy=merchantId:88 then you will get an error, as the same offer can't have two merchantId values. On the other hand, to retrieve, for example, offers from two merchants in the same request, your query should be similar to &filterBy=merchantId:77 88, as the space ' ' is interpreted as OR

If you are filtering by categoryId, please read the offers by category guide.

Filter on continuous distribution

Fields can have continuous values. For instance: price, totalPrice, rebatePercentage...
To know which field has a continuous distribution, use fieldsMeta parameters and check the canFilter and distribution property.

A filter is usually used after a facet. This one expose the distribution of the field. See the facets usage.

If the distribution of a field is continuous, the available filterOperator are the following:

Note: The given value should be a number: for instance 150, 12.5...

Filter on the availability of a field

Filter offers based on the existence of a field. Can be applied on a field that

• have the filter action available

• is optional

Check in the meta to see which field is eligible.

• For instance filterValueExists=deliveryCost:true : return only offers with a delivery cost

• For instance filterValueExists=deliveryCost:false : return only offers with no delivery cost

• Note : if you need both, do not use the filter