{"_id":"57c06e6264ebf60e00688715","parentDoc":null,"project":"54c0e51215af820d001a38a6","__v":1,"category":{"_id":"54f8de4e4339bb1900c8bffc","__v":1,"pages":["54f8de4f4339bb1900c8c010","54f8de4f4339bb1900c8c011","54f8de4f4339bb1900c8c012","54f8de4f4339bb1900c8c013"],"project":"54c0e51215af820d001a38a6","version":"54f8de4e4339bb1900c8bffb","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-01-22T11:54:59.216Z","from_sync":false,"order":0,"slug":"fleetio-api","title":"Fleetio API"},"user":"54cba76f6d1eee0d00c33dee","version":{"_id":"54f8de4e4339bb1900c8bffb","project":"54c0e51215af820d001a38a6","forked_from":"54f8de14c6cabe23005c02a2","__v":31,"createdAt":"2015-03-05T22:53:02.044Z","releaseDate":"2015-03-05T22:53:02.044Z","categories":["54f8de4e4339bb1900c8bffc","54f8de4e4339bb1900c8bffd","54f8de4e4339bb1900c8bffe","54f8de4e4339bb1900c8bfff","54f8de4e4339bb1900c8c000","54ff6057563d7419002d666e","55007b6ecfeeea17004717dc","5501d779f2ef1e0d003116eb","55116ef89f7c7619005f853b","554bb366f245703100ddd39f","554d226b374fec0d007e64db","555e09f18ab3180d001ac605","555e0b2b4f5e5a0d00836d77","561d1f8b92a0cc350018b24f","562a956c96b5f40d0026eb60","5654c3378a26202b00c17cb8","5697a94b0b09a41900b24546","5739d89e37b52e3200a3a3cc","57ac94252c0b220e00a94570","57ac97a1ad44fc0e003be066","57ac9a3a8f312d0e00e96c75","57ac9c187ae5c60e004ba3a3","58178bee62e4500f009404f6","581a39711a63870f008b621d","581a3b4f0c65b20f00247fcb","5926e0606c729e0f00595f95","5954033ea5bbca002d27ae91","596ce53e0aeafe00157eb1ba","596ce87a8b79f4001a8f6139","598cad2e96193400190d879a","598cbcd3dc20c6000fdfb9c3","598cbd8496193400190d8955","59fcc7c9591add0026c91457","5a020b7856ea82001c8c9342","5a09bc64a91882001c56c2ed"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-08-26T16:29:22.794Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":5,"body":"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:\n\n```\n# Returns all vehicles where the color is red\nhttps://secure.fleetio.com/api/v1/vehicles?q[color_eq]=red\n\n# Returns all vehicles that are 2010 or newer\nhttps://secure.fleetio.com/api/v1/vehicles?q[year_gteq]=2010\n\n# Returns all vehicles that have a secondary meter\nhttps://secure.fleetio.com/api/v1/vehicles?q[secondary_meter_true]=1\n\n# Returns all vehicles where the color is red AND the model year is 2010 or newer\nhttps://secure.fleetio.com/api/v1/vehicles?q[color_eq]=red&q[year_gteq]=2010\n```\n\nLet's talk about how filters are constructed.\n\n## Constructing a filter\n\nYou 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.\n\n### q[]\n\nThis 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[]`.\n\n### The filter name\n\nThe 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:\n\n* eq (equals)\n* lt (less than)\n* lteq (less than or equal to)\n* gt (greater than)\n* gteq (greater than or equal to)\n* cont (contains, used for matching partial strings)\n* true (boolean operator for true)\n* false (boolean operator for false)\n* present\n* null\n\nTo construct the filter name, simply concatenate the field name and the predicate, adding an underscore in between.\n\n### The value\n\nYou'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]=`.\n\nThe value is a bit different for the `true`, `false`,  `present`, and `null` predicates. We aren't comparing them with any value, we simply want the records where the predicate evaluates to true. When dealing with these four predicates, you can pass any value as long as it's not blank. Here at Fleetio we like to use `1` as the value, but that's just our personal preference.\n\n### Bringing it together\n\nLet's say that you want to construct a filter that returns all vehicles that have been created since January 1st, 2016. You take the field name, `created_at`, concatenate with the greater than or equal to predicate, `gteq`, add an underscore, and wrap it in q[]. The resulting filter is `q[created_at_gteq]`. Now just add the value. In our case we want anything >= 2016-01-01, resulting in `q[created_at_gteq]=2016-01-01`.\n\nWhat if we want that same result set, but only for vehicles that have no license plate? We just add another filter to our request using the `null` predicate: `q[license_plate_nul]l=1`. The resulting url is:\n\n```\nhttps://secure.fleetio.com/api/v1/vehicles?q[created_at_gteq]=2016-01-01&q[license_plate_null]=1\n```\n\n## And & Or\n\nWe take all filters in a request and `AND` them together. There is currently no support for `OR`. The best solution for applying `OR` filters is to just issue several requests.\n\n## Custom Fields\n\nCustom fields require their own special filters. To tell Fleetio that you're searching for a custom field, your field name needs to be in this format:\n\n`custom_field_CUSTOM_FIELD_NAME_PREDICATE`\n\n`CUSTOM_FIELD_NAME` is the name of your custom field in Fleetio, for example: `invoice_number`\n`PREDICATE` is any predicate from the following list: \n\n* eq (equals)\n* not_eq (not equals)\n* cont (contains)\n* not_cont (does not contain)\n* start (starts with)\n* end (ends with)\n\nPutting it all together, if you wanted to search for a work order with a custom field named `invoice_number` containing the string 123, you would make the following call to the API:\n\n```\nhttps://secure.fleetio.com/api/v1/work_orders?q[custom_field_invoice_number_cont]=123\n```\n\n### Checkbox custom field types\n\nCheckbox (boolean) custom field values are stored as \"true\" or \"false\" strings, so if you wanted to search Work Orders for a boolean custom field named `paid`, you would make the following call:\n\n```\nhttps://secure.fleetio.com/api/v1/work_orders?q[custom_field_paid_eq]=true\n```\n\n## Sorting\n\nWe treat sorting as just another `q[]` wrapped predicate, `q[s]`. Here are a few examples:\n\n```\n# Sort vehicles by name in ascending order\nhttps://secure.fleetio.com/api/v1/vehicles?q[s]=name+asc\n\n# Sort vehicles by name in descending order\nhttps://secure.fleetio.com/api/v1/vehicles?q[s]=name+desc\n\n# Sort vehicles by name without specifying an order, defaults to asc\nhttps://secure.fleetio.com/api/v1/vehicles?q[s]=name\n\n# You can sort by any field\nhttps://secure.fleetio.com/api/v1/vehicles?q[s]=created_at+desc\n\n# You can combine sorting and filters in a single request\nhttps://secure.fleetio.com/api/v1/vehicles?q[created_at_gteq]=2016-01-01&q[license_plate_null]=1&q[s]=created_at+desc\n```\n\n## Not just for vehicles!\n\nYou can apply filters to any of the \"index\" endpoints that we provide. Want to get all of the fuel entries since January 1st?\n\n`https://secure.fleetio.com/api/v1/fuel_entries?q[created_at_gteq]=2016-01-01`\n\nWant all meter entries where the void flag is set to true?\n\n`https://secure.fleetio.com/api/v1/meter_entries?q[void_true]=1`\n\nWant to know if the number of Freds you have working in your company is too high?\n\n`https://secure.fleetio.com/api/v1/contacts?q[first_name_eq]=Fred`\n\nThe possibilities are endless!*\n\n_* Possibilities actually finite_","excerpt":"","slug":"filtering-results","type":"basic","title":"Filtering and Sorting Results"}

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://secure.fleetio.com/api/v1/vehicles?q[color_eq]=red # Returns all vehicles that are 2010 or newer https://secure.fleetio.com/api/v1/vehicles?q[year_gteq]=2010 # Returns all vehicles that have a secondary meter https://secure.fleetio.com/api/v1/vehicles?q[secondary_meter_true]=1 # Returns all vehicles where the color is red AND the model year is 2010 or newer https://secure.fleetio.com/api/v1/vehicles?q[color_eq]=red&q[year_gteq]=2010 ``` Let's talk about how filters are constructed. ## Constructing 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) * 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) * true (boolean operator for true) * false (boolean operator for false) * present * null 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]=`. The value is a bit different for the `true`, `false`, `present`, and `null` predicates. We aren't comparing them with any value, we simply want the records where the predicate evaluates to true. When dealing with these four predicates, you can pass any value as long as it's not blank. Here at Fleetio we like to use `1` as the value, but that's just our personal preference. ### Bringing it together Let's say that you want to construct a filter that returns all vehicles that have been created since January 1st, 2016. You take the field name, `created_at`, concatenate with the greater than or equal to predicate, `gteq`, add an underscore, and wrap it in q[]. The resulting filter is `q[created_at_gteq]`. Now just add the value. In our case we want anything >= 2016-01-01, resulting in `q[created_at_gteq]=2016-01-01`. What if we want that same result set, but only for vehicles that have no license plate? We just add another filter to our request using the `null` predicate: `q[license_plate_nul]l=1`. The resulting url is: ``` https://secure.fleetio.com/api/v1/vehicles?q[created_at_gteq]=2016-01-01&q[license_plate_null]=1 ``` ## And & Or We take all filters in a request and `AND` them together. There is currently no support for `OR`. The best solution for applying `OR` filters is to just issue several requests. ## Custom Fields Custom fields require their own special filters. To tell Fleetio that you're searching for a custom field, your field name needs to be in this format: `custom_field_CUSTOM_FIELD_NAME_PREDICATE` `CUSTOM_FIELD_NAME` is the name of your custom field in Fleetio, for example: `invoice_number` `PREDICATE` is any predicate from the following list: * eq (equals) * not_eq (not equals) * cont (contains) * not_cont (does not contain) * start (starts with) * end (ends with) Putting it all together, if you wanted to search for a work order with a custom field named `invoice_number` containing the string 123, you would make the following call to the API: ``` https://secure.fleetio.com/api/v1/work_orders?q[custom_field_invoice_number_cont]=123 ``` ### Checkbox custom field types Checkbox (boolean) custom field values are stored as "true" or "false" strings, so if you wanted to search Work Orders for a boolean custom field named `paid`, you would make the following call: ``` https://secure.fleetio.com/api/v1/work_orders?q[custom_field_paid_eq]=true ``` ## Sorting We treat sorting as just another `q[]` wrapped predicate, `q[s]`. Here are a few examples: ``` # Sort vehicles by name in ascending order https://secure.fleetio.com/api/v1/vehicles?q[s]=name+asc # Sort vehicles by name in descending order https://secure.fleetio.com/api/v1/vehicles?q[s]=name+desc # Sort vehicles by name without specifying an order, defaults to asc https://secure.fleetio.com/api/v1/vehicles?q[s]=name # You can sort by any field https://secure.fleetio.com/api/v1/vehicles?q[s]=created_at+desc # You can combine sorting and filters in a single request https://secure.fleetio.com/api/v1/vehicles?q[created_at_gteq]=2016-01-01&q[license_plate_null]=1&q[s]=created_at+desc ``` ## Not just for vehicles! You can apply filters to any of the "index" endpoints that we provide. Want to get all of the fuel entries since January 1st? `https://secure.fleetio.com/api/v1/fuel_entries?q[created_at_gteq]=2016-01-01` Want all meter entries where the void flag is set to true? `https://secure.fleetio.com/api/v1/meter_entries?q[void_true]=1` Want to know if the number of Freds you have working in your company is too high? `https://secure.fleetio.com/api/v1/contacts?q[first_name_eq]=Fred` The possibilities are endless!* _* Possibilities actually finite_