Device Data (V2)

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. For more information, see Device Data API Versions for details.

Contents

Concepts
Namespaces
Query Device Data Points
Query Available Data Types
Aggregate Device Data
Aggregate Daily Sleep Data

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

properties object

Searches the device-specific metadata in the properties field. Each key/value pair represents a metadata field name (a key of the properties object) and the associated search value.

dataSource object

Searches the device-specific metadata in the dataSource field. Each key/value pair represents a metadata field name (a key of the dataSource object) and the associated search value.

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.

Element Fields

result.deviceDataPoints collection

A list of DeviceDataPoints filtered by the query parameters.

Element Fields

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

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].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"
}

Query Available Data Types

getDeviceDataV2AllDataTypes()

Provides a list of all possible data types, by namespace. This can aid you in knowing which types you can query for.

Note
Although data from the project namespace can be queried using the Device Data API, it is not included in this list. SDK developers manage which data types exist within their project’s namespace.

Response Fields

types collection

A list of all device data types.

Element Fields

types[n].namespace string

Which namespace the type is available in. See namespaces for details.

types[n].type string

The data type name. Note that each namespace has its own naming conventions, and similar concepts may be named differently in different namespaces.

types[n].enabled boolean

Whether this type of data is enabled in the project’s device data collection settings.

    Sample Response 
    
  

    [
    {
        "namespace": "AppleHealth",
        "type": "Body Mass Index (BMI)",
        "enabled": true
    },
    {
         "namespace": "Fitbit",
         "type": "activities-heart-intraday",
         "enabled": false
     },
     ...
]
  [
    {
        "namespace": "AppleHealth",
        "type": "Body Mass Index (BMI)",
        "enabled": true
    },
    {
         "namespace": "Fitbit",
         "type": "activities-heart-intraday",
         "enabled": false
     },
     ...
]

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.

properties object

Searches the device-specific metadata in the properties field. Each key/value pair represents a metadata field name (a key of the properties object) and the associated search value.

dataSource object

Searches the device-specific metadata in the dataSource field. Each key/value pair represents a metadata field name (a key of the dataSource object) and the associated search value.

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.

Element Fields

result.deviceDataPoints collection

A list of DeviceDataPoints filtered by the query parameters.

Element Fields

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

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].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"
}

Aggregate Daily Sleep Data

MyDataHelps.queryDeviceDataV2DailySleep(queryParameters)

This variant of the Aggregate Data query is specially geared towards collating daily sleep data. Instead of reporting basic statistics, such as max or average, it lists sleep/wake periods with a summary of their sleep type and duration.

Tip
Sleep data is aggregated over a time period of 6am to 6pm in the device’s local time.

Fitbit consolidates and reconcile sleep data across multiple devices, so the source parameter will always be blank. Apple Health may provide multiple records for each interval—one per device. These periods may overlap, so you will need to manually reconcile them.

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

participantID guid

Search for device data for a participant based on the participant’s internal, stable, unique ID field.

participantIdentifier string

Search for device data for a participant based on the project-set, unique participant identifier.

observedBefore date

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

observedAfter date

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

modifiedBefore date

Include only device data points updated in the system before this date, in ISO8601 format.

modifiedAfter date

Include only device data points updated in the system after this date, in ISO8601 format.

insertedBefore date

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

insertedAfter date

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

properties object

Searches the device-specific metadata in the properties field. Each key/value pair represents a metadata field name (a key of the properties object) and the associated search value.

dataSource object

Searches the device-specific metadata in the dataSource field. Each key/value pair represents a metadata field name (a key of the dataSource object) and the associated search value.

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.

Response Fields

sleepStageSummaries collection

A list of the aggregated sleep data, each representing a single interval.

Element Fields

sleepStageSummaries[n].participantID guid

Internal, stable, unique ID for the participant associated with the data.

sleepStageSummaries[n].participantIdentifier string

Project-set, unique participant identifier for the participant associated with the data.

sleepStageSummaries[n].namespace string

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

sleepStageSummaries[n].type string

General category of data, like steps or heartRate. Specific values vary by namespace. See Data Types for details.

sleepStageSummaries[n].date date

The date the metrics were observed, in ISO8601 format.

sleepStageSummaries[n].value string

A description of the type of sleep (e.g., AsleepREM or InBed). Values will vary depending on the source system.

sleepStageSummaries[n].duration string

A time span with the format hh:mm:ss.

sleepStageSummaries[n].source string

Provides details about the originating device for the data. Values will vary depending on the source system, and may not exist in all namespaces.

nextPageID string

Identifier that you can use to retrieve the next page of results.

    Sample Query Params 
    
  

        {
        "namespace": "AppleHealth",
        "type": "Sleep Analysis",
        "observedBefore": "2023-11-08T00:00:00+00:00",
        "observedAfter": "2023-11-01T00:00:00+00:00",
        "participantIdentifier": "PT-123"
    }
      {
        "namespace": "AppleHealth",
        "type": "Sleep Analysis",
        "observedBefore": "2023-11-08T00:00:00+00:00",
        "observedAfter": "2023-11-01T00:00:00+00:00",
        "participantIdentifier": "PT-123"
    }

    Sample Response 
    
  

    {
  "sleepStageSummaries": [
    {
      "participantID": "572826f8-e891-ed11-98ad-f4ce23710c45",
      "participantIdentifier": "9ccd54ac-e891-ed11-98ad-f4ce23710c45",
      "namespace": "AppleHealth",
      "type": "Sleep Analysis",
      "date": "2024-04-14T00:00:00",
      "value": "InBed",
      "duration": "08:00:57",
      "source": "John's iPhone"
    },
    {
      "participantID": "572826f8-e891-ed11-98ad-f4ce23710c45",
      "participantIdentifier": "9ccd54ac-e891-ed11-98ad-f4ce23710c45",
      "namespace": "AppleHealth",
      "type": "Sleep Analysis",
      "date": "2024-04-14T00:00:00",
      "value": "AsleepREM",
      "duration": "01:11:00",
      "source": "Oura"
    },
    ...
  ],
  "nextPageID": "2023-12-06T18:00:00"
}
  {
  "sleepStageSummaries": [
    {
      "participantID": "572826f8-e891-ed11-98ad-f4ce23710c45",
      "participantIdentifier": "9ccd54ac-e891-ed11-98ad-f4ce23710c45",
      "namespace": "AppleHealth",
      "type": "Sleep Analysis",
      "date": "2024-04-14T00:00:00",
      "value": "InBed",
      "duration": "08:00:57",
      "source": "John's iPhone"
    },
    {
      "participantID": "572826f8-e891-ed11-98ad-f4ce23710c45",
      "participantIdentifier": "9ccd54ac-e891-ed11-98ad-f4ce23710c45",
      "namespace": "AppleHealth",
      "type": "Sleep Analysis",
      "date": "2024-04-14T00:00:00",
      "value": "AsleepREM",
      "duration": "01:11:00",
      "source": "Oura"
    },
    ...
  ],
  "nextPageID": "2023-12-06T18:00:00"
}