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.