Skip to main content

Constructing Filters and Sorts

Fleetio is introducing a new, simpler method to filter and sort results. During the transition to this new method, there will be endpoints where the original q[] sorting is used, and new endpoints where the new sorting will be used instead.

info

The new filtering and sorting methods only exist in API versions starting with 2024-01-01. They can be identified by the response, which returns an object with pagination data, applied filters and sorts, and the array of records in the records attribute.

New filtering and sorting method (for endpoints which accept filter and sort query params)​

Filters​

  • Filters are constructed using filter[<field_name>][<operator>]=<value> as query parameters in the url.
  • The available filters and operators for an endpoint can be found in the response schema filtered_by attribute.
  • Filters applied to a response are returned as an array in the filtered_by response attribute.
  • The q[] filter format is not available.

Sorts​

  • Sorts are constructed using the sort[<field_name>]=<direction> as query parameters in the url.
  • The available sorts for an endpoint can be found in the response schema sorted_by attribute.
  • Sorts applied to a response are returned as an array in the sorted_by response attribute.
  • The q[s] sort format is not available.

Examples​

/api/v1/vehicles?filter[name][like]=foo&sort[created_at]=desc

Would result in records containing Vehicles with name including the characters foo, ordered by created_at from newest to oldest.

/api/v1/vehicles?filter[labels][include]=green,blue&filter[license_plate][like]=yz

Would result in records containing Vehicles with labels of blue or green, and license_plate containing the characters yz.

Original filtering and sorting method (for endpoints which do not accept filter and sort query params)​

Filters​

  • Each filter is wrapped in a q[] block.
  • Inside each q[] block is a condition (an attribute combined with a predicate).
  • Each query parameter is assigned a value.

Sorts​

  • Sorts still include a q[] block, but follow a slightly different syntax: q[s]=attribute+order
  • order can be asc or desc
  • The default sort order is asc if no order is passed. So, q[s]=attribute is also valid.

The Filter Parameter​

Values​

The condition represents which properties to use for filtering and how to filter them, but we still need a target value to apply. For example, to retrieve all vehicles where the color is "red", you can pass red as the value to the q[color_eq]= filter parameter. If you want all vehicles with an id greater than 100, you can pass 100 as the value to q[id_gt]=.

Bringing it Together​

Let's say that you want to construct a filter that returns all Vehicles created after January 1st, 2016. You take the attribute, created_at, and join it with the gteq predicate with an underscore, then wrap it in q[], and set the value to 2016-01-01.

q[created_at_gteq]=2016-01-01

To retrieve the same result set, but filtering out vehicles that have no license plate, add another filter using the null predicate:

q[created_at_gteq]=2016-01-01&q[license_plate_null]=1

The Sort Parameter​

You can sort by any attribute in Fleetio. Sorts can be passed by themselves, or combined with filters. Here's what a sort could look like appended to the above examples:

q[created_at_gteq]=2016-01-01&q[s]=updated_at
q[created_at_gteq]=2016-01-01&q[license_late_null]=1&q[s]=make+desc