When retrieving records from the REST API using HTTP GET requests, it is possible to filter a resource's records by property values with query parameters in the request URL. These filtering possibilities are discussed in this article.
To retrieve only records where a certain property has a certain value, simply use the property name as a query parameter. For example, the following request would retrieve only present items:
Some properties of REST API records are objects, which have properties themselves. To filter on such a nested property, use a dot separator. For example, the following request would retrieve events related to the items resource:
Filtering by multiple properties is possible and will always be interpreted as an AND operation; records are only returned when they match all of the given property conditions. For example, the following request would retrieve only present RFID tags:
The REST API does not support an OR operation on multiple properties. To achieve this, instead perform multiple queries and merge the results.
Multiple values for single property
When the same property is given multiple times (with different values), this is interpreted as an OR operation; any of the given values is accepted for that property. For example, the following request would retrieve presences with an "immediate" or "near" proximity:
Some resources have references to records in other resources, which may appear in different formats depending on query parameters; for example, a location reference may appear in query results as
location (see ID reference formats). Regardless of the reference format in the response, to filter based on a reference simply use the base resource name with the ID to filter on. For example, the following request would retrieve presences at location
The special query parameters
after can be used to select records that were created before and/or after a certain point in time. The time should be formatted as an ISO 8601 date-time string. For example, the following query would retrieve events between January 5th, 2019 and January 6th, 2019:
Similar to querying time ranges, the query parameters
after_id can be used to select records older or newer than a certain record's ID.
Note that these are exclusive, i.e.
before_id=12ab will not match the record with ID
12ab. The variants
from_id function the same but are inclusive. The inclusive and exclusive variants cannot be mixed in the same query.
Note: code range is only supported on Brain versions 2.9.0 and later.
Using the query parameters from_code and until_code it is possible to filter on a range of the code_hex field of items. This can be useful with items that have codes programmed in a pattern, such as a batch of RFID tags with sequential numbering. For example, the following query would the retrieve the items with codes a5b0, a5b1 and a5b2:
before_code function the same but are exclusive. The inclusive and exclusive variants cannot be mixed in the same query.