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.

{
    "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:

{
    "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.

Variable

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.

Value

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.

Unit

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.

Time

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.

Serie

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.

Metadata

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).

Location

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.