API Options
What is an API?
An API stands for application programming interface. It is a way for you to get the data you want or need by making your own program to access and use it. There is a great article on UPWork here that simply explains what an API is in detail. Intro to APIs: What Are They
What do we offer for API's?
You are required to have our Premium Account to use any of the server API's.
We have a few ways that you can use to access your PTDevice data using your own software. The main one is our REST API which uses Oauth2.0 for secure server access and it gives the ability to access your device data, account data, and if you are a "Manager" of devices, you can access all your client data as well. We then have a token based access of which you can use to only access your device data through our servers. Once you have the token, you can just do GET requests using a url with the token. A third option is to use the "public url" where in your account you can enable the public sharing of each device. This gives you a way to embed the level data on your own website or to allow others to browse to a url without having to login. It also gives you a simple json GET request for retrieving your device data only. Finally, you can access the data on your device directly. The only catch to that API is that you must understand how to use the raw sensor data to give you the result you are looking for. More detail on each API type is below.
REST API
Documentation for this API is currently here: Documentation
You must be familiar on how to use a REST API and OAuth2.0 using the authorization code flow. Once you have an understanding of this API, you can request the client ID and secret key by creating a ticket here: Create Ticket.
Token API
This API type is simpler than the above, however you only get access to your device information. Contact us through a ticket to request a token: Create Ticket.
Once you have your token, you must find out what your device ID is. In order to do that, log into your ptdevices account, click on the "Features" button of the device of choice and observe the url. At the end of the url will be a number and that number is your device id to use in this api.
Then just do a GET request on the following url. It could be https or http.
http://api.ptdevices.com/token/v1/device/{deviceId}?api_token={given_token}
The following would be the returned JSON data:
{
"data": {
"id": 2773,
"device_id": "CC50E36CF496",
"created": "2020-02-10 23:16:32",
"user_id": 1,
"device_type": "level",
"title": "Large Antenna (Pond)",
"version": "210",
"lat": null,
"lng": null,
"address": null,
"status": "Working",
"delivery_notes": null,
"units": "Metric",
"reported": "2020-11-11 15:47:37",
"tx_reported": "2020-11-11 03:14:47",
"wifi_signal": "100%",
"tx_signal": "-101.00dBm",
"device_data": {
"battery_voltage": 5.05,
"battery_status": "Good",
"percent_level": 86,
"volume_level": 0
},
"device_setup": {
"shape": "rectangle",
"depth": 3,
"width": null,
"length": null,
"diameter": null,
"power_x": 20,
"power_y": 6,
"power_z": 40
}
}
}
You can also request a png image of your level using the following url:
http://api.ptdevices.com/token/v1/device/{deviceId}/image?api_token={given_token}&width=300&height=300
Public Share API
This API access is simply a GET request for JSON data but it doesn't require a token or anything like that. The requirement is that in your account, you have enabled the "Public Sharing" option per device.
Once that is enabled, you must find out what your device ID is. In order to do that, log into your ptdevices account, click on the "Features" button of the device of choice and observe the url. At the end of the url will be a number and that number is your device id to use in this api.
Now you can do a GET request on the following url:
https://www.mypt.in/device/{deviceId}
Which then returns the following JSON data:
{
"id": 2773,
"updated_at": "Nov 11th 2020, 10:56 AM",
"mac_address": "CC50E36CF496",
"device_type": "level",
"depth": 3,
"width": null,
"length": null,
"diameter": null,
"units": "metric",
"percentLevel": 86,
"volumeLevel": 0,
"title": "Large Antenna (Pond)",
"description": null,
"lat": null,
"lng": null,
"address": null,
"batteryStatus": "<span class=\"text-success\">Good</span>",
"status": "<span class=\"text-success\"><i class=\"icon-check\"></i> Working</span>",
"tx_reported_at": "Nov 10th, 10:14 PM",
"power_x": 20,
"power_y": 6,
"power_z": 40,
"delivery_notes": null,
"reported": "Nov 11th, 10:56 AM",
"wifi_rssi": "-42.00",
"tx_rssi": "-101.00",
"temperature": 7.12,
"sensor_data": "[{\"1\": 314, \"z\": 60, \"low_history\": [0], \"low_implied\": true}, {\"2\": 5.83}, {\"3\": 7.12}, {\"2\": 5.05, \"v\": 3.39}]"
}
Direct to Device API
This API access gives you the raw data directly from your device on your own network, bypassing our server system. The main thing about this API is that you only get the raw sensor data and you must interpret it for yourself into useful information, ie. handling the calibration, etc.. However, this is good for those who don't want to rely on our server system. Also, there are no authentication methods to handle here.
PTLevel Long Range Wireless
GET /config?json=true
{
"free_space": "667648",
"rx_id": "210",
"tx_id": "110",
"tx_rssi": "-101",
"rx_rssi": "-42",
"firmware_version": "210",
"hardware_version": "4",
"id": "CC50E36CF496",
"ip": "192.168.0.202",
"subnet": "255.255.255.0",
"gateway": "192.168.0.1",
"dns": "unknown",
"tx_firmware_version": "7",
"tx_hardware_version": "5",
"fails": "0",
"rx_sensors": "[]",
"tx_sensors": "[{\"1\":314,\"z\":60},{\"2\":5.83},{\"3\":7.12}]"
}
The {2:5.83} is the voltage level of the batteries which in this case is 5.83v.
PTLevel WiFi
GET /get_sensors
{
"local_s": "[{\"1\":68,\"z\":68}]"
}
Both devices will return the same sensor values, just in different ways. To explain the level sensor data, basically the 1:{value} is the sensor a/d value and the z:{value} is the zero point value. The zero point is the a/d value of the sensor when there is no pressure applied. You'd use that value as the low part of the linear range. You must then figure out the high point of the range which is calculated based on your tank size or by doing a pressure test when your tank is full (basic calibration). Then you have your range and you can calculate the current level based on that range whether it be in percent, inches, volume, etc..
Related Articles
Wireless Device Installation Instructions
This article is for downloading the Long Range Wireless PTLevel Instruction Manual. To learn the step-by-step process of installing the device in a cistern, with pictures, visit our PTLevel Cistern Setup Page: ...Sharing your Device with your Water Delivery Company
To share your PTLevel with your Water Delivery Company, simply log into your device and follow these directions: 1. Click "Features" (to access more options on your level) and then click "Share" 2. Under the Share tab, click the blue "Share" button ...Wired Device Not Connected
In this article, we will go over how to troubleshoot the PTLevel Wired device when it shows “Not Connected” in your account. TROUBLESHOOTING CONNECTIONSTo top Below are steps we suggest that you can go through to troubleshoot your device. Check your ...What are my Shipping Options?
Ordering Information: It is our goal to ship out all orders the same day they are received, as long as they are received by 1pm EST. Shipping: Canada Post, UPS, and FedEx are our primary shippers. We always try to choose the most economical shipping ...Device Management Account System - Overview
Our Device Manager Account System is designed for those who sell, install, and manage/maintain devices and customer accounts. Basically it is an account that gives you the ability to fully manage many customers and their devices in your own account. ...