Device Data API (V2)

The device data API allows you to manage data obtained from participant 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
Device Data Object
Query Device Data
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.

Device Data Object

The basic device data object is common to many of the device APIs. See Device and Sensor Data for an overview of how to use/interpret device data.

id guid

Auto-generated, globally-unique identifier for this device data point.

participantID guid

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

participantIdentifier string

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

identifier string

External identifier for the device data point. Set by the source application, and may be empty.

namespace string

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

type string

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

value string

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 device-specific metadata associated with this device data point. The metadata will vary depending on the source application.

dataSource object

An object containing identifying information about the device which recorded the data point. This metadata will vary depending on the source application.

startDate date

The date at which this device data point began being recorded (for data that is recorded over time), in ISO8601 format. The timezone offset, if available, is stored in startDateOffset.

startDateOffset string

Timezone offset for startDate. Not all data sources provide a timezone offset.

observationDate date

The date at which this device data point was completely recorded, in ISO8601 format. The timezone offset, if available, is stored in observationDateOffset.

observationDateOffset string

Timezone offset for observationDate. Not all data sources provide a timezone offset.

insertedDate date

Date when the record was created, in ISO8601 format.

modifiedDate date

Date when the record was last modified, in ISO8601 format.

    Sample Device Data 
    
  

    {
    "id": "e266d703-39c3-4af8-b7a3-91b141a87ea0",
    "participantID": "572826f8-e891-ed11-98ad-f4ce23710c45",
    "participantIdentifier": "9ccd54ac-e891-ed11-98ad-f4ce23710c45",
    "namespace": "AppleHealth",
    "type": "Steps",
    "identifier": "7530C212-067A-44F2-AB82-7EA8BBB27F66",
    "value": "29",
    "units": "count",
    "startDate": "2024-02-14T18:48:00",
    "startDateOffset": "-05:00:00",
    "observationDate": "2024-02-14T18:48:00",
    "observationDateOffset": "-05:00:00",
    "insertedDate": "2024-02-26T17:25:36.680936Z",
    "modifiedDate": "2024-02-26T17:25:36.680936Z",
    "properties": {
      "metadata_HKExternalUUID": "bd3002074ad88a1a842c130f553b37470f750d34",
      "metadata_HKMetadataKeySyncVersion": "1707996994",
      "metadata_HKMetadataKeySyncIdentifier": "bd3002074ad88a1a842c130f553b37470f750d34"
    },
    "dataSource": {
      "identifier": "OVk/5oNQ1nF24UFIi0n1SspG25sX436qGfS0sz3U9cg=",
      "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": "e266d703-39c3-4af8-b7a3-91b141a87ea0",
    "participantID": "572826f8-e891-ed11-98ad-f4ce23710c45",
    "participantIdentifier": "9ccd54ac-e891-ed11-98ad-f4ce23710c45",
    "namespace": "AppleHealth",
    "type": "Steps",
    "identifier": "7530C212-067A-44F2-AB82-7EA8BBB27F66",
    "value": "29",
    "units": "count",
    "startDate": "2024-02-14T18:48:00",
    "startDateOffset": "-05:00:00",
    "observationDate": "2024-02-14T18:48:00",
    "observationDateOffset": "-05:00:00",
    "insertedDate": "2024-02-26T17:25:36.680936Z",
    "modifiedDate": "2024-02-26T17:25:36.680936Z",
    "properties": {
      "metadata_HKExternalUUID": "bd3002074ad88a1a842c130f553b37470f750d34",
      "metadata_HKMetadataKeySyncVersion": "1707996994",
      "metadata_HKMetadataKeySyncIdentifier": "bd3002074ad88a1a842c130f553b37470f750d34"
    },
    "dataSource": {
      "identifier": "OVk/5oNQ1nF24UFIi0n1SspG25sX436qGfS0sz3U9cg=",
      "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"
        ...
      ],
      ...
    }
  },

Query Device Data

GET api/v2/administration/projects/:projectID/devicedatapoints

Queries for device data, at either the participant or population level. You can query across several different kinds of dates. See Dates in Device Data for details.

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.

participantIdentifier string

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

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.

Response Fields

deviceDataPoints collection

A list of the device data points.

Element Fields

deviceDataPoints[n].id guid

Auto-generated, globally-unique identifier for this device data point.

deviceDataPoints[n].participantID guid

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

deviceDataPoints[n].participantIdentifier string

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

deviceDataPoints[n].identifier string

External identifier for the device data point. Set by the source application, and may be empty.

deviceDataPoints[n].namespace string

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

deviceDataPoints[n].type string

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

deviceDataPoints[n].value string

The value of the recorded data point.

deviceDataPoints[n].units string

The units, if any, that the data was recorded in.

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.

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.

deviceDataPoints[n].startDate date

The date at which this device data point began being recorded (for data that is recorded over time), in ISO8601 format. The timezone offset, if available, is stored in startDateOffset.

deviceDataPoints[n].startDateOffset string

Timezone offset for startDate. Not all data sources provide a timezone offset.

deviceDataPoints[n].observationDate date

The date at which this device data point was completely recorded, in ISO8601 format. The timezone offset, if available, is stored in observationDateOffset.

deviceDataPoints[n].observationDateOffset string

Timezone offset for observationDate. Not all data sources provide a timezone offset.

deviceDataPoints[n].insertedDate date

Date when the record was created, in ISO8601 format.

deviceDataPoints[n].modifiedDate date

Date when the record was last modified, in ISO8601 format.

nextPageID guid

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

    Sample Response 
    
  

    {
  "deviceDataPoints": [
    {
      "id": "4f73e5ec-e52b-4651-a8e2-42a6555b6601",
      "namespace": "AppleHealth",    
      "type": "Resting Heart Rate",
      ...
    },
    {
      "id": "f716b2c5-980d-484f-a4b4-8663e9acc506",
      "namespace": "AppleHealth",
      "type": "Resting Heart Rate",
      ...
    },
    ...
  ],
  "nextPageID": "a706abd5-cc85-482b-909c-ddd92c8abbde"
}
  {
  "deviceDataPoints": [
    {
      "id": "4f73e5ec-e52b-4651-a8e2-42a6555b6601",
      "namespace": "AppleHealth",    
      "type": "Resting Heart Rate",
      ...
    },
    {
      "id": "f716b2c5-980d-484f-a4b4-8663e9acc506",
      "namespace": "AppleHealth",
      "type": "Resting Heart Rate",
      ...
    },
    ...
  ],
  "nextPageID": "a706abd5-cc85-482b-909c-ddd92c8abbde"
}

See Device Data Object for all device fields.

Query Available Data Types

GET api/v2/administration/projects/:projectID/devicedatapoints/alldatatypes

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

GET api/v2/administration/projects/:projectID/devicedatapoints/aggregate

This operation builds on the basic device data query, but aggregates the results based on a defined interval and aggregate function(s). For example, you could query for all data points of type HeartRate for a given participant identifier within a date range, and then ask for the min, max, and average heart rates over each 24-hour interval (based on observation date).

Available aggregate functions include:

min
max
avg
count
sum

Since not all aggregate functions befit all data types, you must specify which ones you need for each query.

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.

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 (required)

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

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

intervals collection

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

Element Fields

intervals[n].participantID guid

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

intervals[n].participantIdentifier string

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

intervals[n].namespace string

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

intervals[n].type string

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

intervals[n].date date

The date the metrics were observed, in ISO8601 format.

intervals[n].statistics object

An object whose key-value pairs represent the results of the aggregate functions requested.

nextPageID string

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

    Sample Query Params 
    
  

        {
        "namespace": "fitbit",
        "type": "activities-heart-intraday",
        "observedBefore": "2023-11-08T00:00:00+00:00",
        "observedAfter": "2023-11-01T00:00:00+00:00",
        "participantIdentifier": "PT-123",
        "intervalType": "Hours",
        "intervalAmount": "6",
        "aggregateFunctions": [ "min", "max", "avg" ]
    }
      {
        "namespace": "fitbit",
        "type": "activities-heart-intraday",
        "observedBefore": "2023-11-08T00:00:00+00:00",
        "observedAfter": "2023-11-01T00:00:00+00:00",
        "participantIdentifier": "PT-123",
        "intervalType": "Hours",
        "intervalAmount": "6",
        "aggregateFunctions": [ "min", "max", "avg" ]
    }

    Sample Response 
    
  

    {
  "intervals": [
    {
      "participantID": "572826f8-e891-ed11-98ad-f4ce23710c45",
      "participantIdentifier": "9ccd54ac-e891-ed11-98ad-f4ce23710c45",
      "date": "2023-11-01T00:00:00+00:00",
      "namespace": "AppleHealth",
      "type": "Heart Rate",
      "date": "2023-12-07T00:00:00",
      "statistics": {
        "min": 73,
        "avg": 88,
        "max": 97
      }
    },
    {
      "participantID": "572826f8-e891-ed11-98ad-f4ce23710c45",
      "participantIdentifier": "9ccd54ac-e891-ed11-98ad-f4ce23710c45",
      "date": "2023-11-02T00:06:00+00:00",
      "namespace": "AppleHealth",
      "type": "Heart Rate",
      "date": "2023-12-06T18:00:00",
      "statistics": {
        "min": 75,
        "avg": 87,
        "max": 102
      }
    },
    ...
  ],
  "nextPageID": "2023-12-06T18:00:00"
}
  {
  "intervals": [
    {
      "participantID": "572826f8-e891-ed11-98ad-f4ce23710c45",
      "participantIdentifier": "9ccd54ac-e891-ed11-98ad-f4ce23710c45",
      "date": "2023-11-01T00:00:00+00:00",
      "namespace": "AppleHealth",
      "type": "Heart Rate",
      "date": "2023-12-07T00:00:00",
      "statistics": {
        "min": 73,
        "avg": 88,
        "max": 97
      }
    },
    {
      "participantID": "572826f8-e891-ed11-98ad-f4ce23710c45",
      "participantIdentifier": "9ccd54ac-e891-ed11-98ad-f4ce23710c45",
      "date": "2023-11-02T00:06:00+00:00",
      "namespace": "AppleHealth",
      "type": "Heart Rate",
      "date": "2023-12-06T18:00:00",
      "statistics": {
        "min": 75,
        "avg": 87,
        "max": 102
      }
    },
    ...
  ],
  "nextPageID": "2023-12-06T18:00:00"
}

Aggregate Daily Sleep Data

GET api/v2/administration/projects/:projectID/devicedatapoints/aggregate/dailysleep

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