{"_id":"572cca8d73c5671700a7adcb","version":{"_id":"54f8de4e4339bb1900c8bffb","project":"54c0e51215af820d001a38a6","forked_from":"54f8de14c6cabe23005c02a2","__v":32,"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","5a71fa2de9aa84007a8bccdb"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1"},"user":"54cba76f6d1eee0d00c33dee","__v":11,"project":"54c0e51215af820d001a38a6","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"},"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-05-06T16:47:09.364Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"We're expanding our API in an an effort to make working with GPS providers easier. We currently support three main GPS related functions:\n\n1. Odometer updates\n2. DTC Alerts\n3. Fuel Entry Location\n\nIn this tutorial you'll find step by step instructions and code snippets for achieving each of these.\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 https://secure.fleetio.com/api/v1/users/me -i -H 'Authorization: Token API_KEY' -H \\\"Account-Token: ACCOUNT_TOKEN\\\"\\n\\n{\\\"id\\\":1,\\\"username\\\":\\\"test:::at:::example.com\\\",\\\"first_name\\\":\\\"Test\\\",\\\"last_name\\\":\\\"Example\\\",\\\"email\\\":\\\"test@example.com\\\",\\\"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 them [here](http://developer.fleetio.com/v1/docs/meter_entries) if you want to get down to the nitty gritty.\n\nIdeally, we would like to receive as many odometer updates as possible. Keeping a vehicle's odometer up to date is crucial to many features in Fleetio, so don't be shy about sending us an update each day or even each time a trip ends.\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 https://secure.fleetio.com/api/v1/meter_entries -i -H 'Authorization: Token API_KEY' -H \\\"Account-Token: ACCOUNT_TOEN\\\" --data \\\"&value=1000&date=2016-05-06&vehicle_id=123&gps=true&gps_provider=My Company Name\\\"\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"2. DTC Alerts\"\n}\n[/block]\nCreating DTC alerts in Fleetio is pretty straight forward and the process for GPS partners is the same as any other API user. The documentation for DTC alerts can be found [here](http://developer.fleetio.com/docs/dtc_alerts-1).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"3. Fuel Entry Location\"\n}\n[/block]\nFuel entries in Fleetio can have GPS 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/hYd8ZeUoRmqWKwD9Gp2f_Screen%20Shot%202016-05-06%20at%201.51.59%20PM.png\",\n        \"Screen Shot 2016-05-06 at 1.51.59 PM.png\",\n        \"1986\",\n        \"1170\",\n        \"#113749\",\n        \"\"\n      ]\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 and 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/TwNYicEOTNe2GcEeATwx_Screen%20Shot%202016-05-06%20at%202.04.29%20PM.png\",\n        \"Screen Shot 2016-05-06 at 2.04.29 PM.png\",\n        \"1092\",\n        \"1036\",\n        \"#4680aa\",\n        \"\"\n      ],\n      \"caption\": \"An example of the fuel exception email sent to the account owner.\"\n    }\n  ]\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/ivYmUhtESiiLjhHh4FKL_Screen%20Shot%202016-05-06%20at%202.04.40%20PM.png\",\n        \"Screen Shot 2016-05-06 at 2.04.40 PM.png\",\n        \"1798\",\n        \"742\",\n        \"#3f6476\",\n        \"\"\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\nYou'll first want to fetch any and all fuel entries that need to be updated. Use the /fuel_entries endpoint to get a list of entries back:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl https://secure.fleetio.com/api/v1/fuel_entries -i -H 'Authorization: Token API_KEY' -H \\\"Account-Token: ACCOUNT_TOKEN\\\"\",\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 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 \\\"https://secure.fleetio.com/api/v1/fuel_entries?q\\\\[geolocation_gps_device_null\\\\]=1&q\\\\[created_at_gteq\\\\]=2016-06-06\\\" -i -H 'Authorization: Token API_KEY' -H \\\"Account-Token: ACCOUNT_TOKEN\\\"\",\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]`:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl https://secure.fleetio.com/api/v1/fuel_entries/123 -i -H 'Authorization: Token API_KEY' -H \\\"Account-Token: ACCOUNT_TOKEN\\\" -X PATCH --data \\\"geolocation[gps_device][latitude]=32.8117055&geolocation[gps_device][longitude]=-97.0254227\\\"\",\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.","excerpt":"","slug":"gps-integration-guide","type":"basic","title":"GPS Integration Guide"}

GPS Integration Guide


We're expanding our API in an an effort to make working with GPS providers easier. We currently support three main GPS related functions: 1. Odometer updates 2. DTC Alerts 3. Fuel Entry Location In this tutorial you'll find step by step instructions and code snippets for achieving each of these. [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 https://secure.fleetio.com/api/v1/users/me -i -H 'Authorization: Token API_KEY' -H \"Account-Token: ACCOUNT_TOKEN\"\n\n{\"id\":1,\"username\":\"test@example.com\",\"first_name\":\"Test\",\"last_name\":\"Example\",\"email\":\"test@example.com\",\"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 them [here](http://developer.fleetio.com/v1/docs/meter_entries) if you want to get down to the nitty gritty. Ideally, we would like to receive as many odometer updates as possible. Keeping a vehicle's odometer up to date is crucial to many features in Fleetio, so don't be shy about sending us an update each day or even each time a trip ends. 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 https://secure.fleetio.com/api/v1/meter_entries -i -H 'Authorization: Token API_KEY' -H \"Account-Token: ACCOUNT_TOEN\" --data \"&value=1000&date=2016-05-06&vehicle_id=123&gps=true&gps_provider=My Company Name\"", "language": "shell" } ] } [/block] [block:api-header] { "type": "basic", "title": "2. DTC Alerts" } [/block] Creating DTC alerts in Fleetio is pretty straight forward and the process for GPS partners is the same as any other API user. The documentation for DTC alerts can be found [here](http://developer.fleetio.com/docs/dtc_alerts-1). [block:api-header] { "type": "basic", "title": "3. Fuel Entry Location" } [/block] Fuel entries in Fleetio can have GPS 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/hYd8ZeUoRmqWKwD9Gp2f_Screen%20Shot%202016-05-06%20at%201.51.59%20PM.png", "Screen Shot 2016-05-06 at 1.51.59 PM.png", "1986", "1170", "#113749", "" ] } ] } [/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 and will be visible on the fuel entry's map as a warning message. [block:image] { "images": [ { "image": [ "https://files.readme.io/TwNYicEOTNe2GcEeATwx_Screen%20Shot%202016-05-06%20at%202.04.29%20PM.png", "Screen Shot 2016-05-06 at 2.04.29 PM.png", "1092", "1036", "#4680aa", "" ], "caption": "An example of the fuel exception email sent to the account owner." } ] } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/ivYmUhtESiiLjhHh4FKL_Screen%20Shot%202016-05-06%20at%202.04.40%20PM.png", "Screen Shot 2016-05-06 at 2.04.40 PM.png", "1798", "742", "#3f6476", "" ], "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 You'll first want to fetch any and all fuel entries that need to be updated. Use the /fuel_entries endpoint to get a list of entries back: [block:code] { "codes": [ { "code": "curl https://secure.fleetio.com/api/v1/fuel_entries -i -H 'Authorization: Token API_KEY' -H \"Account-Token: ACCOUNT_TOKEN\"", "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 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 \"https://secure.fleetio.com/api/v1/fuel_entries?q\\[geolocation_gps_device_null\\]=1&q\\[created_at_gteq\\]=2016-06-06\" -i -H 'Authorization: Token API_KEY' -H \"Account-Token: ACCOUNT_TOKEN\"", "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]`: [block:code] { "codes": [ { "code": "curl https://secure.fleetio.com/api/v1/fuel_entries/123 -i -H 'Authorization: Token API_KEY' -H \"Account-Token: ACCOUNT_TOKEN\" -X PATCH --data \"geolocation[gps_device][latitude]=32.8117055&geolocation[gps_device][longitude]=-97.0254227\"", "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.