Device Data (V1)
In MyDataHelps, participants may contribute data collected by wearables and other devices.
Note
There are currently two versions of the Device Data API/SDK: V1 and V2. Be sure to pick the version appropriate to your use case. Access to V2 is not enabled by default.
Contact support if you wish to enable V2 for your project. For more information, see
Device Data API Versions for details.
Concepts
Because device data is a powerful tool available to MyDataHelps studies, we strongly recommend reading about device data concepts.
Namespaces
Device data is grouped into namespaces, which represent the source applications that generate the data. Available namespaces depend on whether you are using Device Data API V1 or V2, as well as your project’s sensor data settings. We will continue to add namespaces to Device Data API V2.
| Namespace |
API V1 |
API V2 |
Description |
Project |
|
- |
Data persisted by project sources and SDKs. |
Fitbit |
|
|
Data persisted by a linked Fitbit account. API V2 includes intraday data, but requires explicit approval from Fitbit. Contact support to inquire about enabling intraday access. |
AppleHealth |
|
|
Data imported from Apple Health. |
HealthConnect |
- |
|
Data imported from Google Health Connect. |
GoogleFit |
|
- |
Data imported from Google Fit. |
Garmin |
|
|
Data imported from Garmin devices. |
AirNowApi |
|
- |
Air quality index data imported from AirNow.gov. |
WeatherBit |
|
- |
Weather forecast data imported from WeatherBit.io. |
Omron |
|
- |
Data imported from Omron wellness products. |
Query Device Data Points
MyDataHelps.queryDeviceData(queryParameters)
Queries for device data for the current participant. You can query across several different kinds of dates. See Dates in Device Data for details.
Parameters
namespace
enum
(required)
Source framework for the device data. See namespaces for details.
type
string
Comma-separated list of types of device data. See Data Types for details.
observedAfter
date
Filters device data points to those observed after this date.
observedBefore
date
Filters device data points to those observed before this date.
modifiedBefore
date
Search device data points updated in the system before this date, in ISO8601 format.
modifiedAfter
date
Search device data points updated in the system after this date, in ISO8601 format.
limit
int
How many entries to include in each page of results. Default and maximum is 100.
pageID
guid
Each page of results will return a nextPageID if there are additional pages that can be queried. Supply that as pageID to query the next page. When excluded, retrieves the first page.
Returns
Promise<DeviceDataPointsPage>
Resolves to a result object containing a page of device data points.
result.deviceDataPoints
collection
A list of DeviceDataPoints filtered by the query parameters.
result.deviceDataPoints[n].id
guid
Auto-generated, globally-unique identifier for this device data point.
result.deviceDataPoints[n].namespace
enum
Source framework for the device data. See namespaces for details.
result.deviceDataPoints[n].deviceDataContextID
guid
Identifier for a group of device data points that share some context. For example, a blood pressure reading might contain separate data points for systolic and diastolic readings, but they will share the same deviceDataContextID. Will be null if the device data point isn’t grouped.
result.deviceDataPoints[n].insertedDate
date
Date (in UTC) when the data point was first added.
result.deviceDataPoints[n].modifiedDate
date
Date (in UTC) when the data point was last modified.
result.deviceDataPoints[n].identifier
string
External identifier for the device data point. Set by the source application, and may be empty.
result.deviceDataPoints[n].type
string
General category of data, like steps or heartRate. Specific values vary by namespace. See Data Types for details.
result.deviceDataPoints[n].value
string
The observed value for what this device data point represents, e.g. number of steps from a step tracker.
result.deviceDataPoints[n].units
string
The units, if any, that the device data was recorded in.
result.deviceDataPoints[n].properties
object
An object whose key-value pairs represent device-specific metadata associated with this device data point. The metadata will vary depending on the source application.
result.deviceDataPoints[n].source
object
An object containing identifying information about the device which recorded the data point. This metadata will vary depending on the source application.
result.deviceDataPoints[n].startDate
date
The date at which this device data point began being recorded (for data that is recorded over time).
result.deviceDataPoints[n].observationDate
date
The date at which this device data point was completely recorded.
result.nextPageID
guid
An ID to be used with subsequent queries. Results from queries using this ID as the pageID parameter will show the next page of results. This field is null if there isn’t a next page.
Availability
var queryParameters = {
namespace: "Project",
type: "RestingHeartRate",
observedAfter: "2021-02-18",
observedBefore: "2021-03-01T12:00:00-4:00",
limit: 100,
pageID: "a706abd5-cc85-482b-909c-ddd92c8abbde"
};
MyDataHelps.queryDeviceData(queryParameters)
.then( function(result) {
console.log(result);
} );
var queryParameters = {
namespace: "Project",
type: "RestingHeartRate",
observedAfter: "2021-02-18",
observedBefore: "2021-03-01T12:00:00-4:00",
limit: 100,
pageID: "a706abd5-cc85-482b-909c-ddd92c8abbde"
};
MyDataHelps.queryDeviceData(queryParameters)
.then( function(result) {
console.log(result);
} );
{
"deviceDataPoints": [
{
"id": "d3a770d3-306b-eb11-aa7f-f8e4e3480e0d",
"namespace": "Project",
"deviceDataContextID": "8c8ca79c-cb62-4e01-acaf-3201ca88e7bb",
"insertedDate": "2021-02-19T23:45:07.497Z",
"modifiedDate": "2021-02-19T23:45:07.497Z",
"identifier": "41a0f952-a9eb-4e05-8ff1-20229460e333",
"type": "RestingHeartRate",
"value": "73",
"units": "BPM",
"properties": {
"PostalCode": "48104",
"Sequence": "32"
},
"source": {
"identifier": "BPCuff1",
"properties": {
"Model": "BP130X",
"Serial": "17117bb6-177d-4f89-a25b-f9274eb8d4ff"
}
},
"startDate": "2021-02-19T23:44:06.0Z",
"observationDate": "2021-02-19T23:45:05.999Z"
}
],
"nextPageID": "660874e9-ae7d-40e3-a7d2-b4ef0e5e465b"
}
{
"deviceDataPoints": [
{
"id": "d3a770d3-306b-eb11-aa7f-f8e4e3480e0d",
"namespace": "Project",
"deviceDataContextID": "8c8ca79c-cb62-4e01-acaf-3201ca88e7bb",
"insertedDate": "2021-02-19T23:45:07.497Z",
"modifiedDate": "2021-02-19T23:45:07.497Z",
"identifier": "41a0f952-a9eb-4e05-8ff1-20229460e333",
"type": "RestingHeartRate",
"value": "73",
"units": "BPM",
"properties": {
"PostalCode": "48104",
"Sequence": "32"
},
"source": {
"identifier": "BPCuff1",
"properties": {
"Model": "BP130X",
"Serial": "17117bb6-177d-4f89-a25b-f9274eb8d4ff"
}
},
"startDate": "2021-02-19T23:44:06.0Z",
"observationDate": "2021-02-19T23:45:05.999Z"
}
],
"nextPageID": "660874e9-ae7d-40e3-a7d2-b4ef0e5e465b"
}
Get Device Data Point
MyDataHelps.getDeviceDataPoint(dataPointId)
Gets details for a specific data point, by identifier.
Parameters
dataPointId
guid
The ID for the data point to retrieve.
Returns
Promise<DeviceDataPoints>
Resolves to a result object containing the device data point.
result.id
guid
Auto-generated, globally-unique identifier for this device data point.
result.namespace
enum
Source framework for the device data. See namespaces for details.
result.deviceDataContextID
guid
Identifier for a group of device data points that share some context. For example, a blood pressure reading might contain separate data points for systolic and diastolic readings, but they will share the same deviceDataContextID. Will be null if the device data point isn’t grouped.
result.insertedDate
date
Date (in UTC) when the data point was first added.
result.modifiedDate
date
Date (in UTC) when the data point was last modified.
result.identifier
string
External identifier for the device data point. Set by the source application, and may be empty.
result.type
string
General category of data, like steps or heartRate. Specific values vary by namespace. See Data Types for details.
result.value
string
The observed value for what this device data point represents, e.g. number of steps from a step tracker.
result.units
string
The units, if any, that the device data was recorded in.
result.properties
object
An object whose key-value pairs represent device-specific metadata associated with this device data point. The metadata will vary depending on the source application.
result.source
object
An object containing identifying information about the device which recorded the data point. This metadata will vary depending on the source application.
result.startDate
date
The date at which this device data point began being recorded (for data that is recorded over time).
result.observationDate
date
The date at which this device data point was completely recorded.
Availability
MyDataHelps.getDeviceDataPoint("d3a770d3-306b-eb11-aa7f-f8e4e3480e0d")
.then( function(result) {
console.log(result);
} );
MyDataHelps.getDeviceDataPoint("d3a770d3-306b-eb11-aa7f-f8e4e3480e0d")
.then( function(result) {
console.log(result);
} );
{
"id": "d3a770d3-306b-eb11-aa7f-f8e4e3480e0d",
"namespace": "Project",
"deviceDataContextID": "8c8ca79c-cb62-4e01-acaf-3201ca88e7bb",
"insertedDate": "2021-02-19T23:45:07.497Z",
"modifiedDate": "2021-02-19T23:45:07.497Z",
"identifier": "41a0f952-a9eb-4e05-8ff1-20229460e333",
"type": "RestingHeartRate",
"value": "73",
"units": "BPM",
"properties": {
"PostalCode": "48104",
"Sequence": "32"
},
"source": {
"identifier": "BPCuff1",
"properties": {
"Model": "BP130X",
"Serial": "17117bb6-177d-4f89-a25b-f9274eb8d4ff"
}
},
"startDate": "2021-02-19T23:44:06.0Z",
"observationDate": "2021-02-19T23:45:05.999Z"
}
{
"id": "d3a770d3-306b-eb11-aa7f-f8e4e3480e0d",
"namespace": "Project",
"deviceDataContextID": "8c8ca79c-cb62-4e01-acaf-3201ca88e7bb",
"insertedDate": "2021-02-19T23:45:07.497Z",
"modifiedDate": "2021-02-19T23:45:07.497Z",
"identifier": "41a0f952-a9eb-4e05-8ff1-20229460e333",
"type": "RestingHeartRate",
"value": "73",
"units": "BPM",
"properties": {
"PostalCode": "48104",
"Sequence": "32"
},
"source": {
"identifier": "BPCuff1",
"properties": {
"Model": "BP130X",
"Serial": "17117bb6-177d-4f89-a25b-f9274eb8d4ff"
}
},
"startDate": "2021-02-19T23:44:06.0Z",
"observationDate": "2021-02-19T23:45:05.999Z"
}
Persist Device Data Points
MyDataHelps.persistDeviceData(deviceDataPoints)
Persist device data can be used to add new or update existing points. Each device data point is uniquely identified by a combination of its properties, called a natural key. Properties that are part of the natural key are identified below.
To update an existing device data point, persist one whose natural key properties exactly match the one to be updated. All non-natural key properties will be updated to your persisted point.
To add a new device data point, provide enough natural key properties to uniquely identify it. Recommended properties include identifier, type and observationDate; these can be made into a unique combination for most device data points.
Parameters
identifier
string
External identifier for the device data point. Set by the source application, and may be empty.
type
string
(required)
General category of data, like steps or heartRate. Specific values vary by namespace. See Data Types for details.
value
string
(required)
The value of the recorded data point.
units
string
The units, if any, that the data was recorded in.
properties
object
An object whose key-value pairs represent properties of the device data point.
source
deviceDataSource
An object containing identifying information about the device which recorded the data point.
startDate
date
The date at which this device data point began being recorded (for data that is recorded over time). Natural key property.
observationDate
date
The date at which this device data point was completely recorded. Natural key property.
Availability
var deviceDataSource = {
identifier: "BPCuff1",
properties:
{
"Model": "BP130X",
"Serial": "17117bb6-177d-4f89-a25b-f9274eb8d4ff"
}
};
var deviceDataPoints = [ {
identifier: "c87223f6-174d-4453-bbfd-c24021a7161d",
type: "RestingHeartRate",
value: "73",
properties: {
"PostalCode": 48104,
"Sequence": "32"
},
source: deviceDataSource
} ];
MyDataHelps.persistDeviceData(deviceDataPoints)
.then( function() {
console.log( "Device data persisted" );
} );
var deviceDataSource = {
identifier: "BPCuff1",
properties:
{
"Model": "BP130X",
"Serial": "17117bb6-177d-4f89-a25b-f9274eb8d4ff"
}
};
var deviceDataPoints = [ {
identifier: "c87223f6-174d-4453-bbfd-c24021a7161d",
type: "RestingHeartRate",
value: "73",
properties: {
"PostalCode": 48104,
"Sequence": "32"
},
source: deviceDataSource
} ];
MyDataHelps.persistDeviceData(deviceDataPoints)
.then( function() {
console.log( "Device data persisted" );
} );
Delete Device Data Point
MyDataHelps.deleteDeviceDataPoint(dataPointId)
Deletes a data point.
Warning
This operation CANNOT be undone.
MyDataHelps.deleteDeviceDataPoint("d3a770d3-306b-eb11-aa7f-f8e4e3480e0d")
.then( function(result) {
console.log("Device data point deleted.");
} );
MyDataHelps.deleteDeviceDataPoint("d3a770d3-306b-eb11-aa7f-f8e4e3480e0d")
.then( function(result) {
console.log("Device data point deleted.");
} );