Data Retrieval
- Selma Pittman
Analytics
Data, glorious data.
Now that you've created your users and deployed the marketplace, we'll discuss how to retrieve data from Validic.
About our API
Before we get into the suggested use of our API, let's have a wonderfully short summary of design and data objects.
Data Objects
We separate data into several objects that each contain related data. For example, the Fitness object returns data for activities that are undertaken with the express purpose of exercising. These activities have a defined duration (time, distance, elevation, etc).
Below is a full list of Validic API objects:
Object Name | Description |
|---|---|
Fitness | Activities that are undertaken with the express purpose of exercising. These activities have a defined duration (time, distance, elevation, etc). These records are typically discrete/distinct events. |
Routine | Activities that occur regularly throughout the day, without the specific goal of exercise, for example, total calories burned and consumed, steps taken, stairs climbed. These activities are aggregated throughout the day. These records are typically an aggregate of discrete/distinct events. |
Nutrition | Measurements related to calorie intake and consumption and nutritional information (such as fat, protein, carbohydrates, sodium, etc.). These records are typically discrete/distinct events. |
Sleep | Measurements related to the length of time spent in various sleep cycles, as well as the number of times woken during the night. These records are typically discrete/distinct events. |
Weight | Measurements associated with a user’s weight and body mass. These records are typically discrete/distinct events. |
Diabetes | Measurements associated with a user’s blood glucose and hormone levels related to diabetes treatment and management. These records are typically discrete/distinct events. |
Biometrics | Measurements associated with a user’s biometric health such as blood pressure, cholesterol, heart rate, and blood and hormone levels. These records are typically discrete/distinct events. |
Data Levels
Data is returned at one of two levels:
User: Requests are specific to a user.
Organization: Requests generally return data for all your users
Requesting Data
The Anatomy of a Request
To retrieve data, you'll make a request similar to this:
Sample Request
GET https://api.validic.com/v1/organizations/540e1c9b965feSAMPLEfb/users/54eb9d3a9fa63eSAMPLE78/nutrition.json?access_token=8f6c2c262ddf8SAMPLE6a92625e04676013eSAMPLE960bc25d5bc&start_date=2015-02-14T00:00:00+00:00&expanded=1
Here is the breakdown of the basics of this request:
Parameter | Example | Description/Source |
|---|---|---|
organizations | 540e1c9b965feSAMPLEfb | This is the Organization ID provided by the integration team. |
users | 54eb9d3a9fa63eSAMPLE78 | This is the User ID that appeared in the " uid" field when you provisioned the user. |
access_token | 8f6c2c262ddf8SAMPLE6a9262013eSAMPLE960bc25d5bc5 | This is your Access Token provided by the integration team. |
object | nutrition.json | This defines the data object you'd like returned. |
The other values are optional parameters that we'll discuss in the next section.
Composition of a Response
The following guide will help you understand how to work with the data we return.
Summary
Each response contains a summary object which displays important information about your request. While these fields are self-explanatory, it's important to note one significant function and that is Pagination.
Summary Object
{
"summary": {
"status": 200,
"message": "Ok",
"results": 288,
"start_date": "2015-02-14T00:00:00+00:00",
"end_date": "2015-12-03T23:59:59+00:00",
"offset": 0,
"limit": 100,
"previous": null,
"next": "https://api.validic.com/v1/organizations/540e1c9b965fe22SAMPLEfb/users/54eb9d3a9fa6SAMPLE78/routine?access_token=8f6c2c262ddf8SAMPLEce6a92625e04676013e08a04SAMPLEbc25d5bc5&expanded=1&page=2&start_date=2015-02-14T00%3A00%3A00+00%3A00",
"params": {
"start_date": "2015-02-14T00:00:00+00:00",
"end_date": null,
"expanded": true,
"offset": 0,
"limit": 0
}
Pagination
When making API calls, within a given scope (“start_date” and “end_date” of an API call) you may receive a large number of records. To make this easier to manage, 100 records per page are included in the response by default. You can receive up to 1000 records per page by adding a “limit” parameter to your request. If you experience timeouts, we suggest limiting your requests to 300-500 records.
Each response will contain a Next URI, which directs you to the next page of records.
Next URI
"next": "https://api.validic.com/v1/organizations/540e1c9b965fe22SAMPLEfb/users/54eb9d3a9fa6SAMPLE78/routine?access_token=8f6c2c262ddf8SAMPLEce6a92625e04676013e08a04SAMPLEbc25d5bc5&expanded=1&page=2&start_date=2015-02-14T00%3A00%3A00+00%3A00",
Once the final results page is reached, the Next URI will direct you to the first page again.
Paging Parameters
Parameter | Default | Description |
|---|---|---|
offset=n | 0 | Sets the number of records to skip when returning the results |
limit=n | 100 | Limits the number of results per request. The maximum value is 1000. Any value higher will be reduced to 1000. |
page=n | 1 | Sets the page number to return |
Standard vs. Expanded
In addition to our standard data payload, you can expand your request to include all available fields. We refer to this as expanded data.
Our conventional request only returns standardized data and the values should not change without prior notice. Expanded data returns non-standardized data and we cannot guarantee this data will not change. Here is an example of Standard vs. Expanded responses.
Standard
Expanded
You can receive expanded data by using the expanded filter such as:
HTTP
Source
The source filter allows for retrieving datasets specific to a particular source (e.g., Fitbit, BodyMedia, etc.). Please review our support site for a list of supported sources.
HTTP
You can also request data from multiple sources by using comma-separated source values. For example:
HTTP
Text
Optional Query Parameters
The following optional parameters can be used to request data.
Standard Data Objects
Parameter | Default | Description |
|---|---|---|
start_date=YYYY-MM-DDTHH:MM:SS | (time.Now - 1.Day) | Scopes the results starting the date provided |
end_date=YYYY-MM-DDTHH:MM:SS | time.Now | Scopes the results ending the date provided |
expanded=1 | 0 | Response json includes the expanded data for the object based on the source. Also includes activity_id & extras |
show_validated=1 | 0 | (DEPRICATED ON 12/8/2015) All responses now include the validated property by default |
source=:source name | 0 | Response json contains only records for named source |
Request Date Formats
The date formats used in query parameters must be one of the following formats.
Format | Description |
|---|---|
YYYY-MM-DDThh:mm:ss.ms-hh:mm | Date Time with milliseconds & offset |
YYYY-MM-DDThh:mm:ssZ | Zulu - Date Time & offset |