The device data API allows you to manage data obtained from participant wearables and other devices.
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.
Device data is grouped into namespaces, which represent the source frameworks that generate the data. There is also a separate “Project” namespace, where projects can persist their own data. Supported namespaces include:
Project
: Data persisted by project sources and SDKs.Fitbit
: Data persisted by a linked Fitbit account.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.Auto-generated, globally-unique identifier for this device data point.
Source framework for the device data. See namespaces for details.
Identifier for a group of device data points, which share some context. Will be null if the device data point isn’t grouped.
Identifies the participant associated with the data.
Date when the record was created, in ISO8601 format.
Date when the record was last modified, in ISO8601 format.
String used to name a device data point.
The general category this device data point belongs in, or what the device data represents. This field is a freeform string controlled by the source system based on its chosen categories.
The value of the recorded data point.
The units, if any, that the data was recorded in.
An object whose key-value pairs represent 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.
Identifying string for the data source.
An object whose key-value pairs represent properties of the device data source. The specific properties 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 date at which this device data point was completely recorded, in ISO8601 format.
{
"id": "4f73e5ec-e52b-4651-a8e2-42a6555b6601",
"namespace": "AppleHealth",
"deviceDataContextID": "a7a116e7-a90c-4814-b90a-d0825c428cac",
"insertedDate": "2020-06-16T16:05:54.767Z",
"modifiedDate": "2020-06-16T16:05:54.767Z",
"participantID": "58b331cc-50ee-460b-8e7e-871e08867687",
"participantIdentifier": "PT-123",
"identifier": "7fc24c0f-fc26-44b1-88f3-22d8750f00b3",
"type": "DistanceWalkingRunning",
"value": "7.8970013065263629",
"units": "m",
"properties": {
"PostalCode": "12345"
},
"source": {
"identifier": "6D8C7vR",
"properties": {
"SourceIdentifier": "com.apple.health.E9BBF489-8AE9-4D5F-983C-E66ED450FAE6",
"SourceName": "Jane's iPhone 11",
"SourceOperatingSystemVersion": "13.5.1",
"DeviceManufacturer": "Apple Inc.",
"DeviceModel": "iPhone",
"UploadingDeviceIdentifier": "07e9524a-2a82-4875-b700-92d7e4024cb5"
}
},
"startDate": "2020-06-16T10:52:11-05:00",
"observationDate": "2020-06-16T10:52:17-05:00"
}
{
"id": "4f73e5ec-e52b-4651-a8e2-42a6555b6601",
"namespace": "AppleHealth",
"deviceDataContextID": "a7a116e7-a90c-4814-b90a-d0825c428cac",
"insertedDate": "2020-06-16T16:05:54.767Z",
"modifiedDate": "2020-06-16T16:05:54.767Z",
"participantID": "58b331cc-50ee-460b-8e7e-871e08867687",
"participantIdentifier": "PT-123",
"identifier": "7fc24c0f-fc26-44b1-88f3-22d8750f00b3",
"type": "DistanceWalkingRunning",
"value": "7.8970013065263629",
"units": "m",
"properties": {
"PostalCode": "12345"
},
"source": {
"identifier": "6D8C7vR",
"properties": {
"SourceIdentifier": "com.apple.health.E9BBF489-8AE9-4D5F-983C-E66ED450FAE6",
"SourceName": "Jane's iPhone 11",
"SourceOperatingSystemVersion": "13.5.1",
"DeviceManufacturer": "Apple Inc.",
"DeviceModel": "iPhone",
"UploadingDeviceIdentifier": "07e9524a-2a82-4875-b700-92d7e4024cb5"
}
},
"startDate": "2020-06-16T10:52:11-05:00",
"observationDate": "2020-06-16T10:52:17-05:00"
}
GET api/v1/administration/projects/:projectID/devicedatapoints?namespace=Project&pageSize=10
The device data query supports two different date queries: modifiedBefore/After
and observedBefore/After
. Due to variations and limitations in device data synchronization, it is possible for older data points to turn up in the system unpredictably. Using the “observed” query parameters will search based on the date the data was observed or recorded by the device, while the “modified” parameters will search based on the date it arrived in the system. Use the modifiedAfter
query to search for data that has arrived since a prior query.
Source framework for the device data. See namespaces for details.
Search for device data for a participant based on the participant’s internal ID field.
Search for device data for a participant based on the project-specific participant identifier.
Comma-separated list of types of device data, e.g. HeartRate.
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.
How many entries to include in each page of results. Default and maximum is 100.
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.
A list of the device data points.
Auto-generated, globally-unique identifier for this device data point.
Source framework for the device data. See namespaces for details.
Identifier for a group of device data points, which share some context. Will be null if the device data point isn’t grouped.
Identifies the participant associated with the data.
Date when the record was created, in ISO8601 format.
Date when the record was last modified, in ISO8601 format.
String used to name a device data point.
The general category this device data point belongs in, or what the device data represents. This field is a freeform string controlled by the source system based on its chosen categories.
The value of the recorded data point.
The units, if any, that the data was recorded in.
An object whose key-value pairs represent 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.
Identifying string for the data source.
An object whose key-value pairs represent properties of the device data source. The specific properties 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 date at which this device data point was completely recorded, 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": "HeartRate",
...
},
{
"id": "f716b2c5-980d-484f-a4b4-8663e9acc506",
"namespace": "AppleHealth",
"type": "HeartRate",
...
},
...
],
"nextPageID": "660874e9-ae7d-40e3-a7d2-b4ef0e5e465b"
}
{
"deviceDataPoints": [
{
"id": "4f73e5ec-e52b-4651-a8e2-42a6555b6601",
"namespace": "AppleHealth",
"type": "HeartRate",
...
},
{
"id": "f716b2c5-980d-484f-a4b4-8663e9acc506",
"namespace": "AppleHealth",
"type": "HeartRate",
...
},
...
],
"nextPageID": "660874e9-ae7d-40e3-a7d2-b4ef0e5e465b"
}
POST api/v1/administration/projects/:projectID/devicedatapoints
Persist device data can be used to add new or update existing points.
Project
namespace. You cannot alter or add data in other namespaces.
Each device data point is uniquely identified by a combination of the following properties:
If all four of these properties exactly match the existing data point in a persist action, the other data will be updated. Otherwise, a new data point will be created.
List of data point models.
Identifies the participant associated with the data.
String used to name a device data point.
The general category this device data point belongs in, or what the device data represents. This field is a freeform string controlled by the source system based on its chosen categories.
The value of the recorded data point.
The units, if any, that the data was recorded in.
An object whose key-value pairs represent 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.
Identifying string for the data source.
An object whose key-value pairs represent properties of the device data source. The specific properties 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 date at which this device data point was completely recorded, in ISO8601 format.
[
{
"identifier": "0b425f95-7c43-42f6-b069-60cbb11dce1d",
"observationDate": "2020-06-16T10:52:17-05:00",
"type": "SBP",
"value": "120",
"units": "mmHg",
"participantIdentifier": "PT-123",
...
},
{
"identifier": "0b425f95-7c43-42f6-b069-60cbb11dce1d",
"observationDate": "2020-06-17T11:50:10-05:00",
"type": "SBP",
"value": "120",
"units": "mmHg",
"participantIdentifier": "PT-123",
...
},
...
]
[
{
"identifier": "0b425f95-7c43-42f6-b069-60cbb11dce1d",
"observationDate": "2020-06-16T10:52:17-05:00",
"type": "SBP",
"value": "120",
"units": "mmHg",
"participantIdentifier": "PT-123",
...
},
{
"identifier": "0b425f95-7c43-42f6-b069-60cbb11dce1d",
"observationDate": "2020-06-17T11:50:10-05:00",
"type": "SBP",
"value": "120",
"units": "mmHg",
"participantIdentifier": "PT-123",
...
},
...
]