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:

AttributeDescriptionType
userIdentifying information for the user associated with the recordHash
sourceThe original reporting source of the record for the userHash
segmentsFiner grained information about an event, when provided by an integrationArray
metricsThe reported metrics, represented as an array of discrete items of dataArray
categoryDescriptive field provides context for the resource objectString
{
 "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.

10981098

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.

AttributeDefinitionValue
typeThe type of metric being reported, like "steps', "active_duration", or "distance"string
unitThe metric unit of measure the value is being reported in.string
valueThe representation of the measurement which represents the value received from the data source. For instance, "100" steps from Fitbit.string, float, or integer*
originThe 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.

OriginDefinition
sourceThe offset was provided or calculated based on data provided by the record source
profileThe offset was provided by the user profile linked to the record received
user_definedThe 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