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.

Users

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.

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.

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:

curl \
--include \
--header "Authorization: Token API_KEY" \
--header "Account-Token: ACCOUNT_TOKEN" \
"https://secure.fleetio.com/api/v1/users/me"

{"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"}

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.

1. Odometer Updates

Odometer updates are called meter entries in Fleetio. We have a dedicated section for creating them here 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:

curl \
--include \
--header "Authorization: Token API_KEY" \
--header "Account-Token: ACCOUNT_TOKEN" \
--data "&value=1000&date=2016-05-06&vehicle_id=123&gps=true&gps_provider=My Company Name" \
"https://secure.fleetio.com/api/v1/meter_entries"

2. Faults / DTC Alerts

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.

3. Vehicle Location

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. If you're interested in creating Location Entries via the API, you can look at the docs for creating Location Entries.

Here's a snippet showing how to create a Location Entry.

curl \
--include \
--request POST \
--header "Authorization: Token API_KEY" \
--header "Account-Token: ACCOUNT_TOKEN" \
--header "Content-Type: application/json" \
--data '{"vehicle_id": 1234, "date": "2019-08-25 12:00:00 -0600", "latitude": 33.477536, "longitude": -86.771141}' \
"https://secure.fleetio.com/api/v1/location_entries/"

4. Fuel Entry Location

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:

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 it will be visible on the fuel entry's map as a warning message.

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, and here is an example of how you'd fetch these Fuel Entries.

curl \
--include \
--header "Authorization: Token API_KEY" \
--header "Account-Token: ACCOUNT_TOKEN" \
"https://secure.fleetio.com/api/v1/fuel_entries"

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.

curl \
--include \
--header "Authorization: Token API_KEY" \
--header "Account-Token: ACCOUNT_TOKEN" \
"https://secure.fleetio.com/api/v1/fuel_entries?q\[geolocation_gps_device_null\]=1&q\[created_at_gteq\]=2016-06-06"

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, and here is an example of how to do it:

curl \
--include \
--header "Authorization: Token API_KEY" \
--header "Account-Token: ACCOUNT_TOKEN" \
--request PATCH \
--data "geolocation[gps_device][latitude]=32.8117055&geolocation[gps_device][longitude]=-97.0254227" \
"https://secure.fleetio.com/api/v1/fuel_entries/123"

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.