Filtering

The API provides a generic system to apply filters on collections. Not all endpoints support filters. Please refer to the individual documentation of each endpoint for more information on the supported filters.

To filter a collection, simply add the filters=[field]:[operator]:[value] query parameter to the url of the endpoint and make sure to URL encode the value. Multiple filters may be specified by separating each filter by a semicolon.

Simple filter example

In this example we get all popular events where the sport is not Tennis or Soccer:

$ curl --request GET \\
  --url 'https://api.vaix.ai/api/sports/events/popular?filters=sport:nin:Tennis,Soccer'

You can combine multiple filters by separating them with a semicolon. For example if you wanted to get all popular Soccer events except the Norwegian games you would do:

$ curl --request GET \\
  --url 'https://api.vaix.ai/api/sports/events/popular?filters=sport:eq:Soccer;country:neq:Norway'

OR filtering

The above example demonstrates combining multiple filters using the AND filtering logic. If you want to apply an OR logic, you can use the | separator between multiple filters.

OR filter example

In this example we get all popular events where the sport is Soccer or the league is NBA:

$ curl --request GET \\
  --url 'https://api.vaix.ai/api/sports/events/popular?filters=sport:eq:Soccer|league:eq:NBA'

Notice that AND and OR filters can be combined in the same request. In that case, the OR filters are grouped together to a nested clause.

AND and OR filters combined

In this example we get all popular events where the status is live and (sport is Soccer or league is NBA):

$ curl --request GET \\
  --url 'https://api.vaix.ai/api/sports/events/popular?filters=status:eq:live;sport:eq:Soccer|league:eq:NBA'

Filtering fields

If filtering is available for an endpoint, then the supported filtering fields are indicated in the documentation of that endpoint.

Field types

Notice that an error will be returned if the provided filter value does not match the type of the underlying field.

For example if you try to filter a numeric field with a string value:

$ curl --request GET \\
  --url 'https://api.vaix.ai/api/crm/predictions/retention?operator=luckybus&filters=apds_last_30:gt:invalid' \\
  --header 'Content-Type: application/json'

you will get a 400 Bad Request response:

{
    "error": "invalid value for filters",
    "status": "error"
}

Filtering operators

The following operators are supported by the API:

Operator	Description
in	Returns entries where the field is equal to one of the provided values. The values should be comma separated, e.g. sport:in:soccer,rugby
nin	Returns entries where the field is not equal to any of the provided values. The values should be comma separated, e.g. sport:nin:soccer,rugby
eq	Returns entries where the field is equal to the value, e.g. country:eq:germany
neq	Returns entries where the field is not equal to the value, e.g. country:neq:germany
gt	Returns entries where the field is greater than the value, e.g. churn_score:gt:0.5
gte	Returns entries where the field is greater or equal to the value, churn_score:gte:0.5
lt	Returns entries where the field is less than the value, e.g. churn_score:lt:0.5
lte	Returns entries where the field is less or equal to the value, e.g. churn_score:lte:0.5

Filters on array fields

Currently only in, nin filters are supported for fields that contain array values like the participants of an event. Providing a different filtering operator for such a field will result in a 400 Bad Request response.

Dynamic filtering

Some endpoints support a dynamic filtering functionality. In those cases, the filter's value does not need to be provided in the request parameters, but it will be dynamically calculated during the request's execution. These filters are usually user-related and for them to work the user query parameter must also be specified.

In the following example, we get events that are popular in the user's country.

$ curl --request GET \\
  --url 'https://api.vaix.ai/api/sports/events/popular?user=123&dynamic_filters=user_country' \\
  --header 'Content-Type: application/json'

Ranking filtering

Some endpoints support a ranking filtering functionality. In those cases, an extra filter is dynamically added to the request, where its value will be calculated by ranking the given entity and getting the top count values out of it. Notice that for ranking recommended-related entities, the user query parameter must also be specified.

The expected format is a comma separated list of the form entity:ranking where entity corresponds to one of the supported entities and ranking is a single integer indicating the exact ranking position of the entity to use for filtering.

For example a ranking filter of the form game_studio_recommended:1 would filter the endpoint's results to return only games which are designed by the top recommended game studio of the current user.

For a multi-ranking example, game_studio_recommended:1,game_category_popular:1 would apply the above filter and on top of that, it will only include games from the most popular game category.

In the following example, we get recommended games which all belong to the user's most recommended game studio.

$ curl --request GET \\
  --url 'https://api.vaix.ai/api/casino/games/recommended?user=123&ranking_filter=game_studio_recommended:1' \\
  --header 'Content-Type: application/json'