Every time a we send sensor data to the cloud, a data-point or "dot" is created. Ubidots stores "dots" that come from your devices inside variables, and these stored dots have corresponding timestamps:

2618

Ubidots Data Hierarchy

Sending sensor readings to a device, such as "Machine A" , is as easy as:

curl -X POST \
     -H "Content-Type: application/json" \
     -H "X-Auth-Token: YOUR_UBIDOTS_TOKEN" \
     -d '{
           "temperature":23.5,
           "humidity": 60,
           "pressure": 1013.2
         }' \
     "https://industrial.api.ubidots.com/api/v1.6/devices/machine-a"

Here, we just sent 3 "dots". A dot is made of up to 3 fields:

ItemDescriptionMandatory
valueA numerical value. Ubidots accepts up to 16 floating-point length numbers.Yes
timestampUnix Epoch time, in milliseconds. If not specified, then our servers will assign one upon reception.No
contextAn arbitrary collection of key-value pairs. Mostly used to store the latitude and longitude coordinates of GPS devices.No

Value

A numerical value. Ubidots accepts up to 16 floating-point length numbers.

{"value" : 34.87654974}

Timestamp

A timestamp, as best described here, is a way to track time as a running total of seconds. This count starts at the Unix Epoch on January 1st, 1970 at UTC. Therefore, the unix time stamp is merely the number of seconds between a particular date and the Unix Epoch. Please keep in mind that when you send data to Ubidots, you must set the timestamp in milliseconds; also, if you retrieve a dot's timestamp, it will be in milliseconds.

"timestamp" : 1537453824000

The above timestamp corresponds to Thursday, September 20, 2018 2:30:24 PM.

PRO-TIP: A useful tool to convert between Unix timestamps and human-readable dates is Epoch Converter.

Context

Numerical values are not the only data type supported; you can also store string or char data types inside what we call context. The context is a key-value object that allows you to store not only numerical but also string values. An example use of the context could be:

"context" : {"status" : "on", "weather" : "sunny"}

A context is commonly used to store the latitude and longitude coordinates of your device for GPS/tracking application use cases. All Ubidots maps uses the lat and lng keys from a dot's context to extract the coordinates of your device, in that way you just need to send a single dot with the coordinates values in the variable context to plot a map instead of sending separately both latitude and longitude in two different variables. Below you can find a typical context with coordinates values:

"context" : {"lat":-6.2, "lng":75.4, "weather" : "sunny"}

Please note that you can mix both string and numerical values in the context. If your application is for geo-localization purposes, make sure that the coordinates are set in decimal degrees.


Following our example, we could be more specific about the data we send, by adding the timestamp and context to a variable:

curl -X POST \
     -H "Content-Type: application/json" \
     -H "X-Auth-Token: YOUR_UBIDOTS_TOKEN" \
     -d '{
           "temperature":{
               "value": 23.5,
               "timestamp":1703001262000, 
               "context" : {
                   "weather" : "sunny"
               }
           }
           "humidity": 60,
           "pressure": 1013.2
         }' \
     "https://industrial.api.ubidots.com/api/v1.6/devices/machine-a"