POST /statistics

Description

The /statistics endpoint enables retrieval of a user's summary statistics, including averages, quartiles, and measures of variance. Additionally, time in range based on customizable glycemic ranges and the hypoglycemia risk metric available to users through Dexcom CLARITY® are provided.

Resource

POST /v2/users/self/statistics

Authorization

OAuth 2.0 bearer token; see the Authentication section for details on this workflow.

Query Parameters

These query parameters specify the time window for the requested data; both are required. See the discussion of time in the Endpoint Overview section for more details on how they relate to device information.

Name	Type	Description
`startDate`	DateTime	Beginning of the time window
`endDate`	DateTime	End of the time window

Request Body Example

In order to calculate the statistics based on target ranges, one or more named time ranges and associated target EGV ranges are required. These are passed in the request body in JSON format. The time ranges must cover the entire 24-hour period and not overlap. If the request body is not included or violates these rules, a 400 (Bad Request) error will be returned.

{
  "targetRanges":[
    {
      "name": "day",
      "startTime": "07:00:00",
      "endTime": "20:00:00",
      "egvRanges": [   
        {
          "name": "urgentLow",
          "bound": 55
        },
        {
          "name": "low",
          "bound": 70
        },
        {
          "name": "high",
          "bound": 180
        }
      ]
    },
    {
      "name": "night",
      "startTime": "20:00:00",
      "endTime": "07:00:00",
      "egvRanges": [   
        {
          "name": "urgentLow",
          "bound": 55
        },
        {
          "name": "low",
          "bound": 80
        },
        {
          "name": "high",
          "bound": 200
        }
      ]
    }
  ]
}

Request Body Fields

Name	Type	Description
`name`	String	Reference name for the time window
`startTime`	Time	Beginning of the time window
`endTime`	Time	End of the time window
`egvRanges`	Array	Array containing the minimum and maximum EGV defining the target range

The egvRanges array fields are as follows

Name	Type	Description
`name`	String	Name of for the EGV threshold used for calculations; the following must be included: "urgentLow" "low" "high"
`bound`	Float	The value of the EGV threshold; must follow the rule: "urgentLow" < "low" < "high"

Name

Type

Description

name

String

Name of for the EGV threshold used for calculations; the following must be included:

"urgentLow"
"low"
"high"

bound

Float

The value of the EGV threshold; must follow the rule:

"urgentLow" < "low" < "high"

Request Example

curl
C#
Go
Java
JS
Node.js
PHP
Python
Ruby
Swift

curl -X POST \
  'https://api.dexcom.com/v2/users/self/statistics?startDate=2017-06-01&endDate=2017-06-17' \
  -H 'authorization: Bearer {your_access_token}' \
  -H 'content-type: application/json' \
  -d '{
   "targetRanges":[
      {
         "name":"day",
         "startTime":"07:00:00",
         "endTime":"22:00:00",
         "egvRanges":[   
           {
             "name": "urgentLow",
             "bound": 55
           },
           {
             "name": "low",
             "bound": 70
           },
           {
             "name": "high",
             "bound": 180
           }
         ]
      },
      {
         "name":"night",
         "startTime":"22:00:00",
         "endTime":"07:00:00",
         "egvRanges":[   
           {
             "name": "urgentLow",
             "bound": 55
           },
           {
             "name": "low",
             "bound": 80
           },
           {
             "name": "high",
             "bound": 200
           }
         ]
      }
   ]
}'

using System;
using System.Threading.Tasks;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Newtonsoft.Json.Linq;

public class APIAccess
{
    string _baseUrl = "https://api.dexcom.com";
    string _token = "{your_access_token}";
    private void GetStatistics()
    {
        var client = new HttpClient();
        client.DefaultRequestHeaders.Accept.Clear();
        client.DefaultRequestHeaders.Accept.Add(
        new MediaTypeWithQualityHeaderValue("application/json"));
        client.DefaultRequestHeaders.Add("authorization", "Bearer " + _token);

        var url = _baseUrl + "/v2/users/self/statistics?startDate=2017-06-01&endDate=2017-06-17";
        var jsonString = @"	{
     ""targetRanges"":[
        {
           ""name"":""day"",
           ""startTime"":""07:00:00"",
           ""endTime"":""22:00:00"",
           ""egvRanges"":[   
            {
             ""name"": ""urgentLow"",
             ""bound"": 55
            },
            {
             ""name"": ""low"",
             ""bound"": 70
            },
            {
             ""name"": ""high"",
             ""bound"": 180
            }
          ]
        },
        {
           ""name"":""night"",
           ""startTime"":""22:00:00"",
           ""endTime"":""07:00:00"",
           ""egvRanges"":[   
            {
             ""name"": ""urgentLow"",
             ""bound"": 55
            },
            {
             ""name"": ""low"",
             ""bound"": 80
            },
            {
             ""name"": ""high"",
             ""bound"": 200
            }
          ]
        }
     ]
  }";

    var jsonObject = JObject.Parse(jsonString);


        HttpResponseMessage response = client.PostAsync(url,new StringContent(jsonObject.ToString(),Encoding.UTF8,
                                    "application/json")).Result;
        Console.Write(response.Content.ReadAsStringAsync().Result);
    }
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://api.dexcom.com/v2/users/self/statistics?startDate=2017-06-01&endDate=2017-06-17"

	payload := strings.NewReader("{  \n   \"targetRanges\":[  \n      {  \n         \"name\":\"day\",\n         \"startTime\":\"06:00:00\",\n         \"endTime\":\"22:00:00\",\n         \"egvRanges\":[\n           {\n            \"name\": \"urgentLow\",\n            \"bound\": 55\n          },\n          {\n            \"name\": \"low\",\n            \"bound\": 70\n          },\n          {\n            \"name\": \"high\",\n            \"bound\": 180\n          }\n         ]\n      },\n      {  \n         \"name\":\"night\",\n         \"startTime\":\"22:00:00\",\n         \"endTime\":\"06:00:00\",\n         \"egvRanges\":[\n           {\n            \"name\": \"urgentLow\",\n            \"bound\": 55\n          },\n           {\n            \"name\": \"low\",\n            \"bound\": 80\n          },\n          {\n            \"name\": \"high\",\n            \"bound\": 200\n          }\n         ]\n      }\n   ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("authorization", "Bearer {your_access_token}")
	req.Header.Add("content-type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{  \n   \"targetRanges\":[  \n      {  \n         \"name\":\"day\",\n         \"startTime\":\"06:00:00\",\n         \"endTime\":\"22:00:00\",\n         \"egvRanges\":[\n           {\n            \"name\": \"urgentLow\",\n            \"bound\": 55\n          },\n          {\n            \"name\": \"low\",\n            \"bound\": 70\n          },\n          {\n            \"name\": \"high\",\n            \"bound\": 180\n          }\n         ]\n      },\n      {  \n         \"name\":\"night\",\n         \"startTime\":\"22:00:00\",\n         \"endTime\":\"06:00:00\",\n         \"egvRanges\":[\n           {\n            \"name\": \"urgentLow\",\n            \"bound\": 55\n          },\n           {\n            \"name\": \"low\",\n            \"bound\": 80\n          },\n          {\n            \"name\": \"high\",\n            \"bound\": 200\n          }\n         ]\n      }\n   ]\n}");
Request request = new Request.Builder()
  .url("https://api.dexcom.com/v2/users/self/statistics?startDate=2017-06-01&endDate=2017-06-17")
  .post(body)
  .addHeader("authorization", "Bearer {your_access_token}")
  .addHeader("content-type", "application/json")
  .build();

Response response = client.newCall(request).execute();

var data = JSON.stringify({
  "targetRanges": [
    {
      "name": "day",
      "startTime": "06:00:00",
      "endTime": "22:00:00",
      "egvRanges": [
        {
          "name": "urgentLow",
          "bound": 55
        },
        {
          "name": "low",
          "bound": 70
        },
        {
          "name": "high",
          "bound": 180
        }
      ]
    },
    {
      "name": "night",
      "startTime": "22:00:00",
      "endTime": "06:00:00",
      "egvRanges": [
        {
          "name": "urgentLow",
          "bound": 55
        },
        {
          "name": "low",
          "bound": 80
        },
        {
          "name": "high",
          "bound": 200
        }
      ]
    }
  ]
});

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.dexcom.com/v2/users/self/statistics?startDate=2017-06-01&endDate=2017-06-17");
xhr.setRequestHeader("authorization", "Bearer {your_access_token}");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);

var http = require("https");

var options = {
  "method": "POST",
  "hostname": "api.dexcom.com",
  "port": null,
  "path": "/v2/users/self/statistics?startDate=2017-06-01&endDate=2017-06-17",
  "headers": {
    "authorization": "Bearer {your_access_token}",
    "content-type": "application/json"
    }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({ targetRanges: 
   [ { name: 'day',
       startTime: '06:00:00',
       endTime: '22:00:00',
       egvRanges: 
        [ { name: 'urgentLow', bound: 55 },
          { name: 'low', bound: 70 },
          { name: 'high', bound: 180 } ] },
     { name: 'night',
       startTime: '22:00:00',
       endTime: '06:00:00',
       egvRanges: 
        [ { name: 'urgentLow', bound: 55 },
          { name: 'low', bound: 80 },
          { name: 'high', bound: 200 } ] } ] }));
req.end();

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.dexcom.com/v2/users/self/statistics?startDate=2017-06-01&endDate=2017-06-17",
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{  \n   \"targetRanges\":[  \n      {  \n         \"name\":\"day\",\n         \"startTime\":\"06:00:00\",\n         \"endTime\":\"22:00:00\",\n         \"egvRanges\":[\n           {\n            \"name\": \"urgentLow\",\n            \"bound\": 55\n          },\n          {\n            \"name\": \"low\",\n            \"bound\": 70\n          },\n          {\n            \"name\": \"high\",\n            \"bound\": 180\n          }\n         ]\n      },\n      {  \n         \"name\":\"night\",\n         \"startTime\":\"22:00:00\",\n         \"endTime\":\"06:00:00\",\n         \"egvRanges\":[\n           {\n            \"name\": \"urgentLow\",\n            \"bound\": 55\n          },\n           {\n            \"name\": \"low\",\n            \"bound\": 80\n          },\n          {\n            \"name\": \"high\",\n            \"bound\": 200\n          }\n         ]\n      }\n   ]\n}",
  CURLOPT_HTTPHEADER => array(
    "content-type: application/json",
    "authorization: Bearer {your_access_token}"
  ),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

import http.client

conn = http.client.HTTPSConnection("api.dexcom.com")

payload = "{  \n   \"targetRanges\":[  \n      {  \n         \"name\":\"day\",\n         \"startTime\":\"06:00:00\",\n         \"endTime\":\"22:00:00\",\n         \"egvRanges\":[\n           {\n            \"name\": \"urgentLow\",\n            \"bound\": 55\n          },\n          {\n            \"name\": \"low\",\n            \"bound\": 70\n          },\n          {\n            \"name\": \"high\",\n            \"bound\": 180\n          }\n         ]\n      },\n      {  \n         \"name\":\"night\",\n         \"startTime\":\"22:00:00\",\n         \"endTime\":\"06:00:00\",\n         \"egvRanges\":[\n           {\n            \"name\": \"urgentLow\",\n            \"bound\": 55\n          },\n           {\n            \"name\": \"low\",\n            \"bound\": 80\n          },\n          {\n            \"name\": \"high\",\n            \"bound\": 200\n          }\n         ]\n      }\n   ]\n}"

headers = {
    'authorization': "Bearer {your_access_token}",
    'content-type': "application/json"
    }

conn.request("POST", "/v2/users/self/statistics?startDate=2017-06-01&endDate=2017-06-17", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.dexcom.com/v2/users/self/statistics?startDate=2017-06-01&endDate=2017-06-17")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Bearer {your_access_token}'
request["content-type"] = 'application/json'
request.body = "{  \n   \"targetRanges\":[  \n      {  \n         \"name\":\"day\",\n         \"startTime\":\"06:00:00\",\n         \"endTime\":\"22:00:00\",\n         \"egvRanges\":[\n           {\n            \"name\": \"urgentLow\",\n            \"bound\": 55\n          },\n          {\n            \"name\": \"low\",\n            \"bound\": 70\n          },\n          {\n            \"name\": \"high\",\n            \"bound\": 180\n          }\n         ]\n      },\n      {  \n         \"name\":\"night\",\n         \"startTime\":\"22:00:00\",\n         \"endTime\":\"06:00:00\",\n         \"egvRanges\":[\n           {\n            \"name\": \"urgentLow\",\n            \"bound\": 55\n          },\n           {\n            \"name\": \"low\",\n            \"bound\": 80\n          },\n          {\n            \"name\": \"high\",\n            \"bound\": 200\n          }\n         ]\n      }\n   ]\n}"

response = http.request(request)
puts response.read_body

import Foundation

let headers = [
  "authorization": "Bearer {your_access_token}",
  "content-type": "application/json"
]
let parameters = ["targetRanges": [
    [
      "name": "day",
      "startTime": "06:00:00",
      "endTime": "22:00:00",
      "egvRanges": [
        [
          "name": "urgentLow",
          "bound": 55
        ],
        [
          "name": "low",
          "bound": 70
        ],
        [
          "name": "high",
          "bound": 180
        ]
      ]
    ],
    [
      "name": "night",
      "startTime": "22:00:00",
      "endTime": "06:00:00",
      "egvRanges": [
        [
          "name": "urgentLow",
          "bound": 55
        ],
        [
          "name": "low",
          "bound": 80
        ],
        [
          "name": "high",
          "bound": 200
        ]
      ]
    ]
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.dexcom.com/v2/users/self/statistics?startDate=2017-06-01&endDate=2017-06-17")! as URL,
      cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

Response Example

{
  "hypoglycemiaRisk": "minimal",
  "min": 44,
  "max": 261,
  "mean": 133.64806445274132,
  "median": 124,
  "variance": 1447.8893070219756,
  "stdDev": 38.05114067964291,
  "sum": 680135,
  "q1": 103,
  "q2": 124,
  "q3": 158,
  "utilizationPercent": 96.00831928771177,
  "meanDailyCalibrations": 1.9809075622325305,
  "nDays": 19,
  "nValues": 5089,
  "nUrgentLow": 33,
  "nBelowRange": 10,
  "nWithinRange": 4417,
  "nAboveRange": 629,
  "percentUrgentLow": 0.6484574572607585,
  "percentBelowRange": 0.19650225977598745,
  "percentWithinRange": 86.79504814305365,
  "percentAboveRange": 12.35999213990961
}

Response Fields

Name	Type	Description
`hypoglycemiaRisk`	String	Risk for the patient to have future hypoglycemic events; see additional notes below (nullable)
`min`	Float	Minimum of all EGV data for given date range
`max`	Float	Maximum of all EGV data for given date range
`mean`	Float	Mean of all EGV data for given date range
`median`	Float	Median of all EGV data for given date range
`variance`	Float	Statistical variance of glucose level for given date range
`stdDev`	Float	Standard deviation of all EGV data for given date range
`sum`	Float	Sum of all EGV data for given date range
`q1`	Float	First quartile of all EGV data for given date range
`q2`	Float	Second quartile of all EGV data for given date range
`q3`	Float	Third quartile of all EGV data for given date range
`utilizationPercent`	Float	Percent CGM sensor was utilized for given date range
`meanDailyCalibrations`	Float	Mean number of calibrations per day for given date range
`nDays`	Integer	Number of calendar days contributing data to the statistics calculations; only days containing EGV data are included in this count
`nValues`	Integer	Total number of EGV observations for given date range
`nUrgentLow`	Integer	Number of EGV observations below urgentLow bound (exclusive) specified in `egvRanges` array
`nBelowRange`	Integer	Number of EGV observations below low bound (exclusive) and above urgentLow bound (inclusive) specified in `egvRanges` array
`nWithinRange`	Integer	Number of EGV observations between high bound (inclusive) and above low bound (inclusive) specified in `egvRanges` array
`nAboveRange`	Integer	Number of EGV observations above high bound (exclusive) specified in `egvRanges` array
`percentUrgentLow`	Float	Percentage of EGV observations below urgentLow bound (exclusive) specified in `egvRanges` array
`percentBelowRange`	Float	Percentage of EGV observations below low bound (exclusive) and above urgentLow bound (inclusive) specified in `egvRanges` array
`percentWithinRange`	Float	Percentage of EGV observations between high bound (inclusive) and above low bound (inclusive) specified in `egvRanges` array
`percentAboveRange`	Float	Percentage of EGV observations above high bound (exclusive) specified in `egvRanges` array

Notes

Statistics are calculated using the value field from the /egvs endpoints. See the GET /egvs page for more details.

Additional notes for hypoglycemiaRisk:

This calculation estimates the risk for severe hypoglycemia. It is based on a combination of the number of times glucose was low, the magnitude of the low glucose and for how long there was low glucose.

Experiencing frequent lower measured glucose values for short durations has more impact than minimal hypoglycemia for longer periods but with less frequency. Having more frequent lows for longer durations and at lower glucose levels carries a high risk for severe hypoglycemia. The hypoglycemia risk complements the patient’s A1C measurements. Patients can have low or high A1C and still be at low, medium or high hypoglycemia risk. The impact of hypoglycemic risk on patients and diabetes management should be reviewed by a healthcare professional.

The hypoglycemia risk estimation is calculated from a minimum amount of days with a minimum duration of CGM wear time as follows:

When number of days in date range is less than 20 days, at least 12 days in date range with utilizationPercent greater than or equal to 66%.
When number of days in date range is greater than or equal to 20 days, at least 60% of total days in date range with utilizationPercent greater than or equal to 66%.

Clinical References:

Kovatchev, B, et al. Algorithmic Evaluation of Metabolic Control and Risk of Severe Hypoglycemia in Type 1 and Type 2 Diabetes Using Self-Monitoring Blood Glucose Data. Diabetes Technology and Therapeutics, 5(5): 817-828, 2003. PubMed Link

Clarke W, Kovatchev B. Statistical Tools to Analyze Continuous Glucose Monitor Data. Diabetes Technology & Therapeutics. 2009; 11(Suppl 1): S-45-S-54. doi:10.1089/dia.2008.0138. PubMed Link

Hypoglycemia Risk corresponds to the risk categories from these studies:

"minimal" corresponds to Minimal Risk in the studies
"low" corresponds to Low Risk in the studies
"moderate" corresponds to Moderate Risk in the studies
"high" corresponds to High Risk in the studies

The documentation for an earlier version of this endpoint is available here.