Device Data (V1)

In MyDataHelps, participants may contribute data collected by wearables and other devices.

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.
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

A non-standard object whose key-value pairs represent metadata associated with this device data point.

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

MyDataHelps Views
MyDataHelps Embeddables
Web View Steps
Querying for Project Device Data Points
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); } );
Console Output
{
  "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

A non-standard object whose key-value pairs represent metadata associated with this device data point.

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 Views
MyDataHelps Embeddables
Web View Steps
Get Device Data Point
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); } );
Console Output
{
  "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

MyDataHelps Views
MyDataHelps Embeddables
Web View Steps
Persisting Blood Pressure Device Data
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.

Availability

MyDataHelps Views
MyDataHelps Embeddables
Web View Steps
Delete Device Data Point
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."); } );