NAV
shell

Introduction

Welcome to the Tank Utility API! You can use this documentation to learn about our API endpoints. You can get information on customers, devices, and tank levels in our database.

We know data is only useful when you leverage it to make life easier, so we’re opening this up for interoperability!

Data security and privacy is very important, so devices are only accessible when you have been granted access by the device owner.

You can view code explanations and examples in the dark area to the right.

This API documentation is really only helpful if you are trying to retrieve data from a Tank Utility Device. Feel free to orders yours today!

Authentication

To receive your token, use this code:

curl --user <my_username>:<my_password> https://data.tankutility.com/api/getToken

The above command returns JSON structured like this:

{"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0MzgyMjQwODE0NjIsInYiOjAsImQiOnsidWleejoic2ltcGxlbG9naW46MzM1In0sImlhdCI6wwDIyMzk5NX0.kbYzxRtbGB2ke3IBgQTVMNQprHOWJZFgQQnPK6Wyas4"}

Tank Utility uses API tokens to provide access to the API. Based on the credentials you’ve configured in our app, you can retrieve a string type token for your API calls using https://data.tankutility.com/api/getToken

The token will be issued using basic authentication and will expire in 24 hours.

Your token is expected to be included in all API requests to the server in a header that looks like the following:

token=my_personal_token

Devices

Get a list of devices

To receive the list of devices you have in your account, use this code:

curl https://data.tankutility.com/api/devices?token=<my_personal_token>

The above command returns JSON structured like this:

{"devices":["54df6a066667531535371367","54ff69057492666782350667"]}

This endpoint retrieves all devices that are assigned to your user account in the app in list.

Note that there is no limit on the number of tanks you can assign to a single account.

So if you’re a fuel supplier or 3rd party, get in touch with Tank Utility to see how we can work for you.

Get data from a specific device

curl https://data.tankutility.com/api/devices/54df6a066667531535371367?token=<my_personal_token>

The above command returns JSON structured like this:

{"device":{"name":"Sample Device","address":"6 Dane St., Somerville, MA 02143, USA","capacity":100,"lastReading":{"tank":20,"temperature":72.12,"time":1444338760345,"time_iso":"2015-10-08T21:12:40.345Z"}}}

This endpoint retrieves data, including tank level from a specific device.

Return Parameters

Parameter Description
address The physical location of the tank
capacity The volumetric capacity of the tank in gallons
lastReading Last reading received by Tank Utility
tank Last reading of tank level as a percentage
temperature temperature at tank monitor in degrees F
time Last reading time in unix epoch
time_iso Last reading time in iso format
name The name of the customer or tank owner

Errors

The Tank Utility API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request has an issue
401 Unauthorized – Your API key is wrong
403 Forbidden – The device requested is not assigned to your account
404 Not Found – The specified device could not be found
405 Method Not Allowed – You tried to access a device with an invalid method
406 Not Acceptable – You requested a format that isn’t json
410 Gone – The tank requested has been removed from our servers
429 Too Many Requests – You’re requesting too much data! Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.