Filters

List endpoints return descriptions of a list of resources. You can filter the list to include only items matching certain criteria by supplying filter parameters.

You can filter resources based on exact values, ranges of values, or existence of values for any of their properties, or the properties of related resources. You can supply separate filters for any number of properties, which will be applied in conjunction.

See the documentation page on dynamic paths for more information about how to specify filter paths.

Filter Paths

A simple exact value filter parameter may have the form:

{property}={value}

Where {property} is short name (or JSON name) of the property to check the values of, and {value} is the exact value that is required to satisfy the filter.

The short name of a property is usually the last segment of the property URI, but otherwise you can find it in the model documentation for the API.

However, you can also write the parameter name as a .-separated property path, for example:

{prop1}.{prop2}...{propn}={value}

Where {prop1}.{prop2}...{propn} denotes path that traverses the related resources in the graph. As before, each property in the path is identified by its short name.

Filter Values

In the example above, the filter value could be a string, number, date, date-time or the URI of another resource.

URIs

When filtering on resource values, you can reference the resource by its URI or its compact URI, based on the prefix mapping defined for the API. You can find the prefix mapping for the API in the reference documentation or model documentation.

Note that when URIs are supplied in query parameters, they must be correctly encoded.

For example, to request only resources whose type is skos:Concept, you could supply the query parameter and value:

type=skos:Concept

or

type=http%3A%2F%2Fwww.w3.org%2F2004%2F02%2Fskos%2Fcore%23Concept

In some cases, you can also reference resources by just their short names, eg.

type=Concept

Dates and Times

Dates and date-times should be written in ISO format. When filtering on a range of date-times, to ensure accurate comparison, you should include the timezone on the timestamp that you want to compare values to. For example, to write a timestamp in UTC time, append a Z to the end. See here for more information.

Filter Sets

You can request a filter which on a disjunctive set of values simply by supplying multiple values for a single property path. For example, the filter:

label=colour&label=color

is satisfied by any resource whose label is either “colour” or “color”.

Filter Ranges

You can filter resources based on a range of values by prepending one of the following prefixes to the filter parameter name.

For example, the filter;

mineq-dob=1993-03-12

would be satisfied be resources whose dob is on or after 12/03/1993. To specify a bounded range, you can combine less-than and greater-then filters. For example, the filter;

mineq-dob=1993-03-12&maxeq-dob=2003-03-12

would be satisfied by resources whose dob is between 12/03/1993 and 12/03/2003.

Alternatively, you can specify a bounded range filter using parenthesis notation. Enclose the lower and upper bounds with ( and ) for exclusive bounds, or (* and *) for inclusive bounds. The boundary values should be separated with ...

The example above could be written as:

dob=(*1993-03-12..2003-03-12*)

You can also use a mixture of inclusive and exclusive bounds.

Existential Filters

You can also filter based on the existence or non-existence of values on the given property path by prepending the exists- prefix to the path and setting the value to either true or false respectively.

For example, the filter:

exists-inspection=true

would be satisfied by resources which have an inspection value.