Device Data (V2)

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

Contents

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.queryDeviceDataV2(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 string (required)

Source framework for the device data. See namespaces for details.

type string (required)

Type of data to query. See Data Types for details.

observedBefore date

Search device data points observed before this date, in ISO8601 format.

observedAfter date

Search device data points observed after this date, in ISO8601 format.

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.

insertedBefore date

Search device data points added to the system before this date, in ISO8601 format.

insertedAfter date

Search device data points added to the system after this date, in ISO8601 format.

limit int

How many entries to include in each page of results. Default and maximum is 1,000.

pageID guid

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

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].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].dataSource 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 Device Data Points 
var queryParameters = {
	namespace: "AppleHealth",
	type: "Distance Walking Running",
	observedAfter: "2024-02-18"
};

MyDataHelps.queryDeviceDataV2(queryParameters)
	.then( function(result) {
		console.log(result);
	} );
var queryParameters = { namespace: "AppleHealth", type: "Distance Walking Running", observedAfter: "2024-02-18" }; MyDataHelps.queryDeviceDataV2(queryParameters) .then( function(result) { console.log(result); } );
Console Output 
{
  "deviceDataPoints": [
  {
      "id": "2b7ebe60-15d3-4e2d-9a1f-6fbfbc412f2b",
      "participantID": "58b331cc-50ee-460b-8e7e-871e08867687",
      "participantIdentifier": "PT-123",
      "namespace": "AppleHealth",
      "type": "Distance Walking Running",
      "value": "7.8970013065263629",
      "units": "m",
      "identifier": "E52036AC-240F-47A9-9BF2-8D1DA1FEB587",
      "startDate": "2024-05-07T06:02:02",
      "startDateOffset": "-04:00:00",
      "observationDate": "2024-05-07T06:08:32",
      "observationDateOffset": "-04:00:00",
      "insertedDate": "2024-05-07T16:27:44.016578Z",
      "modifiedDate": "2024-05-07T16:27:44.016578Z",
      "properties": {
        "PostalCode": "12345"
      },
      "dataSource": {
          "identifier": "6D8C7vR",
          "properties": {
              "sourceIdentifier": "com.apple.health.E9BBF489-8AE9-4D5F-983C-E66ED450FAE6",
              "sourceName": "John's Apple Watch",
              "sourceOperatingSystemVersion": "13.5.1",
              "deviceManufacturer": "Apple Inc.",
              "deviceModel": "iPhone",
              "uploadingDeviceIdentifier": "07e9524a-2a82-4875-b700-92d7e4024cb5"
          },
          ...
      },
      }
    },
    {
        "id": "838af277-3830-4553-ada9-b92e78d61b76",
        "participantID": "58b331cc-50ee-460b-8e7e-871e08867687",
        "participantIdentifier": "PT-123",
        "namespace": "AppleHealth",
        ...
    }
  ],
  "nextPageID": "a706abd5-cc85-482b-909c-ddd92c8abbde"
}
{ "deviceDataPoints": [ { "id": "2b7ebe60-15d3-4e2d-9a1f-6fbfbc412f2b", "participantID": "58b331cc-50ee-460b-8e7e-871e08867687", "participantIdentifier": "PT-123", "namespace": "AppleHealth", "type": "Distance Walking Running", "value": "7.8970013065263629", "units": "m", "identifier": "E52036AC-240F-47A9-9BF2-8D1DA1FEB587", "startDate": "2024-05-07T06:02:02", "startDateOffset": "-04:00:00", "observationDate": "2024-05-07T06:08:32", "observationDateOffset": "-04:00:00", "insertedDate": "2024-05-07T16:27:44.016578Z", "modifiedDate": "2024-05-07T16:27:44.016578Z", "properties": { "PostalCode": "12345" }, "dataSource": { "identifier": "6D8C7vR", "properties": { "sourceIdentifier": "com.apple.health.E9BBF489-8AE9-4D5F-983C-E66ED450FAE6", "sourceName": "John's Apple Watch", "sourceOperatingSystemVersion": "13.5.1", "deviceManufacturer": "Apple Inc.", "deviceModel": "iPhone", "uploadingDeviceIdentifier": "07e9524a-2a82-4875-b700-92d7e4024cb5" }, ... }, } }, { "id": "838af277-3830-4553-ada9-b92e78d61b76", "participantID": "58b331cc-50ee-460b-8e7e-871e08867687", "participantIdentifier": "PT-123", "namespace": "AppleHealth", ... } ], "nextPageID": "a706abd5-cc85-482b-909c-ddd92c8abbde" }

Aggregate Device Data

MyDataHelps.queryDeviceDataV2Aggregate(queryParameters)

This operation builds on the basic device data query, but aggregates the results based on a defined interval and aggregate function(s). See the Device Data API for details.

Parameters

namespace string (required)

Source framework for the device data. See namespaces for details.

type string (required)

Type of data to query. See Data Types for details.

intervalType string (required)

The units for intervalAmount, one of: Minutes, Hours, Days, Weeks, Months.

intervalAmount int (required)

Used in conjunction with intervalType to define the span of each aggregate interval, e.g., 12 hours or 1 week.

aggregateFunctions string array (required)

A list of statistics to aggregate. May include: min, avg, count, max, sum.

observedBefore date

Search device data points observed before this date, in ISO8601 format.

observedAfter date

Search device data points observed after this date, in ISO8601 format.

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.

insertedBefore date

Search device data points added to the system before this date, in ISO8601 format.

insertedAfter date

Search device data points added to the system after this date, in ISO8601 format.

limit int

How many entries to include in each page of results. Default and maximum is 1,000.

pageID string

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

Promise<DeviceDataAggregatePage>

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].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].dataSource 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
Aggregating Device Data 
var queryParameters = {
	namespace: "AppleHealth",
	type: "Distance Walking Running",
	observedAfter: "2024-02-18",
  intervalType: "Hours",
  intervalAmount: "6",
  aggregateFunctions: [ "min", "max", "avg" ]
};

MyDataHelps.queryDeviceDataV2Aggregate(queryParameters)
	.then( function(result) {
		console.log(result);
	} );
var queryParameters = { namespace: "AppleHealth", type: "Distance Walking Running", observedAfter: "2024-02-18", intervalType: "Hours", intervalAmount: "6", aggregateFunctions: [ "min", "max", "avg" ] }; MyDataHelps.queryDeviceDataV2Aggregate(queryParameters) .then( function(result) { console.log(result); } );
Console Output 
{
  "intervals": [
    {
      "participantID": "58b331cc-50ee-460b-8e7e-871e08867687",
      "participantIdentifier": "PT-123",
      "namespace": "AppleHealth",
      "type": "Heart Rate",
      "date": "2023-12-07T00:00:00",
      "statistics": {
        "min": 63,
        "avg": 73.41888618469238,
        "max": 136,
      }
    },
    {
      "participantID": "58b331cc-50ee-460b-8e7e-871e08867687",
      "participantIdentifier": "PT-123",
      "namespace": "AppleHealth",
      "type": "Heart Rate",
      "date": "2023-12-06T06:00:00",
      "statistics": {
        "min": 54,
        "avg": 66.14068101762652,
        "max": 140
      }
    },
    ...
  ],
  "nextPageID": "2023-12-06T18:00:00"
}
{ "intervals": [ { "participantID": "58b331cc-50ee-460b-8e7e-871e08867687", "participantIdentifier": "PT-123", "namespace": "AppleHealth", "type": "Heart Rate", "date": "2023-12-07T00:00:00", "statistics": { "min": 63, "avg": 73.41888618469238, "max": 136, } }, { "participantID": "58b331cc-50ee-460b-8e7e-871e08867687", "participantIdentifier": "PT-123", "namespace": "AppleHealth", "type": "Heart Rate", "date": "2023-12-06T06:00:00", "statistics": { "min": 54, "avg": 66.14068101762652, "max": 140 } }, ... ], "nextPageID": "2023-12-06T18:00:00" }

Have questions about MyDataHelps? Contact us.

© 2024 CareEvolution, LLC