Filtering

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.

Single property

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:

GET /api/items?is_present=true

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:

GET /api/events?topic.resource_type=items

Multiple properties

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:

GET /api/items?is_present=true&technology=rfid&type=tag

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:

GET /api/presences?proximity=immediate&proximity=near

ID references

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_url (default), location_id or 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 5b685177bf98c63603ee818b:

GET /api/presences?location=5b685177bf98c63603ee818b

Time range

The special query parameters before and 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, 2023 and January 6th, 2023:

GET /api/events?after=2023-01-05T00:00:00Z&before=2023-01-06T00:00:00Z

ID range

Similar to querying time ranges, the query parameters before_id and 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 until_id and from_id function the same but are inclusive. The inclusive and exclusive variants cannot be mixed in the same query.

Code range

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:

GET /api/items?from_code=a5b0&until_code=a5b2

The variants after_code and before_code function the same but are exclusive. The inclusive and exclusive variants cannot be mixed in the same query.

Select returned properties

Note: select is only supported on Brain versions 3.6.0 and later.

Select can be used to limit the returned properties of records to the provided selection as required for the usecase. For example, the following request would limit the returned properties of the item records to only the identifier:

GET /api/items?select=id

For example, the following request would limit the returned properties of the item record to the identifier and the label:

GET /api/items?select=id,label