Device Data API (V2)
The device data API allows you to manage data obtained from participant wearables and other devices.
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. Access to V2 is not enabled by default. Contact support if you wish to enable V2 for your project. For more information, see Device Data API Versions for details.
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. | ||
HealthConnect |
- | Data imported from Google Health Connect. | |
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.
Auto-generated, globally-unique identifier for this device data point.
Internal, stable, unique ID for the participant associated with the data.
Project-set, unique participant identifier for the participant associated with the data.
External identifier for the device data point. Set by the source application, and may be empty.
Source framework for the device data. See namespaces for details.
General category of data, like steps
or heartRate
. Specific values vary by namespace. See Data Types for details.
The value of the recorded data point.
The units, if any, that the data was recorded in.
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.
An object containing identifying information about the device which recorded the data point. This metadata will vary depending on the source application.
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
.
Timezone offset for startDate
. Not all data sources provide a timezone offset.
The date at which this device data point was completely recorded, in ISO8601 format. The timezone offset, if available, is stored in observationDateOffset
.
Timezone offset for observationDate
. Not all data sources provide a timezone offset.
Date when the record was created, in ISO8601 format.
Date when the record was last modified, in ISO8601 format.
{
"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
Source framework for the device data. See namespaces for details.
Type of data to query. See Data Types for details.
Search for device data for a participant based on the participant’s internal, stable, unique ID.
Search for device data for a participant based on the project-set, unique participant identifier.
Search device data points observed before this date, in ISO8601 format.
Search device data points observed after this date, in ISO8601 format.
Search device data points updated in the system before this date, in ISO8601 format.
Search device data points updated in the system after this date, in ISO8601 format.
Search device data points added to the system before this date, in ISO8601 format.
Search device data points added to the system after this date, in ISO8601 format.
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.
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.
How many entries to include in each page of results. Default and maximum is 1,000.
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
A list of the device data points.
Auto-generated, globally-unique identifier for this device data point.
Internal, stable, unique ID for the participant associated with the data.
Project-set, unique participant identifier for the participant associated with the data.
External identifier for the device data point. Set by the source application, and may be empty.
Source framework for the device data. See namespaces for details.
General category of data, like steps
or heartRate
. Specific values vary by namespace. See Data Types for details.
The value of the recorded data point.
The units, if any, that the data was recorded in.
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.
An object containing identifying information about the device which recorded the data point. This metadata will vary depending on the source application.
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
.
Timezone offset for startDate
. Not all data sources provide a timezone offset.
The date at which this device data point was completely recorded, in ISO8601 format. The timezone offset, if available, is stored in observationDateOffset
.
Timezone offset for observationDate
. Not all data sources provide a timezone offset.
Date when the record was created, in ISO8601 format.
Date when the record was last modified, in ISO8601 format.
Identifier that you can use to retrieve the next page of results.
{
"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"
}
Query Available Data Types
GET api/v2/administration/projects/:projectID/devicedatapoints/alldatatypes
Provides a list of all possible data types. This can aid you in knowing which types you can query for.
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.
Query Parameters
Optional parameter. If true, the query will return only the enabled data types. If false, it will return only the disabled types. If not specified, it will return all data types.
Response Fields
A list of all device data types.
Which namespace the type is available in. See namespaces for details.
The data type name. Note that each namespace has its own naming conventions, and similar concepts may be named differently in different namespaces.
Whether this type of data is enabled in the project’s device data collection settings.
The number of days that data for the given type will be available. Only populated for enabled types.
[
{
"namespace": "AppleHealth",
"type": "Steps",
"enabled": true,
"retentionDays": 30
},
{
"namespace": "Fitbit",
"type": "activities-steps-intraday",
"enabled": false
},
...
]
[
{
"namespace": "AppleHealth",
"type": "Steps",
"enabled": true,
"retentionDays": 30
},
{
"namespace": "Fitbit",
"type": "activities-steps-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
Source framework for the device data. See namespaces for details.
Type of data to query. See Data Types for details.
The units for intervalAmount
, one of: Minutes
, Hours
, Days
, Weeks
, Months
.
Used in conjunction with intervalType
to define the span of each aggregate interval, e.g., 12 hours or 1 week.
A comma-separated list of statistics to aggregate. May include: min
, avg
, count
, max
, sum
.
Search for device data for a participant based on the participant’s internal, stable, unique ID field.
Search for device data for a participant based on the project-set, unique participant identifier.
Include only device data points observed before this date, in ISO8601 format.
Include only device data points observed after this date, in ISO8601 format.
Include only device data points updated in the system before this date, in ISO8601 format.
Include only device data points updated in the system after this date, in ISO8601 format.
Include only device data points added to the system before this date, in ISO8601 format.
Include only device data points added to the system after this date, in ISO8601 format.
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.
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.
How many entries to include in each page of results. Default and maximum is 1,000.
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
A list of the aggregated device data fields, each representing a single interval.
Internal, stable, unique ID for the participant associated with the data.
Project-set, unique participant identifier for the participant associated with the data.
Source framework for the device data. See namespaces for details.
General category of data, like steps
or heartRate
. Specific values vary by namespace. See Data Types for details.
The date the metrics were observed, in ISO8601 format.
An object whose key-value pairs represent the results of the aggregate functions requested.
Identifier that you can use to retrieve the next page of results.
{
"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" ]
}
{
"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.
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
Source framework for the device data. See namespaces for details.
Type of data to query. See Data Types for details.
Search for device data for a participant based on the participant’s internal, stable, unique ID field.
Search for device data for a participant based on the project-set, unique participant identifier.
Include only device data points observed before this date, in ISO8601 format.
Include only device data points observed after this date, in ISO8601 format.
Include only device data points updated in the system before this date, in ISO8601 format.
Include only device data points updated in the system after this date, in ISO8601 format.
Include only device data points added to the system before this date, in ISO8601 format.
Include only device data points added to the system after this date, in ISO8601 format.
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.
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.
How many entries to include in each page of results. Default and maximum is 1,000.
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
A list of the aggregated sleep data, each representing a single interval.
Internal, stable, unique ID for the participant associated with the data.
Project-set, unique participant identifier for the participant associated with the data.
Source framework for the device data. See namespaces for details.
General category of data, like steps
or heartRate
. Specific values vary by namespace. See Data Types for details.
The date the metrics were observed, in ISO8601 format.
A description of the type of sleep (e.g., AsleepREM
or InBed
). Values will vary depending on the source system.
A time span with the format hh:mm:ss.
Provides details about the originating device for the data. Values will vary depending on the source system, and may not exist in all namespaces.
Identifier that you can use to retrieve the next page of results.
{
"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"
}
{
"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"
}