{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","params":[],"results":{"codes":[]},"settings":""},"next":{"description":"","pages":[]},"title":"GPS Integration Guide","type":"basic","slug":"gps-integration-guide","excerpt":"","body":"We're expanding our API in an effort to make working with GPS providers easier. We currently support a number of GPS related functions:\n\n1. Odometer Updates\n2. Faults / DTC Alerts\n3. Vehicle Location\n4. Fuel Entry Location\n\nIn this tutorial you'll find step by step instructions and code snippets to help you get started. You can also refer to the documentation for each endpoint for more details.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Users\"\n}\n[/block]\nBefore we get started I should say a few words about users, authentication, and authorization.\n\nA user in Fleetio works pretty much how you'd expect. Users can login, modify data, and belong to multiple organizations, which we call accounts. A user has a defined set of permissions within an account. Some users can create vehicles and manage their fuel and odometer history; others can't. It's important to make sure that the user whose credentials you use to interact with the API has the correct set of permissions. You can read more about our permissions [here](http://help.fleetio.com/article/46-user-roles-and-permissions).\n\nEach request to the API must be accompanied by the user's API key and an account token. Instructions on how to obtain these can be found on our [overview page](http://developer.fleetio.com/).\n\nSo now that you have a user, an API key, and an account token, it's time to start using the API. Here's an example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl \\\\\\n--include \\\\\\n--header \\\"Authorization: Token API_KEY\\\" \\\\\\n--header \\\"Account-Token: ACCOUNT_TOKEN\\\" \\\\\\n\\\"https://secure.fleetio.com/api/v1/users/me\\\"\\n\\n{\\\"id\\\":1,\\\"username\\\":\\\"test:::at:::example.com\\\",\\\"first_name\\\":\\\"Test\\\",\\\"last_name\\\":\\\"Example\\\",\\\"email\\\":\\\"[email protected]\\\",\\\"fuel_economy_units\\\":\\\"mpg_us\\\",\\\"time_zone_name\\\":\\\"Central Time (US & Canada)\\\",\\\"time_zone_offset_in_seconds\\\":-21600,\\\"created_at\\\":\\\"2013-09-23T02:09:30.607-05:00\\\",\\\"updated_at\\\":\\\"2016-03-30T16:43:05.158-05:00\\\"}\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n*Note that the authorization token is preceded by `Authorization: Token`. We require this because we accept multiple types of authorization methods.*\n\nIn this example, I queried the `/users/me` end point which returns useful information about the current user such as email, name, and time zone.\n\nAll right, that covers users, let's move on to Odometer updates.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"1. Odometer Updates\"\n}\n[/block]\nOdometer updates are called meter entries in Fleetio. We have a dedicated section for creating them [here](https://developer.fleetio.com/docs/create-meter-entry) if you want to get down to the nitty gritty.\n\nWe recommend updating a vehicle's odometer on a regular basis, such as once per day. This should be enough for most scenarios, but certain use cases may require more frequent updates.\n\nThere's one important difference between creating a regular meter entry and a GPS meter entry. When creating GPS meter entries please be sure to provide two extra parameters, `gps` and `gps_provider`. The `gps` param is a boolean and must be set to true and the `gps_provider` is the name of your organization/product/service as you would like it to appear to end users within Fleetio. \n\nHere's a snippet showing how to create a GPS meter entry:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl \\\\\\n--include \\\\\\n--header \\\"Authorization: Token API_KEY\\\" \\\\\\n--header \\\"Account-Token: ACCOUNT_TOKEN\\\" \\\\\\n--data \\\"&value=1000&date=2016-05-06&vehicle_id=123&gps=true&gps_provider=My Company Name\\\" \\\\\\n\\\"https://secure.fleetio.com/api/v1/meter_entries\\\"\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"2. Faults / DTC Alerts\"\n}\n[/block]\nCreating Faults in Fleetio is pretty straightforward and the process for GPS partners is the same as any other API user. Here's the [docs for creating Faults](https://developer.fleetio.com/docs/create-fault).\n[block:api-header]\n{\n  \"title\": \"3. Vehicle Location\"\n}\n[/block]\nHistorical vehicle locations are stored in Fleetio via Location Entries. You can learn about how Location Entries are used in the Fleetio UI by referencing the [Vehicle Location History Help Center Article](https://help.fleetio.com/hc/en-us/articles/360019526051-Vehicle-Location-History). If you're interested in creating Location Entries via the API, you can look at the [docs for creating Location Entries](https://developer.fleetio.com/docs/create-location-entry).\n\nHere's a snippet showing how to create a Location Entry.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl \\\\\\n--include \\\\\\n--request POST \\\\\\n--header \\\"Authorization: Token API_KEY\\\" \\\\\\n--header \\\"Account-Token: ACCOUNT_TOKEN\\\" \\\\\\n--header \\\"Content-Type: application/json\\\" \\\\\\n--data '{\\\"vehicle_id\\\": 1234, \\\"date\\\": \\\"2019-08-25 12:00:00 -0600\\\", \\\"latitude\\\": 33.477536, \\\"longitude\\\": -86.771141}' \\\\\\n\\\"https://secure.fleetio.com/api/v1/location_entries/\\\"\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"4. Fuel Entry Location\"\n}\n[/block]\nFuel Entries in Fleetio can have location data associated with them, detailing the vehicle's location at the time of the fill up. This serves two main purposes:\n\n1. Provides a map based visual representation of the location on the Fuel Entry's detail page:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/8596498-fuel-entry-page.jpg\",\n        \"fuel-entry-page.jpg\",\n        2880,\n        1536,\n        \"#f1f2f1\"\n      ],\n      \"caption\": \"The fuel entry page showing information about a specific fuel up.\"\n    }\n  ]\n}\n[/block]\n2. Fuel exception alerts. If a vehicle's position at the time of a fill up is greater than 1/4 mile from the reported vendor's location, a fuel exception alert will fire. This alert will send an email to the account owner:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/1f86e43-fuel-location-exception-email.jpg\",\n        \"fuel-location-exception-email.jpg\",\n        1682,\n        1244,\n        \"#f1f2dd\"\n      ],\n      \"caption\": \"An example of the fuel exception email sent to the account owner.\"\n    }\n  ]\n}\n[/block]\nAnd it will be visible on the fuel entry's map as a warning message.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/2bea448-fuel-location-exception.jpg\",\n        \"fuel-location-exception.jpg\",\n        1922,\n        698,\n        \"#ededea\"\n      ],\n      \"caption\": \"The exception alert on a fuel entry's detail page.\"\n    }\n  ]\n}\n[/block]\nNow that we know why fuel entry GPS data is useful in Fleetio, let's check out how to get it all working.\n\n# Fetching relevant fuel entries\n\nThe first thing to understand is that a single Fuel Entry can have multiple types of location data associated with it - i.e. it can have the location of the gas station where the fuel-up occurred, and it can have the location reported by the vehicle's telematics hardware at the time the fuel-up occurred. By comparing these two coordinates to see if they match or are in close proximity, we can determine if the vehicle was actually present at the gas station when the fuel-up occurred (or if it was somewhere else, indicating a possible fraudulent fuel-up.\n\nThe location of the gas station is stored automatically on the Fuel Entry if a `vendor_id` is saved on the Fuel Entry, and if that Vendor's location is saved in Fleetio. So when a Fuel Entry is created, all you have to do is give it a `vendor_id`, and that Vendor's location will be saved as the location where the fuel-up occurred. (If a Fleetio customer has a fuel integration in Fleetio with one of our supported Fuel Card partners, this process happens automatically.)\n\nThe second part of the process is saving the vehicle's location at the time of the fuel-up as reported by the onboard telematics hardware. To do this, the first thing is to fetch any and all Fuel Entries that need to be updated. Use the /fuel_entries endpoint to get a list of entries back. Here are the [docs for fetching Fuel Entries](https://developer.fleetio.com/docs/fuel-entries), and here is an example of how you'd fetch these Fuel Entries.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl \\\\\\n--include \\\\\\n--header \\\"Authorization: Token API_KEY\\\" \\\\\\n--header \\\"Account-Token: ACCOUNT_TOKEN\\\" \\\\\\n\\\"https://secure.fleetio.com/api/v1/fuel_entries\\\"\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\nThat gets us a list of Fuel Entries, but it's not exactly what we want as it gets us _too many_ results. Fortunately, we can narrow down the result set by passing [filters](https://developer.fleetio.com/docs/filtering-results) to the API. In this example we only want fuel entries that were created today and do not currently have GPS data.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl \\\\\\n--include \\\\\\n--header \\\"Authorization: Token API_KEY\\\" \\\\\\n--header \\\"Account-Token: ACCOUNT_TOKEN\\\" \\\\\\n\\\"https://secure.fleetio.com/api/v1/fuel_entries?q\\\\[geolocation_gps_device_null\\\\]=1&q\\\\[created_at_gteq\\\\]=2016-06-06\\\"\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\nI've added two filters, `q[geolocation_gps_device_null]=1` and `q[created_at_gteq]=2016-06-06` _(Note that I had to escape the brackets for curl to recognize them properly)_. The first filter returns only those entries without GPS data, while the second filter handles the date.\n\n# Updating the Fuel Entry\n\nTo update a Fuel Entry's position, we issue a PATCH request for each Fuel Entry, specifying values for `geolocation[gps_device][latitude]` and `geolocation[gps_device][longitude]`. Here are the [docs on updating Fuel Entries](https://developer.fleetio.com/docs/update-fuel-entry), and here is an example of how to do it:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl \\\\\\n--include \\\\\\n--header \\\"Authorization: Token API_KEY\\\" \\\\\\n--header \\\"Account-Token: ACCOUNT_TOKEN\\\" \\\\\\n--request PATCH \\\\\\n--data \\\"geolocation[gps_device][latitude]=32.8117055&geolocation[gps_device][longitude]=-97.0254227\\\" \\\\\\n\\\"https://secure.fleetio.com/api/v1/fuel_entries/123\\\"\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\nAnd that's it! Fleetio takes care of the rest. You can verify that the GPS data was added successfully by viewing the Fuel Entry in the browser. If a fuel exception is fired, the account owner will receive an email and the warning message will be visible on the Fuel Entry's detail page. Keep in mind that the fuel exception calculator runs in the background and may take a few minutes to process.","updates":[],"order":8,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"572cca8d73c5671700a7adcb","version":{"version":"1","version_clean":"1.0.0","codename":"","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"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","5a71fa2de9aa84007a8bccdb","5b3a768a8a21dd0003ca080d","5c7030f099eeb6003116a106","5c9553a7b6957d005006fc09","5c955c3d04233b0063c9f450","5cfe73f7823bba005de7e1ed","5d07eb760568e70040d6ae21","5deec6550e90370067139979","5ec5a01754009700689296af"],"_id":"54f8de4e4339bb1900c8bffb","project":"54c0e51215af820d001a38a6","releaseDate":"2015-03-05T22:53:02.044Z","createdAt":"2015-03-05T22:53:02.044Z","forked_from":"54f8de14c6cabe23005c02a2","__v":40},"createdAt":"2016-05-06T16:47:09.364Z","user":"54cba76f6d1eee0d00c33dee","__v":11,"githubsync":"","project":"54c0e51215af820d001a38a6","category":{"sync":{"isSync":false,"url":""},"pages":["54f8de4f4339bb1900c8c010","54f8de4f4339bb1900c8c011","54f8de4f4339bb1900c8c012","54f8de4f4339bb1900c8c013"],"title":"Fleetio API","slug":"fleetio-api","order":0,"from_sync":false,"reference":false,"_id":"54f8de4e4339bb1900c8bffc","__v":1,"createdAt":"2015-01-22T11:54:59.216Z","project":"54c0e51215af820d001a38a6","version":"54f8de4e4339bb1900c8bffb"},"parentDoc":null}

GPS Integration Guide


We're expanding our API in an effort to make working with GPS providers easier. We currently support a number of GPS related functions: 1. Odometer Updates 2. Faults / DTC Alerts 3. Vehicle Location 4. Fuel Entry Location In this tutorial you'll find step by step instructions and code snippets to help you get started. You can also refer to the documentation for each endpoint for more details. [block:api-header] { "type": "basic", "title": "Users" } [/block] Before we get started I should say a few words about users, authentication, and authorization. A user in Fleetio works pretty much how you'd expect. Users can login, modify data, and belong to multiple organizations, which we call accounts. A user has a defined set of permissions within an account. Some users can create vehicles and manage their fuel and odometer history; others can't. It's important to make sure that the user whose credentials you use to interact with the API has the correct set of permissions. You can read more about our permissions [here](http://help.fleetio.com/article/46-user-roles-and-permissions). Each request to the API must be accompanied by the user's API key and an account token. Instructions on how to obtain these can be found on our [overview page](http://developer.fleetio.com/). So now that you have a user, an API key, and an account token, it's time to start using the API. Here's an example: [block:code] { "codes": [ { "code": "curl \\\n--include \\\n--header \"Authorization: Token API_KEY\" \\\n--header \"Account-Token: ACCOUNT_TOKEN\" \\\n\"https://secure.fleetio.com/api/v1/users/me\"\n\n{\"id\":1,\"username\":\"[email protected]\",\"first_name\":\"Test\",\"last_name\":\"Example\",\"email\":\"[email protected]\",\"fuel_economy_units\":\"mpg_us\",\"time_zone_name\":\"Central Time (US & Canada)\",\"time_zone_offset_in_seconds\":-21600,\"created_at\":\"2013-09-23T02:09:30.607-05:00\",\"updated_at\":\"2016-03-30T16:43:05.158-05:00\"}", "language": "shell" } ] } [/block] *Note that the authorization token is preceded by `Authorization: Token`. We require this because we accept multiple types of authorization methods.* In this example, I queried the `/users/me` end point which returns useful information about the current user such as email, name, and time zone. All right, that covers users, let's move on to Odometer updates. [block:api-header] { "type": "basic", "title": "1. Odometer Updates" } [/block] Odometer updates are called meter entries in Fleetio. We have a dedicated section for creating them [here](https://developer.fleetio.com/docs/create-meter-entry) if you want to get down to the nitty gritty. We recommend updating a vehicle's odometer on a regular basis, such as once per day. This should be enough for most scenarios, but certain use cases may require more frequent updates. There's one important difference between creating a regular meter entry and a GPS meter entry. When creating GPS meter entries please be sure to provide two extra parameters, `gps` and `gps_provider`. The `gps` param is a boolean and must be set to true and the `gps_provider` is the name of your organization/product/service as you would like it to appear to end users within Fleetio. Here's a snippet showing how to create a GPS meter entry: [block:code] { "codes": [ { "code": "curl \\\n--include \\\n--header \"Authorization: Token API_KEY\" \\\n--header \"Account-Token: ACCOUNT_TOKEN\" \\\n--data \"&value=1000&date=2016-05-06&vehicle_id=123&gps=true&gps_provider=My Company Name\" \\\n\"https://secure.fleetio.com/api/v1/meter_entries\"", "language": "shell" } ] } [/block] [block:api-header] { "type": "basic", "title": "2. Faults / DTC Alerts" } [/block] Creating Faults in Fleetio is pretty straightforward and the process for GPS partners is the same as any other API user. Here's the [docs for creating Faults](https://developer.fleetio.com/docs/create-fault). [block:api-header] { "title": "3. Vehicle Location" } [/block] Historical vehicle locations are stored in Fleetio via Location Entries. You can learn about how Location Entries are used in the Fleetio UI by referencing the [Vehicle Location History Help Center Article](https://help.fleetio.com/hc/en-us/articles/360019526051-Vehicle-Location-History). If you're interested in creating Location Entries via the API, you can look at the [docs for creating Location Entries](https://developer.fleetio.com/docs/create-location-entry). Here's a snippet showing how to create a Location Entry. [block:code] { "codes": [ { "code": "curl \\\n--include \\\n--request POST \\\n--header \"Authorization: Token API_KEY\" \\\n--header \"Account-Token: ACCOUNT_TOKEN\" \\\n--header \"Content-Type: application/json\" \\\n--data '{\"vehicle_id\": 1234, \"date\": \"2019-08-25 12:00:00 -0600\", \"latitude\": 33.477536, \"longitude\": -86.771141}' \\\n\"https://secure.fleetio.com/api/v1/location_entries/\"", "language": "shell" } ] } [/block] [block:api-header] { "type": "basic", "title": "4. Fuel Entry Location" } [/block] Fuel Entries in Fleetio can have location data associated with them, detailing the vehicle's location at the time of the fill up. This serves two main purposes: 1. Provides a map based visual representation of the location on the Fuel Entry's detail page: [block:image] { "images": [ { "image": [ "https://files.readme.io/8596498-fuel-entry-page.jpg", "fuel-entry-page.jpg", 2880, 1536, "#f1f2f1" ], "caption": "The fuel entry page showing information about a specific fuel up." } ] } [/block] 2. Fuel exception alerts. If a vehicle's position at the time of a fill up is greater than 1/4 mile from the reported vendor's location, a fuel exception alert will fire. This alert will send an email to the account owner: [block:image] { "images": [ { "image": [ "https://files.readme.io/1f86e43-fuel-location-exception-email.jpg", "fuel-location-exception-email.jpg", 1682, 1244, "#f1f2dd" ], "caption": "An example of the fuel exception email sent to the account owner." } ] } [/block] And it will be visible on the fuel entry's map as a warning message. [block:image] { "images": [ { "image": [ "https://files.readme.io/2bea448-fuel-location-exception.jpg", "fuel-location-exception.jpg", 1922, 698, "#ededea" ], "caption": "The exception alert on a fuel entry's detail page." } ] } [/block] Now that we know why fuel entry GPS data is useful in Fleetio, let's check out how to get it all working. # Fetching relevant fuel entries The first thing to understand is that a single Fuel Entry can have multiple types of location data associated with it - i.e. it can have the location of the gas station where the fuel-up occurred, and it can have the location reported by the vehicle's telematics hardware at the time the fuel-up occurred. By comparing these two coordinates to see if they match or are in close proximity, we can determine if the vehicle was actually present at the gas station when the fuel-up occurred (or if it was somewhere else, indicating a possible fraudulent fuel-up. The location of the gas station is stored automatically on the Fuel Entry if a `vendor_id` is saved on the Fuel Entry, and if that Vendor's location is saved in Fleetio. So when a Fuel Entry is created, all you have to do is give it a `vendor_id`, and that Vendor's location will be saved as the location where the fuel-up occurred. (If a Fleetio customer has a fuel integration in Fleetio with one of our supported Fuel Card partners, this process happens automatically.) The second part of the process is saving the vehicle's location at the time of the fuel-up as reported by the onboard telematics hardware. To do this, the first thing is to fetch any and all Fuel Entries that need to be updated. Use the /fuel_entries endpoint to get a list of entries back. Here are the [docs for fetching Fuel Entries](https://developer.fleetio.com/docs/fuel-entries), and here is an example of how you'd fetch these Fuel Entries. [block:code] { "codes": [ { "code": "curl \\\n--include \\\n--header \"Authorization: Token API_KEY\" \\\n--header \"Account-Token: ACCOUNT_TOKEN\" \\\n\"https://secure.fleetio.com/api/v1/fuel_entries\"", "language": "shell" } ] } [/block] That gets us a list of Fuel Entries, but it's not exactly what we want as it gets us _too many_ results. Fortunately, we can narrow down the result set by passing [filters](https://developer.fleetio.com/docs/filtering-results) to the API. In this example we only want fuel entries that were created today and do not currently have GPS data. [block:code] { "codes": [ { "code": "curl \\\n--include \\\n--header \"Authorization: Token API_KEY\" \\\n--header \"Account-Token: ACCOUNT_TOKEN\" \\\n\"https://secure.fleetio.com/api/v1/fuel_entries?q\\[geolocation_gps_device_null\\]=1&q\\[created_at_gteq\\]=2016-06-06\"", "language": "shell" } ] } [/block] I've added two filters, `q[geolocation_gps_device_null]=1` and `q[created_at_gteq]=2016-06-06` _(Note that I had to escape the brackets for curl to recognize them properly)_. The first filter returns only those entries without GPS data, while the second filter handles the date. # Updating the Fuel Entry To update a Fuel Entry's position, we issue a PATCH request for each Fuel Entry, specifying values for `geolocation[gps_device][latitude]` and `geolocation[gps_device][longitude]`. Here are the [docs on updating Fuel Entries](https://developer.fleetio.com/docs/update-fuel-entry), and here is an example of how to do it: [block:code] { "codes": [ { "code": "curl \\\n--include \\\n--header \"Authorization: Token API_KEY\" \\\n--header \"Account-Token: ACCOUNT_TOKEN\" \\\n--request PATCH \\\n--data \"geolocation[gps_device][latitude]=32.8117055&geolocation[gps_device][longitude]=-97.0254227\" \\\n\"https://secure.fleetio.com/api/v1/fuel_entries/123\"", "language": "shell" } ] } [/block] And that's it! Fleetio takes care of the rest. You can verify that the GPS data was added successfully by viewing the Fuel Entry in the browser. If a fuel exception is fired, the account owner will receive an email and the warning message will be visible on the Fuel Entry's detail page. Keep in mind that the fuel exception calculator runs in the background and may take a few minutes to process.