apidocs.tankutility.comAPI Reference

NAV shell Sign Up for credentials in the app 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. You must replace my_username and my_password with your credentials to the Tank Utility App. 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 If you’re not already assigned a tank in the Tank Utility App, note that the tank will return 403 Forbidden. 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. ....