Device Data API (V1)

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

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.

deviceDataContextID guid

Identifier for a group of device data points that share some context. For example, a blood pressure reading might contain separate data points for systolic and diastolic readings, but they will share the same deviceDataContextID. Will be null if the device data point isn’t grouped.

participantIdentifier string

Identifies the participant associated with the data.

participantID guid

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

insertedDate date

Date when the record was created, in ISO8601 format.

modifiedDate date

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

identifier string

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

value string (required)

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.

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

observationDate date

The date at which this device data point was completely recorded, in ISO8601 format.

    Sample Device Data 
    
  

    {
  "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": "John's Apple Watch",
          "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": "John's Apple Watch",
          "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"
}

Query Device Data

GET api/v1/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)

Comma-separated list of types of device data. 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.

limit int

How many entries to include in each page of results. Default and maximum is 100.

pageID guid

Each page of results will return a nextPageID if there are additional pages that can be queried. Supply that as 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].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].deviceDataContextID guid

deviceDataPoints[n].participantIdentifier string

Identifies the participant associated with the data.

deviceDataPoints[n].participantID guid

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

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.

deviceDataPoints[n].identifier string

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

deviceDataPoints[n].value string (required)

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

deviceDataPoints[n].observationDate date

The date at which this device data point was completely recorded, 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": "RestingHeartRate",
      ...
    },
    {
      "id": "f716b2c5-980d-484f-a4b4-8663e9acc506",
      "namespace": "AppleHealth",
      "type": "RestingHeartRate",
      ...
    },
    ...
  ],
  "nextPageID": "660874e9-ae7d-40e3-a7d2-b4ef0e5e465b"
}
  {
  "deviceDataPoints": [
    {
      "id": "4f73e5ec-e52b-4651-a8e2-42a6555b6601",
      "namespace": "AppleHealth",    
      "type": "RestingHeartRate",
      ...
    },
    {
      "id": "f716b2c5-980d-484f-a4b4-8663e9acc506",
      "namespace": "AppleHealth",
      "type": "RestingHeartRate",
      ...
    },
    ...
  ],
  "nextPageID": "660874e9-ae7d-40e3-a7d2-b4ef0e5e465b"
}

See Device Data Object for all device fields.

Persist Device Data

POST api/v1/administration/projects/:projectID/devicedatapoints

Persist device data can be used to add new or update existing points.

Note
This API operates within the 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:

identifier
type
startDate
observationDate

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.

Tip
Recommended properties include identifier, type and observationDate; these can be made into a unique combination for most device data points.

Body Parameters

models collection

List of data point models.

Element Fields

models[n].type string

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

models[n].participantIdentifier string

Identifies the participant associated with the data.

models[n].participantID guid

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

models[n].identifier string

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

models[n].value string (required)

The value of the recorded data point.

models[n].units string

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

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

models[n].source object

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

models[n].startDate date

The date at which this device data point began being recorded (for data that is recorded over time), in ISO8601 format.

models[n].observationDate date

The date at which this device data point was completely recorded, in ISO8601 format.

Response Fields

None

    Sample Body Parameters 
    
  

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

See Device Data Object for all device fields.