TagoIO Data Structure Details

Today, I will show you a little more about something that many TagoIO users are not aware of: the TagoIO data structure. Knowing the TagoIO data structure is essential for you to develop an application that can utilize as much of the platform as possible, so I will explain in detail each field of the data structure used on the platform.

So, what exactly is the format of the TagoIO data structure? The structure follows the JSON format (Click here to check what is JSON), see below a sample JSON for TagoIO with all fields accepted by the API.

Complete JSON
    "variable": "temperature",
    "value": 71,
    "unit": "F",
    "time": "2019-09-19 05:15:02",
    "serie": "1568913302243",
    "metadata": {
      "color": "green"
    "location": {
      "lat": 35.770723,
      "lng": -78.677328

As you can see, there are several possible fields to be sent, but which of these fields are really necessary for your JSON to be accepted by the TagoIO API? We can check this with the JSON below:

Basic JSON
    "variable": "temperature",
    "value": 71,

The TagoIO API accepts a very large range of JSON complexity from the most rudimentary, to the most complex JSONs. However, not every field accepted by the TagoIO API is useful in the development of your application. Check below for detailed explanations related to each field.


This field is a mandatory field and represents the name you will give to your variable. You can use this field as a parameter when searching your bucket. Always remember that the TagoIO API will not accept special characters in this field (with the exception of the underline) and will not differentiate between uppercase and lowercase letters.


This field is also mandatory in your JSON and represents the value of your data, such as: temperature data that will have a value such 71. You cannot use this field as a parameter when searching your bucket. This field does not accept objects, you must use it to send values such as: strings, numbers and booleans.


Whenever you have data that uses units, like temperature for example, you can make use of the unit field to show that unit in your widgets. For your widgets to use the unit from your JSON, you must configure this in your widget.


The time is a field that you don’t need to worry about most of the time, it is automatically generated by the TagoIO API if it isn’t present in your JSON. Use this field only if you want to send data with a past or future time.


The greatest use of this field is the organization of data, you can use it to organize data in widgets such as tables and charts. Imagine for example that you have a table with 3 variables: temperature, humidity and wind. For these 3 variables to be aligned in the table, you just need to use the serial field for this. Another extremely useful application of this field comes from the fact that this field is indexable and can be used to perform searches.


This field has several uses and serves as a field where you can send whatever you like, for example: color, icon and label for your variable. Something very cool that you can do by using this field is to save Data Inputs in your application; for more details see this post (Sending as much data as you want for the price of 1 data input).


The last field accepted by the TagoIO API is very simple, it is the geographical location of your device that can be used in the Map widget for example. Just send an object with the lat and lng fields representing the latitude and longitude measured by your device.

These were all fields accepted by the TagoIO API, if you have any questions related to one of these fields just ask here in this post and I will be happy to answer you.

1 Like

How can I push a lat/lng into a payload using a parser? I have created an empty payload that I can fill with other data, and the lat/lon goes in correctly if I push it as a single variable, but I can’t figure out how to insert it as a location pair variable.

  var latitude=hexToFloat(flipHexString(latdata, 8));
  var longitude=hexToFloat(flipHexString(londata, 8));

  payload.push({"variable" : "latitude" , "value" : latitude});   
  payload.push({"variable" : "longitude" , "value" : latitude}); 

  payload.push({"variable" : "location", value:  {"lat": latitude, "lng": longitude}});  

    "variable": "location",
    "value": {
        "lat": 30.0786018371582,
        "lng": -100.28189849853516

//FAILS WITH ERROR THAT "variable" is missing
  payload.push({"location" :  {"lat": latitude, "lng": longitude}});

I think you have to do it this way:

  "variable": "address", // variable name (required)
  "value": "anything", // string, number or boolean
  "location": {
    "coordinates": [30, 45] // [lng, lat]
1 Like