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",
}