How the Surfact platform works

Every time a device updates a sensor reading, that reading is stored in a variable as a data-point — what we call a "dot." Dots that come from your devices are stored inside variables, each with its own timestamp.

The hierarchy is:

Organization → Device → Variable → Dot (value + timestamp + context)

Data structure

Each dot contains the following items:

Values

A numerical value, up to 16 floating-point digits:

{
  "value": 34.87654974
}

Timestamps

A timestamp tracks time as a running total starting from the Unix Epoch — January 1, 1970 at UTC.

When you send data to Surfact, set the timestamp in milliseconds. When you retrieve a dot's timestamp, it is also returned in milliseconds.

{
  "timestamp": 1537453824000
}

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

💡

Pro tip: Use Epoch Converter to convert between Unix timestamps and human-readable dates.

Context

Numerical values aren't the only data type supported. You can also store strings and other values inside the context — a key-value object attached to a dot.

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

GPS coordinates

Context is commonly used to store the latitude and longitude of your device for GPS and tracking applications. All Surfact maps read the lat and lng keys from a dot's context to plot the device's position.

This means you only need to send a single dot — with the coordinates in its context — to plot a point on a map, instead of sending latitude and longitude as two separate variables.

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

⚠️

Note: You can mix string and numerical values in the context. For geolocation, make sure coordinates are in decimal degrees.

On an Emma tracker the coordinates arrive on one specific variable — position, whose numeric value is the accuracy of the fix in metres. See Device Position.