Filter Expressions in the Main API (2017/01)

9 min

This page / section pertains to BrightSign Network (often abbreviated BSN), our legacy cloud platform. Our latest cloud platform is BSN.Cloud. Development of BSN has largely ceased and the platform will eventually be deprecated and replaced with BSN.Cloud.

Filter Expressions

GET calls that return multiple items accept the "?filter" query string, which allows the client to filter list returns according to one or more entity values. The query string can have multiple operators joined together with "AND" or "OR".

Example (single operator)

GET /2017/01/REST/Content/?filter=[mediaType]%20IS%20'video'

Example (multiple operators)

GET /2017/01/REST/Content/?filter=[fileName]%20BEGINS%20WITH%20'ex'%20AND%20[mediaType]%20IS%20'image'

Accepted expressions are described below.

String Operators

String operators are case-insensitive.

[entry] IS '<value>': Returns items that contain the entry equalling <value>. This operation supports the "*" and "?" wildcards.
[entry] IS NOT '<value>': Returns items that do not contain the entry equalling <value>. This operation supports the "*" and "?" wildcards.
[entry] BEGINS WITH '<value>': Returns items that contain the entry starting with the <value> substring.
[entry] ENDS WITH '<value>': Returns items that contain the entry ending with the <value> substring.
[entry] CONTAINS '<value>': Returns items that contain the entry with the <value> substring.
[entry] DOES NOT CONTAIN '<value>': Returns items that do not contain the entry with the substring".
[entry] CONTAINS ALL ('<value_1>', '<value_2>', [...]): Returns items that contain the entry with all of the specified substrings.
[entry] CONTAINS ANY ('<value_1>', '<value_2>', [...]): Returns items that contain the entry with any of the specified substrings.
[entry] IS IN ('<value_1>', '<value_2>', [...]): Returns items that contain the entry equalling any of the specified values.
[entry] IS NOT IN ('<value_1>', '<value_2>', [...]): Returns items that do not contain the entry equalling any of the specified values.

Enumeration Operators

Some string-value entries are enumerations: For example, the [mediaType] entry on the Content endpoint can only have "Video", "Image", "Audio", "Text", and "Other" values. The following operators can be used with enumeration entries:

[entry] IS '<value>': Returns items that contain the entry equalling <value>.
[entry] IS NOT '<value>': Returns items that do not contain the entry equalling <value>.
[entry] IS IN ('<value_1>', '<value_2>', [...]): Returns items that contain the entry equalling any of the specified values.
[entry] IS NOT IN ('<value_1>', '<value_2>', [...]): Returns items that do not contain the entry equalling any of the specified values.

Number Operators

[entry] IS <value>: Returns items that contain the entry equalling <value>.
[entry] IS NOT <value>: Returns items that do not contain the entry equalling <value>.
[entry] IS GREATER THAN <value>: Returns items that contain the entry with a value greater than <value>.
[entry] IS LESS THAN <value>: Returns items that contain the entry with a value less than <value>.
[entry] IS IN THE RANGE <value> AND <value>: Returns items that contain the entry with a value between the specified range.
[entry] IS NOT IN THE RANGE <value> AND <value>: Returns items that do not contain the entry with a value between the specified range.
[entry] IS IN (<value_1>, <value_2>, [...]): Returns items that contain the entry equalling any of the specified values.
[entry] IS NOT IN (<value_1>, <value_2>, [...]): Returns items that do not contain the entry equalling any of the specified values.
GPS LOCATION ([latittude_entry] AND [longitude_entry]) IN (<latitude_value>, <longitude_value>, <distance_value>): Returns items that have coordinate entries within <distance_value> of the specified <latitude_value> and <longitude_value>.
GPS LOCATION ([latittude_entity] AND [longitude_entity]) NOT IN (<latitude_value>, <longitude_value>, <distance_value>): Returns items that do not have coordinate entries within <distance_value> of the specified <latitude_value> and <longitude_value>.

DateTime Operators

DateTime values are formatted as yyyy-mm-ddThh:mm:ss.sssZ.

[entry] IS '<dateTime>': Returns items that contain the entry equalling <dateTime>.
[entry] IS NOT '<dateTime>': Returns items that do not contain the entry equalling <dateTime>.
[entry] IS AFTER '<dateTime>': Returns items that contain the entry with a time before <dateTime>.
[entry] IS BEFORE '<dateTime>': Returns items that contain the entry with a time after <dateTime>.
[entry] IN THE LAST (<units>, <length>, '<dateTime>'): Returns items that have a time entry within <length> before <dateTime>. The time <length> is quantified with the <units> parameter, which can have one of the following values: years, months, days.
[entry] NOT IN THE LAST (<units>, <length>, '<dateTime>'): Returns items that do not have a time entry within <length> before <dateTime>. The time <length> is quantified with the <units> parameter, which can have one of the following values: years, months, days.
[entry] IS IN THE RANGE '<dateTime>' AND '<dateTime>': Returns items that have a time entry that falls between the two <dateTime> values.
[entry] IS NOT IN THE RANGE '<dateTime>' AND '<dateTime>': Returns items that do not have a time entry that falls between the two <dateTime> values.
[entry] IS IN ('<dateTime_1>', '<dateTime_2>', [...]): Returns items that contain the entry equalling any of the specified values.
[entry] IS NOT IN ('<dateTime_1>', '<dateTime_2>', [...]): Returns items that do not contain the entry equalling any of the specified values.

Boolean Operators

[entity] IS TRUE: Returns items that contain the entry equalling a true value.
[entity] IS FALSE: Returns items that contain the entry equalling a false value.