GET /egvs

Description

The /egvs endpoint enables retrieval of a user's estimated glucose value (EGV) data, including trend and status information.

Resource

GET /v2/users/self/egvs

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 Example

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

curl -X GET \
  'https://api.dexcom.com/v2/users/self/egvs?startDate=2017-06-16T15:30:00&endDate=2017-06-16T15:45:00' \
  -H 'authorization: Bearer {your_access_token}'

using System;
using System.Threading.Tasks;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

public class APIAccess
{
    string _baseUrl = "https://api.dexcom.com";
    string _token = "{your_access_token}";
    private void GetEGV()
    {
        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/egvs?startDate=2017-06-16T15:30:00&endDate=2017-06-16T15:45:00";
        HttpResponseMessage response = client.GetAsync(url).Result;
        Console.Write(response.Content.ReadAsStringAsync().Result);
    }
}

package main

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

func main() {

	url := "https://api.dexcom.com/v2/users/self/egvs?startDate=2017-06-16T15:30:00&endDate=2017-06-16T15:45:00"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("authorization", "Bearer {your_access_token}")

	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();

Request request = new Request.Builder()
  .url("https://api.dexcom.com/v2/users/self/egvs?startDate=2017-06-16T15:30:00&endDate=2017-06-16T15:45:00")
  .get()
  .addHeader("authorization", "Bearer {your_access_token}")
  .build();

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

var data = null;

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

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

xhr.open("GET", "https://api.dexcom.com/v2/users/self/egvs?startDate=2017-06-16T15:30:00&endDate=2017-06-16T15:45:00");
xhr.setRequestHeader("authorization", "Bearer {your_access_token}");

xhr.send(data);

var http = require("https");

var options = {
  "method": "GET",
  "hostname": "api.dexcom.com",
  "port": null,
  "path": "/v2/users/self/egvs?startDate=2017-06-16T15:30:00&endDate=2017-06-16T15:45:00",
  "headers": {
    "authorization": "Bearer {your_access_token}",
    }
};

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.end();

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.dexcom.com/v2/users/self/egvs?startDate=2017-06-16T15:30:00&endDate=2017-06-16T15:45:00",
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "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")

headers = {
    'authorization': "Bearer {your_access_token}"
    }

conn.request("GET", "/v2/users/self/egvs?startDate=2017-06-16T15:30:00&endDate=2017-06-16T15:45:00", headers=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/egvs?startDate=2017-06-16T15:30:00&endDate=2017-06-16T15:45:00")

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

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Bearer {your_access_token}'

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

import Foundation

let headers = [
  "authorization": "Bearer {your_access_token}"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.dexcom.com/v2/users/self/egvs?startDate=2017-06-16T15:30:00&endDate=2017-06-16T15:45:00")! as URL,
      cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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)
    if (data != nil){
                let responseData:String! = String(data: data!, encoding: String.Encoding.utf8)
                print(responseData)
            }
  }
})

dataTask.resume()

Response Example

{
  "unit": "mg/dL",
  "rateUnit": "mg/dL/min",
  "egvs": [
    {
      "systemTime": "2018-02-06T09:12:35",
      "displayTime": "2018-02-06T01:12:35",
      "value": 122,
      "realtimeValue": 121,
      "smoothedValue": 122,
      "status": null,
      "trend": "flat",
      "trendRate": -0.5
    },
    {
      "systemTime": "2018-02-06T09:07:35",
      "displayTime": "2018-02-06T01:07:35",
      "value": 123,
      "realtimeValue": 124,
      "smoothedValue": 123,
      "status": null,
      "trend": "flat",
      "trendRate": -0.5
    },
    {
      "systemTime": "2018-02-06T09:02:35",
      "displayTime": "2018-02-06T01:02:35",
      "value": 125,
      "realtimeValue": 125,
      "smoothedValue": null,
      "status": null,
      "trend": "flat",
      "trendRate": -0.7
    }
  ]
}

Response Fields

Name	Type	Description	Enumeration
`unit`	String	Unit of measurement for `value`	"mg/dL" "mmol/L"
`rateUnit`	String	Unit of measurement for `trendRate`	"mg/dL/min" "mmol/L/min"
`egvs`	Array	Array of estimated glucose values

The egvs array fields are as follows

Name	Type	Description	Enumeration
`systemTime`	DateTime	Time according to the system clock at which observation was made; nominally UTC
`displayTime`	DateTime	Time displayed on the receiving device when the observation was made
`value`	Float	Estimated glucose value For G4 and G5 devices, equal to `realtimeValue` For G6 devices, equal to `smoothedValue` if present, otherwise equal to `realtimeValue` See the Notes section below for more details	39 indicates that the value was calculated and it was less than 40; the value 39 is used in calculations but is not explicitly displayed to end users 40 to 400 this is the measuring range of the Dexcom CGM 401 indicates that the value was calculated and it was greater than 400; the value 401 is used in calculations but is not explicitly displayed to end users
`realtimeValue`	Float	Estimated glucose value presented on receiving device in realtime See the Notes section below for more details	See enumeration for `value` above
`smoothedValue`	Float	Estimated glucose value presented retrospectively on receiving device after smoothing; G6 devices only See the Notes section below for more details (nullable)	See enumeration for `value` above
`status`	String	Explanation of EGV record; used when the `value` field is outside the measuring range (nullable)	"high" indicates a glucose value of more than 400 "low" indicates a glucose value of less than 40
`trend`	String	General trend of EGV value movement; corresponds to `trendRate` field (nullable)	"doubleUp" +3 ≤ `trendRate` ≤ +8 "singleUp" +2 ≤ `trendRate` < +3 "fortyFiveUp" +1 ≤ `trendRate` < +2 "flat" -1 < `trendRate` < +1 "fortyFiveDown" -2 < `trendRate` ≤ -1 "singleDown" -3 < `trendRate` ≤ -2 "doubleDown" -8 < `trendRate` ≤ -3 "none" no arrow (blank) "notComputable" the algorithm decides that it is not reasonable to compute trend arrow "rateOutOfRange" the computed filtered rate is not within the range for assigning the arrows
`trendRate`	Float	Rate at which glucose value is moving up or down (nullable)

Notes

The G6 generation of sensors and transmitters introduced the concept of retrospective data smoothing to estimated glucose values. This smoothing incorporates three consecutive EGVs to produce a clearer, more readable trace for the user. Because three consecutive EGVs are not always available—for example, at the beginning or end of a sensor session—some EGVs cannot be smoothed. In these cases, the realtimeValue will be populated with a number, but the smoothedValue will be null.

The rules for the value field are as follows:

If smoothedValue is not null, value is equal to smoothedValue
If smoothedValue is null, value is equal to realtimeValue

The recommended method for consuming the /egvs endpoint is to use the value field. This will match what the Dexcom CGM user can see retrospectively on the display devices as well as in CLARITY.

Due to how data is uploaded and processed, some records that initially have a null smoothedValue may later have this field populated, with the value field also changing per the rules above.

For EGVs generated by G4 and G5 devices, the smoothedValue field will always return null as these systems do not have retrospective data smoothing.

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