Filtering

The API query language allows you to make complex API calls.

This section explains:

What the API query language is
What filter operators are
The comparison operators you can use for filtering
The logical operators you can use for filtering
The grouping operators you can use for filtering
Query examples

API query language

You use the API query language to filter the results returned by an API call. It is a simple language that extends the functionality of query parameters. The API language allows you to make more complex requests than you can make using conventional queries. It supports all the operators described in the Filtering section of Microsoft's API Guidelines.

Filter operators

The API query language allows you to add filter operators to your query. Filter operators allow you to append your query with comparison, logical and grouping operators. For example, rather than requesting a list of every customer in your account, you can use a comparison operator to request every user on your account with a particular name. Using filter operators can be useful if you want to narrow down the results returned by your query.

Comparison operators

Operator	Description	Example
eq	Equal - this operator returns results that are equal to the specified value. The example returns a list of items with a name equal to Alan.	name eq "Alan"
ne	Not equal - this operator returns results that are not equal to the specified value. The example returns a list items with a name other than Nicole.	name ne "Nicole"
like	Like - this operator returns results that include the specified value as a sub-string. The example returns a list of items with a name that includes "al". This returns items with names such as Alan, Alma and Alberto.	name like "Al"
gt	Greater than - this operator returns results that are greater than the specified value. The example returns a list of items with a cost greater than 100.	cost gt 100
ge	Greater than or equal - this operator returns results that are greater than or equal to the specified value. The example returns a list of items with a cost greater than or equal to 100.	cost ge 100
lt	Less than - this operator returns results that are less than the specified value. The example returns a list of items with a cost less than 150.	cost lt 150
le	Less than or equal - this operator returns results that are less than or equal to the specified value. The example returns a list of items with a cost less than or equal to 150.	cost le 150

Logical operators

Operator	Description	Example
and	Logical and - This operator returns results that match both the specified conditions. The example returns a list of items with the name Alan and an age greater than 10.	name eq "Alan" and age gt 10
or	Logical or - This operator returns results that match either of the specified conditions. The example returns a list of items with the name Alan or an age of 10.	name eq "Alan" or age eq "10"
not	Logical negation - This operator negates whatever comparison follows directly after it. The example returns a list of items with a cost greater than 10.	not cost le 10

Operator

Description

Example

and

Logical and - This operator returns results that match both the specified conditions.

The example returns a list of items with the name Alan and an age greater than 10.

name eq "Alan" and age gt 10

Logical or - This operator returns results that match either of the specified conditions.

The example returns a list of items with the name Alan or an age of 10.

name eq "Alan" or age eq "10"

not

Logical negation - This operator negates whatever comparison follows directly after it.

The example returns a list of items with a cost greater than 10.

not cost le 10

Grouping operator

If you want a statement in a query to be evaluated first, you can place it inside of round brackets (). This is typically required for complex operations involving the or logical operator. For example, if you want to retrieve a list of items located in Glasgow, Edinburgh or London with a color of red, you would place the or statement inside of round brackets.

The query would look like this: (city eq "Glasgow" or city eq "Edinburgh" or city eq "London") and color eq "red".

Query examples

The following examples demonstrate how you structure a request using the API query language.

Info

For further examples of using filers, refer to the topic How to filter subscribers by network status.

Returns All Groups Named "Naomi's Group"
GET "https://api.iot-x.com/subscriber-groups?filter=(name eq "Naomi's Group")

Returns All Groups Not Named "Naomi's Group"
GET "https://api.iot-x.com/subscriber-groups?filter=(name ne "Naomi's Group")

Returns All Subscribers on the Konnect Operator with a Physical ID Less Than 8944999999248275001
GET "https://api.iot-x.com/subscribers/active?filter=(operator eq "Konnect" and physicalId lt "208944999999248275001")

Returns All Subscribers on the Konnect or Wavez Operator with a Physical ID Less Than 8944999999248275001
GET "https://api.iot-x.com/subscribers/active?filter=(operator eq "Konnect" or operator eq "Wavez") and physicalId lt "8944999999248275001"