Filtering and Sorting Results

The API supports narrowing down the result set on each of the index pages via a filtering mechanism. Filters are passed as GET parameters, and you can add as many filters as you'd like to each request. Here are a few example urls:

# Returns all vehicles where the color is red
https://api.fleetmanagermobile.com/v1/vehicles?q[color_eq]=red

# Returns all vehicles that are 2010 or newer
https://api.fleetmanagermobile.com/v1/vehicles?q[year_gteq]=2010

# Returns all vehicles where the color is red AND the model year is 2010 or newer
https://api.fleetmanagermobile.com/v1/vehicles?q[color_eq]=red&q[year_gteq]=2010

Let's see how those filters are constructed.

Building a Filter

You may have noticed a pattern emerging from the filters in the above examples. For one, each filter is wrapped in a q[] block. You'll also notice that inside the q[] is what appears to be a field name combined with an operator. Finally, being GET parameters, each filter is assigned a value. Let's break down each piece.

q[]

This is simply something we use to differentiate filter parameters from regular parameters. If a parameter is wrapped in q[], then we know for a fact that you're trying to filter. Be sure to always wrap your parameters in q[].

The filter name

The filter name is a combination of two things, a field name and an operator, which we call the predicate. The field name is just that, the name of the field to which you want to apply the filter. The predicate is the operation that is applied to the field. We currently support the following predicates:

• eq (equals, case sensitive)
• matches (case insensitive)
• lt (less than)
• lteq (less than or equal to)
• gt (greater than)
• gteq (greater than or equal to)
• cont (contains, used for matching partial strings)

To construct the filter name, simply concatenate the field name and the predicate, adding an underscore in between.

The value

You've already told us what you want to narrow down and how, but you haven't yet told us by what. This is where the value comes in. If you want all vehicles where the color is red, you simply pass red as the value to q[color_eq]=. If you want all vehicles where the id > 100, 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 the completed services that have been created since January 1st, 2016. You take the field name, date, concatenate with the greater than or equal to predicate, gteq, add an underscore, and wrap it in q[]. The resulting filter is q[date_gteq]. Now just add the value. In our case we want anything >= 2016-01-01, resulting in q[date_gteq]=2016-01-01.

Sorting

We treat sorting as just another q[] wrapped predicate, q[s]. Here are a few examples:

# Sort vehicles by unit # in ascending order
https://api.fleetmanagermobile.com/v1/vehicles?q[s]=unit_number+asc

# Sort vehicles by unit # in descending order
https://api.fleetmanagermobile.com/v1/vehicles?q[s]=unit_number+desc

# Sort vehicles by unit # without specifying an order, defaults to asc
https://api.fleetmanagermobile.com/v1/vehicles?q[s]=unit_number