Skip to content
Tidepool API/Data API/
/
Data Set State

Data API (1.0)

The Tidepool API is an HTTP REST API used by Tidepool clients use to communicate with the Tidepool Platform.

For more information, see the Getting Started section.

Download OpenAPI description
data.v1.json
data.v1.yaml
Overview
URL

https://support.tidepool.org/

Tidepool API Support

support@tidepool.org

License

BSD-2-Clause

Terms of Service

Languages
Servers
Mock server

https://tidepool.redocly.app/_mock/reference/data.v1/

integration

https://external.integration.tidepool.org/

production

https://api.tidepool.org/

dev1

https://dev1.dev.tidepool.org/

qa1

https://qa1.development.tidepool.org/

qa2

https://qa2.development.tidepool.org/

Internal

APIs intended for internal use by Tidepool.

Operations

Data

Manages diabetes data in user's Tidepool account.

Operations

New Tidepool Diabetes Data Set

Create a new Tidepool diabetes data set.

clientobject(Client Software)

The client software that provided diabetes data.

dataSetTypestring(Data Set Type)required
Enum"continuous""normal"
Example: "continuous"
deviceIdstring(Device ID)non-emptyrequired

Globally unique to device and repeatable with each upload, e.g. device make and model with serial number

Example: "MMT-1711:12345678"
deviceManufacturersArray of strings(Device Manufacturers)required

An array of string tags indicating the manufacturer(s) of the device.

In order to avoid confusion resulting from referring to a single manufacturer with more than one name—for example, using both 'Minimed' and 'Medtronic' interchangeably—we restrict the set of strings used to refer to manufacturers to the set listed above and enforce exact string matches (including casing).

deviceManufacturers is an array of one or more string "tags" because there are devices resulting from a collaboration between more than one manufacturer, such as the Tandem G4 insulin pump with CGM integration (a collaboration between Tandem and Dexcom).

Example: ["DeviceCo"]
deviceModelstring(Device Model Name)non-emptyrequired

A string identifying the model of the device.

The deviceModel is a non-empty string that encodes the model of device. We endeavor to match each manufacturer's standard for how they represent model name in terms of casing, whether parts of the name are represented as one word or two, etc.

Example: "Devicey McDeviceface"
deviceSerialNumberstring(Device Serial Number)non-emptyrequired

A string encoding the device's serial number.

The deviceSerialNumber is a string that encodes the serial number of the device. Note that even if a manufacturer only uses digits in its serial numbers, the SN should be stored as a string regardless.

Uniquely of string fields in the Tidepool device data models, deviceSerialNumber may be an empty string. This is essentially a compromise: having the device serial number is extremely important (especially for e.g., clinical studies) but in 2016 we came across our first case where we cannot recover the serial number of the device that generated the data: Dexcom G5 data uploaded to Tidepool through Apple iOS's HealthKit integration.

Example: "B97B6D59"
deviceTagsArray of strings(Device Tags)non-empty

An array of string tags indicating the function(s) of the device.

The deviceTags array should be fairly self-explanatory as an array of tags indicating the function(s) of a particular device. For example, the Insulet OmniPod insulin delivery system has the tags bgm and insulin-pump since the PDM is both an insulin pump controller and includes a built-in blood glucose monitor.

Items Enum"bgm""cgm""insulin-pump""fgm""pen""manual"
deduplicatorobject(Deduplicator Descriptor)
timestring(date-time)(Date/Time)required

RFC 3339 / ISO 8601 timestamp with timezone information

Example: "2017-02-06T02:37:46Z"
timeProcessingstring(Time Processing)required

A string indicating what variety of processing was used to create the time and related fields such as timezoneOffset on data in this upload.

For data auditing purposes, we store a string encoding the type of algorithm used to generate the time, timezoneOffset, and other related fields from the local deviceTime. At present, there are only three options for this value:

  • none for data sources that already include a UTC-anchored time value. At present, the only data source for which this is true is Dexcom G5 or Dexcom G6 data coming through Apple's iOS HealthKit integration.
  • across-the-board-timezone for devices (all BGMs, for example) that cannot have their deviceTime values "bootstrapped" to a UTC time value; in such cases, we apply a single user-selected timezone to every deviceTime "across the board" to generate the time value.
  • utc-bootstrapping for devices (most insulin pumps and CGMs) where we use a combination of the user-selected timezone at time of upload, the most recent timestamp on device, and the history of display time changes on the device to infer the correct time value for each record.
Enum"none""across-the-board-timezone""utc-bootstrapping"
Example: "utc-bootstrapping"
timezonestring(Time Zone)required

A string timezone name from the IANA timezone database

Example: "Europe/London"
timezoneOffsetinteger(int32)(Time Zone offset)[ -10080 .. 10080 ]required

Time zone offset, expressed as positive or negative number of minutes from UTC.

Example: -420
{
  "client": {
    "name": "org.tidepool.uploader",
    "version": "2.36.1",
    "platform": "macOS 10.15.4",
    "private": {}
  },
  "dataSetType": "continuous",
  "deviceId": "MMT-1711:12345678",
  "deviceManufacturers": [
    "DeviceCo"
  ],
  "deviceModel": "Devicey McDeviceface",
  "deviceSerialNumber": "B97B6D59",
  "deviceTags": [
    "bgm"
  ],
  "deduplicator": {
    "hash": "string",
    "version": "2.36.1",
    "name": "org.tidepool.uploader"
  },
  "time": "2017-02-06T02:37:46Z",
  "timeProcessing": "utc-bootstrapping",
  "timezone": "Europe/London",
  "timezoneOffset": -420
}

Data Set State

string(Data Set State)
Enum"open""closed"
"open"

Tidepool Data Array

Diabetes Data Array

deviceIdstring(Device ID)non-emptyrequired

Globally unique to device and repeatable with each upload, e.g. device make and model with serial number

Example: "MMT-1711:12345678"
deviceModelstring(Device Model Name)non-emptyrequired

A string identifying the model of the device.

The deviceModel is a non-empty string that encodes the model of device. We endeavor to match each manufacturer's standard for how they represent model name in terms of casing, whether parts of the name are represented as one word or two, etc.

Example: "Devicey McDeviceface"
deviceSerialNumberstring(Device Serial Number)non-emptyrequired

A string encoding the device's serial number.

The deviceSerialNumber is a string that encodes the serial number of the device. Note that even if a manufacturer only uses digits in its serial numbers, the SN should be stored as a string regardless.

Uniquely of string fields in the Tidepool device data models, deviceSerialNumber may be an empty string. This is essentially a compromise: having the device serial number is extremely important (especially for e.g., clinical studies) but in 2016 we came across our first case where we cannot recover the serial number of the device that generated the data: Dexcom G5 data uploaded to Tidepool through Apple iOS's HealthKit integration.

Example: "B97B6D59"
statestring(Data Set State)required
Enum"open""closed"
Example: "open"
timestring(date-time)(Date/Time)required

RFC 3339 / ISO 8601 timestamp with timezone information

Example: "2017-02-06T02:37:46Z"
timezonestring(Time Zone)required

A string timezone name from the IANA timezone database

Example: "Europe/London"
timezoneOffsetinteger(int32)(Time Zone offset)[ -10080 .. 10080 ]required

Time zone offset, expressed as positive or negative number of minutes from UTC.

Example: -420
{
  "deviceId": "MMT-1711:12345678",
  "deviceModel": "Devicey McDeviceface",
  "deviceSerialNumber": "B97B6D59",
  "state": "open",
  "time": "2017-02-06T02:37:46Z",
  "timezone": "Europe/London",
  "timezoneOffset": -420
}