Device Data
In MyDataHelps, participants may contribute data collected by wearables and other devices.
Because device data is a powerful tool available to MyDataHelps studies, we strongly recommend reading about device data concepts.
Contents
Namespaces
Device data is grouped into namespaces, which represent the source frameworks that generate the data. There is also a separate “Project” namespace, where projects can persist their own data. Supported namespaces include:
Project: Data persisted by project sources and SDKs.Fitbit: Data persisted by a linked Fitbit account.AppleHealth: Data imported from Apple Health.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)
Parameters
Specifies the source framework for the device data. Must be one of the following values:
- “Project”: Data persisted by Project sources, including the Persist Device Data API described below.
- “Fitbit”: Data persisted by a linked Fitbit account.
- “AppleHealth”: Data imported from AppleHealth.
- “GoogleFit”: Data imported from GoogleFit.
- “Garmin”: Data imported from Garmin devices.
- “AirNowApi”: Air quality index data imported from AirNow.gov.
- “WeatherBit”: Weather forecast data imported from WeatherBit.io.
List of types of device data, e.g. HeartRate.
Filters device data points to those observed after this date.
Filters device data points to those observed before this date.
How many entries to include in each page of results. Default and maximum is 100.
Each page of results will return a nextPageID if there are additional pages that can be queried. Supply that to pageID to query the next page. When excluded, retrieves the first page.
Returns
Resolves to a result object containing a page of device data points.
A list of DeviceDataPoints filtered by the query parameters.
Auto-generated, globally-unique identifier for this device data point.
Identifies device data as from a specific source system. One of the following values:
- “Project”: Data persisted by the Persist Device Data Points operation below.
- “Fitbit”: Data imported from a linked Fitbit account.
- “AppleHealth”: Data imported from AppleHealth.
- “GoogleFit”: Data imported from GoogleFit.
- “AirNowApi”: Air quality index data imported from AirNow.gov.
- “WeatherBit”: Weather forecast data imported from WeatherBit.io.
Identifier for a group of device data points, which share some context. Will be null if the device data point isn’t grouped.
Date (in UTC) when the data point was first added.
Date (in UTC) when the data point was last modified.
String used to name a device data point.
The general category this device data point belongs in, or what the device data represents.
The observed value for what this device data point represents, e.g. number of steps from a step tracker.
The units, if any, that the device data was recorded in.
A non-standard object whose key-value pairs represent metadata associated with this device data point.
An object containing identifying information about the device which recorded the data point.
Identifying string for the data source. Natural key property for device data source.
An object whose fields represent key/value pairs, describing the device data source.
The date at which this device data point began being recorded (for data that is recorded over time).
The date at which this device data point was completely recorded.
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: "HeartRate",
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: "HeartRate",
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": "HeartRate",
"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": null
}{
"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": "HeartRate",
"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": null
}
Get Device Data Point
MyDataHelps.getDeviceDataPoint(dataPointId)
Gets details for a specific data point, by identifier.
Parameters
The device data point.
Auto-generated, globally-unique identifier for this device data point.
Identifies device data as from a specific source system. One of the following values:
- “Project”: Data persisted by the Persist Device Data Points operation below.
- “Fitbit”: Data imported from a linked Fitbit account.
- “AppleHealth”: Data imported from AppleHealth.
- “GoogleFit”: Data imported from GoogleFit.
- “AirNowApi”: Air quality index data imported from AirNow.gov.
- “WeatherBit”: Weather forecast data imported from WeatherBit.io.
Identifier for a group of device data points, which share some context. Will be null if the device data point isn’t grouped.
Date (in UTC) when the data point was first added.
Date (in UTC) when the data point was last modified.
String used to name a device data point.
The general category this device data point belongs in, or what the device data represents.
The observed value for what this device data point represents, e.g. number of steps from a step tracker.
The units, if any, that the device data was recorded in.
A non-standard object whose key-value pairs represent metadata associated with this device data point.
An object containing identifying information about the device which recorded the data point.
Identifying string for the data source. Natural key property for device data source.
An object whose fields represent key/value pairs, describing the device data source.
The date at which this device data point began being recorded (for data that is recorded over time).
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": "HeartRate",
"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": "HeartRate",
"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
String used to name a device data point. Natural key property.
The general category this device data point belongs in, or what the device data represents. Natural key property.
The value of the recorded data point.
The units, if any, that the data was recorded in.
An object whose key-value pairs represent properties of the device data point.
An object containing identifying information about the device which recorded the data point.
Identifying string for the data source. Natural key property for device data source.
An object whose fields represent key/value pairs, describing the device data source.
The date at which this device data point began being recorded (for data that is recorded over time). Natural key property.
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: "HeartRate",
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: "HeartRate",
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.
This operation CANNOT be undone.
Availability
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.");
} );
