Filtering

Learn how to filter GET requests to the Wunderite API. Filterable fields are defined in the object model for each endpoint. They are denoted as Filterable in the field's description, along with the type of filtering that's supported.

Filter query parameters

All GET requests to the Wunderite API support filtering by one or more fields.
When more than one filter is specified, all filters are combined using the AND operator.

To use a filter, provide a query parameter in the format filter[field]=value.

Exact

An exact filter will only return results that match the exact value you provide.
This is used for all fields that you want to match exactly, such as a uuid.

For example, a uuid filter will only return results that match the exact UUID you provide. filter[uuid]=8f2c9f0a-cd6a-4ea7-9ed3-b5d013d01c5b

Filtered response

{
  "data": [
    {
      "object": "building",
      "uuid": "8f2c9f0a-cd6a-4ea7-9ed3-b5d013d01c5b",
      // ...
    }
  ]
}

Partial

A partial filter will return any results that contain the value you provide using a fuzzy match.
This is used for fields that you want to match any part of, such as a name or description.

For example, a description filter will return results that contain any portion of the value you provide. filter[description]=Jon

Filtered response

{
  "data": [
    {
      "object": "building",
      "uuid": "8f2c9f0a-cd6a-4ea7-9ed3-b5d013d01c5b",
      "data": { "description": "Jonathan's Building", ... },
      // ...
    },
    {
      "object": "building",
      "uuid": "8f2c9f0a-cd6a-4ea7-9ed3-b5d013d55c5b",
      "data": { "description": "Owned by Jonah", ... },
      // ...
    }
  ]
}

Operator

An operator filter will return results that match the operator you provide. This is used for fields that you want to match using a specific operator, such as a number.

The available operators are:

= (equal)
!= (not equal)
> (greater than)
>= (greater than or equal to)
< (less than)
<= (less than or equal to)

To specify an operator, provide the operator in the format filter[field]={operator}value. To specify multiple operators, provide a comma-separated list of operators in the format filter[field]={operator}value,{operator}value.

Equal

For example, a number operator filter to filter for numbers equal to 5.

filter[number]=5

# or, making sure to URL encode the `=` inside of the query parameter value
`filter[number]=%3D5`

Filtered response

{
  "data": [
    { "data": { "number": 5, ... }, "object": "building", "uuid": "1f2c9f0a-cd6a-4ea7-9ed3-b5d013d01c5b", ...},
    // ...
  ]
}

Not Equal

For example, a number operator filter to filter for numbers not equal to 3.

# making sure to URL encode the `=` inside of the query parameter value
`filter[number]=!%3D3`

Filtered response

{
  "data": [
    { "data": { "number": 1, ... }, "object": "building", "uuid": "8f2c9f0a-cd6a-4ea7-9ed3-b5d013d01c5b", ...},
    { "data": { "number": 2, ... }, "object": "building", "uuid": "9f2c9f0a-cd6a-4ea7-9ed3-b5d013d01c5b", ...},
    { "data": { "number": 4, ... }, "object": "building", "uuid": "0f2c9f0a-cd6a-4ea7-9ed3-b5d013d01c5b", ...},
    { "data": { "number": 5, ... }, "object": "building", "uuid": "1f2c9f0a-cd6a-4ea7-9ed3-b5d013d01c5b", ...},
  ]
}

Greater than

For example, a number operator filter to filter for numbers greater than 5.

# making sure to URL encode the `>` inside of the query parameter value
filter[number]=%3E5

Filtered response

{
  "data": [
    { "data": { "number": 6, ... }, "object": "building", "uuid": "9f2c9f0a-cd6a-4ea7-9ed3-b5d013d01c5b", ...},
    { "data": { "number": 7, ... }, "object": "building", "uuid": "0f2c9f0a-cd6a-4ea7-9ed3-b5d013d01c5b", ...},
  ]
}

Greater than or equal to

For example, a number operator filter to filter for numbers greater than or equal to 5.

# making sure to URL encode the `>=` inside of the query parameter value
filter[number]=%3E%3D5

Filtered response

{
  "data": [
    { "data": { "number": 5, ... }, "object": "building", "uuid": "8f2c9f0a-cd6a-4ea7-9ed3-b5d013d01c5b", ...},
    { "data": { "number": 6, ... }, "object": "building", "uuid": "9f2c9f0a-cd6a-4ea7-9ed3-b5d013d01c5b", ...},
    { "data": { "number": 7, ... }, "object": "building", "uuid": "0f2c9f0a-cd6a-4ea7-9ed3-b5d013d01c5b", ...},
  ]
}

Less than

For example, a number operator filter to filter for numbers less than 3.

# making sure to URL encode the `<` inside of the query parameter value
filter[number]=%3C3

Filtered response

{
  "data": [
    { "data": { "number": 1, ...}, "object": "building", "uuid": "9f2c9f0a-cd6a-4ea7-9ed3-b5d013d01c5b", ...},
    { "data": { "number": 2, ...}, "object": "building", "uuid": "0f2c9f0a-cd6a-4ea7-9ed3-b5d013d01c5b", ...},
  ]
}

Less than or equal to

For example, a number operator filter to filter for numbers less than or equal to 3.

# making sure to URL encode the `<=` inside of the query parameter value
filter[number]=%3C%3D3

Filtered response

{
  "data": [
    { "data": { "number": 1, ... }, "object": "building", "uuid": "8f2c9f0a-cd6a-4ea7-9ed3-b5d013d01c5b", ...},
    { "data": { "number": 2, ... }, "object": "building", "uuid": "9f2c9f0a-cd6a-4ea7-9ed3-b5d013d01c5b", ...},
    { "data": { "number": 3, ... }, "object": "building", "uuid": "0f2c9f0a-cd6a-4ea7-9ed3-b5d013d01c5b", ...},
  ]
}

Between (using compound operators)

For example, a compound number operator filter to filter for numbers between 2 and 5 (inclusive).

# making sure to URL encode the `>=` and `<=` inside of the query parameter value
filter[number]=%3E%3D2,%3C%3D5

Filtered response

{
  "data": [
    {"data": { "number": 2, ... }, "object": "building", "uuid": "8f2c9f0a-cd6a-4ea7-9ed3-b5d013d01c5b", ...},
    {"data": { "number": 3, ... }, "object": "building", "uuid": "9f2c9f0a-cd6a-4ea7-9ed3-b5d013d01c5b", ...},
    {"data": { "number": 4, ... }, "object": "building", "uuid": "0f2c9f0a-cd6a-4ea7-9ed3-b5d013d01c5b", ...},
    {"data": { "number": 5, ... }, "object": "building", "uuid": "1f2c9f0a-cd6a-4ea7-9ed3-b5d013d01c5b", ...},
  ]
}

Date

A date filter will return results that match the date you provide. Or, if you provide a date range (delimited by a comma), it will return results that fall within that range.

Single date example

For example, a created filter with only a single date will return results that were created on that date. filter[created]=2025-01-01

Filtered response

{
  "data": [
    {
      "object": "building",
      "uuid": "8f2c9f0a-cd6a-4ea7-9ed3-b5d013d01c5b",
      "meta": { "created": "2025-01-01T00:00:00Z", ... },
      // ...
    },
    {
      "object": "building",
      "uuid": "8f2c9f0a-cd6a-4ea7-9ed3-b5d013d55c5b",
      "meta": { "created": "2025-01-01T00:50:00Z", ... },
      // ...
    }
  ]
}

Date range example

For example, a created filter with a date range will return results that were created within that range. filter[created]=2025-01-01,2025-01-02

Filtered response

{
  "data": [
    {
      "object": "building",
      "uuid": "8f2c9f0a-cd6a-4ea7-9ed3-b5d013d01c5b",
      "meta": { "created": "2025-01-01T00:00:00Z", ... },
      // ...
    },
    {
      "object": "building",
      "uuid": "8f2c9f0a-cd6a-4ea7-9ed3-b5d013d55c5b",
      "meta": { "created": "2025-01-02T00:50:00Z", ... },
      // ...
    }
  ]
}