Understanding The Data Model

In this section, we'll explain how our data model is constructed and help you understand how to work with our data model.

Model

All supported resources follow a structural convention in order to facilitate reading data easily. Both the Stream and RESTful APIs adhere to this convention. All records provide a top level set of information to facilitate tracking records. In addition to tracking information such as id and checksum each record contains the following top level attributes:

Attribute

Description

Type

user

Identifying information for the user associated with the record

Hash

source

The original reporting source of the record for the user

Hash

segments

Finer grained information about an event, when provided by an integration

Array

metrics

The reported metrics, represented as an array of discrete items of data

Array

category

Descriptive field provides context for the resource object

String

{
 "data" : [
  {
   "version" : "1.0",
   "checksum" : "dce6201fa3e2c8bb7c7033811a5ad2ad",
   "id" : "ec60ac18c6c6a7a607034a9ba31c2514",
   "log_id" : "2017-03-24",
   "created_at" : "2017-03-24T13:38:21.581Z",
   "offset_origin" : "profile",
   "utc_offset" : -14400,
   "type" : "summary",
   "end_time" : "2017-03-25T03:59:59Z",
   "start_time" : "2017-03-24T04:00:00Z",
   "category" : "daily",
   "source" : {
    "type" : "fitbit"
   },
   "user" : {
    "organization_id" : "58209c808a5da50001de6e2d",
    "user_id" : "583c579b8a5da50001a45071",
    "uid" : "9c808a5da50001da5da50001"
   },
   "metrics" : [],
   "segments" : []
  }
 ]
}

Graphical Example

The following graphic displays a standard Summaries Resource and outlines how each attribute is used. Please click on the image to enlarge.

Metrics

Within a record, data specific to an end user event is returned in a list of Metrics. These metrics are broken into four attributes, detailed below. If a metric is not reported by a data source (Fitbit, Jawbone, Garmin, etc), the metric will not appear in the record. Although Validic will not send NULL for metrics, NULL values are possible for top level attributes.

Attribute

Definition

Value

type

The type of metric being reported, like "steps', "active_duration", or "distance"

string

unit

The metric unit of measure the value is being reported in.

string

value

The representation of the measurement which represents the value received from the data source. For instance, "100" steps from Fitbit.

string, float, or integer*

origin

The method by which the measurement was recorded. This value is used to determine where the data was generated. For instance, "manual" meaning the end user added the event using the application and not their device.

string

*The representation of the value is linked to the metric type

},
            "metrics": [
                {
                    "type": "active_duration",
                    "unit": "s",
                    "value": 125,
                    "origin": "unknown"
                },
                {
                    "type": "basal_energy_burned",
                    "unit": "kcal",
                    "value": 2371.96079206,
                    "origin": "unknown"
                },
                {
                    "type": "distance",
                    "unit": "m",
                    "value": 1244.01981306,
                    "origin": "unknown"
                },
                {
                    "type": "active_energy_burned",
                    "unit": "kcal",
                    "value": 219.896335174,
                    "origin": "unknown"
                },
                {
                    "type": "steps",
                    "unit": "count",
                    "value": 1546,
                    "origin": "unknown"
                },
                {
                    "type": "energy_burned",
                    "unit": "kcal",
                    "value": 2591.857127234,
                    "origin": "unknown"
                }
            ],

Time

Time representations in the Validic API are presented as complete UTC timestamps with adherence to the ISO8601 standard. In addition to determining the user local time of the event, a utc_offset is provided as a whole integer representing the seconds offset from UTC. In the event that a UTC offset is neither provided nor inferable, the offset_origin will provide additional context on how the UTC offset was calculated.

Origin

Definition

source

The offset was provided or calculated based on data provided by the record source

profile

The offset was provided by the user profile linked to the record received

user_defined

The offset was provided by the user upon authorization through the marketplace

{
 "created_at" : "2017-03-24T13:38:21.581Z",
 "end_time" : "2017-03-25T03:59:59Z",
 "start_time" : "2017-03-24T04:00:00Z",
 "utc_offset" : -14400,
 "offset_origin" : "profile",
}

What’s Next
Did this page help you?