GET /egvs

Description

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

Scopes & Access

 

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

 

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.