dexcomshare

README

dexcom-share

dexcom-share is a Go client for the undocumented Dexcom Share API. Use it to read near-realtime glucose data uploaded from a Dexcom continuous glucose monitor.

The Share API is not public, not documented, and not supported by Dexcom. It can change or disappear without notice. You have been warned.

Install

go get github.com/mntndev/dexcom-share

Usage

package main

import (
	"context"
	"fmt"
	"log"

	dexcomshare "github.com/mntndev/dexcom-share"
)

func main() {
	ctx := context.Background()

	client, err := dexcomshare.NewClient(ctx, "username", "password")
	if err != nil {
		log.Fatal(err)
	}

	// The ten most recent readings from the last hour.
	entries, err := client.ReadGlucose(ctx, 60, 10)
	if err != nil {
		log.Fatal(err)
	}

	for _, entry := range entries {
		fmt.Printf("%s %d mg/dL %s %s\n",
			entry.WT.Local().Format("15:04"),
			entry.Value,
			entry.Trend.Arrow(),
			entry.Trend.Description(),
		)
	}
}

ReadGlucose takes a lookback window in minutes (1–1440) and a maximum number of entries (1–288), and returns the most recent readings first.

Readings

GlucoseEntry.Value is in mg/dL; call MmolL for mmol/L. Trend is a typed string with Arrow, Description, and Known helpers. DT, WT, and ST are parsed timestamps that embed time.Time, so the usual time methods work directly. DT carries the offset the device reported; WT and ST are UTC.

Accounts outside the United States

Dexcom serves non-US accounts from a different host:

client, err := dexcomshare.NewClient(ctx, "username", "password",
	dexcomshare.WithBaseURL(dexcomshare.BaseURLOutsideUS),
)

Use WithHTTPClient to supply your own *http.Client for timeouts, proxies, or instrumentation.

Errors

Failures wrap a sentinel you can match with errors.Is — ErrAuthenticationFailed, ErrLoginFailed, ErrReadGlucoseFailed, ErrInvalidMinutes, ErrInvalidMaxCount — and, when the API reported a reason, an *APIError you can reach with errors.As:

entries, err := client.ReadGlucose(ctx, 60, 10)

var apiErr *dexcomshare.APIError
if errors.As(err, &apiErr) && apiErr.Code == "SessionIdNotFound" {
	// The session expired; build a new client.
}

Sessions do not refresh themselves. When one expires, create a new client.

Development

go test -race -coverprofile=coverage.out ./...

Tests run against httptest stubs plus one session recorded from the real API with go-vcr (testdata/TestRecordedSession.yaml). No credentials are needed, and the recorded cassette has them redacted.

License

MIT

Documentation

Overview

Package dexcomshare provides a client for the Dexcom Share API, which serves near-realtime glucose readings uploaded from a Dexcom continuous glucose monitor.

The Share API is undocumented and unsupported by Dexcom. It can change or disappear without notice. You have been warned.

Accounts registered outside the United States live on a separate host; pass WithBaseURL with BaseURLOutsideUS for those.

Example

This example is compiled but not run, since it talks to the real Share API.

package main

import (
	"context"
	"fmt"
	"log"

	dexcomshare "github.com/mntndev/dexcom-share"
)

func main() {
	ctx := context.Background()

	client, err := dexcomshare.NewClient(ctx, "username", "password")
	if err != nil {
		log.Fatal(err)
	}

	// The ten most recent readings from the last hour.
	entries, err := client.ReadGlucose(ctx, 60, 10)
	if err != nil {
		log.Fatal(err)
	}

	for _, entry := range entries {
		fmt.Printf("%s %d mg/dL %s %s\n",
			entry.WT.Local().Format("15:04"),
			entry.Value,
			entry.Trend.Arrow(),
			entry.Trend.Description(),
		)
	}
}

Index

• Constants
• Variables
• type APIError
  • func (e *APIError) Error() string
• type Client
  • func NewClient(ctx context.Context, username, password string, options ...Option) (*Client, error)
  • func (c *Client) ReadGlucose(ctx context.Context, minutes, maxCount int) ([]GlucoseEntry, error)
• type GlucoseEntry
  • func (e GlucoseEntry) MmolL() float64
• type Option
  • func WithBaseURL(baseURL string) Option
  • func WithHTTPClient(httpClient *http.Client) Option
• type Time
  • func (t Time) MarshalJSON() ([]byte, error)
  • func (t *Time) UnmarshalJSON(data []byte) error
• type Trend
  • func (t Trend) Arrow() string
  • func (t Trend) Description() string
  • func (t Trend) Known() bool

Examples

• Package
• WithBaseURL

Constants

const (
	// BaseURLUS serves accounts registered inside the United States. It is the default.
	BaseURLUS = "https://share2.dexcom.com/ShareWebServices/Services"
	// BaseURLOutsideUS serves accounts registered outside the United States.
	BaseURLOutsideUS = "https://shareous1.dexcom.com/ShareWebServices/Services"
)

Variables

var (
	// ErrAuthenticationFailed is returned when an account cannot be authenticated.
	ErrAuthenticationFailed = errors.New("dexcomshare: authentication failed")
	// ErrLoginFailed is returned when a session cannot be established.
	ErrLoginFailed = errors.New("dexcomshare: login failed")
	// ErrReadGlucoseFailed is returned when glucose readings cannot be retrieved.
	ErrReadGlucoseFailed = errors.New("dexcomshare: read glucose failed")
	// ErrInvalidMinutes is returned when minutes is outside the range the API accepts.
	ErrInvalidMinutes = errors.New("dexcomshare: minutes must be between 1 and 1440")
	// ErrInvalidMaxCount is returned when maxCount is outside the range the API accepts.
	ErrInvalidMaxCount = errors.New("dexcomshare: max count must be between 1 and 288")
)

Types

type APIError

type APIError struct {
	StatusCode int
	Code       string
	Message    string
}

APIError describes an unsuccessful response from the Share API. The API reports failures as a JSON body containing a Code and a Message.

func (*APIError) Error

func (e *APIError) Error() string

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a client for the Dexcom Share API.

func NewClient

func NewClient(ctx context.Context, username, password string, options ...Option) (*Client, error)

NewClient creates a new Dexcom Share client and establishes a session.

func (*Client) ReadGlucose

func (c *Client) ReadGlucose(ctx context.Context, minutes, maxCount int) ([]GlucoseEntry, error)

ReadGlucose returns up to maxCount glucose entries recorded within the last minutes minutes, most recent first. minutes must be between 1 and 1440, and maxCount between 1 and 288.

type GlucoseEntry

type GlucoseEntry struct {
	Value int   `json:"Value"` // Value is the glucose reading in mg/dL.
	Trend Trend `json:"Trend"`
	DT    Time  `json:"DT"` // DT is the display time, in the device's own UTC offset.
	WT    Time  `json:"WT"` // WT is the wall time reported by the transmitter.
	ST    Time  `json:"ST"` // ST is the system time reported by the transmitter.
}

GlucoseEntry is a single glucose reading.

func (GlucoseEntry) MmolL

func (e GlucoseEntry) MmolL() float64

MmolL returns the reading in mmol/L, rounded to one decimal place the way the Dexcom apps display it.

type Option

type Option func(*Client)

Option configures a Client.

func WithBaseURL

func WithBaseURL(baseURL string) Option

WithBaseURL configures a Client to talk to a different Share host, such as BaseURLOutsideUS.

Example

Accounts registered outside the United States live on a different host.

package main

import (
	"context"
	"log"

	dexcomshare "github.com/mntndev/dexcom-share"
)

func main() {
	_, err := dexcomshare.NewClient(
		context.Background(),
		"username",
		"password",
		dexcomshare.WithBaseURL(dexcomshare.BaseURLOutsideUS),
	)
	if err != nil {
		log.Fatal(err)
	}
}

func WithHTTPClient

func WithHTTPClient(httpClient *http.Client) Option

WithHTTPClient configures a Client with a custom http.Client.

type Time

type Time struct {
	time.Time
}

Time is a Share API timestamp. The API reports timestamps in an ASP.NET flavored format holding Unix milliseconds and an optional UTC offset, such as Date(1680591428000) or Date(1680591428000-0700).

It embeds time.Time, so the usual time methods are available directly.

func (Time) MarshalJSON

func (t Time) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler, emitting the format the Share API uses.

func (*Time) UnmarshalJSON

func (t *Time) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type Trend

type Trend string

Trend describes the direction a glucose reading is heading. The Share API reports it as a string; values this package does not recognize are preserved as-is rather than discarded.

const (
	TrendNone           Trend = "None"
	TrendDoubleUp       Trend = "DoubleUp"
	TrendSingleUp       Trend = "SingleUp"
	TrendFortyFiveUp    Trend = "FortyFiveUp"
	TrendFlat           Trend = "Flat"
	TrendFortyFiveDown  Trend = "FortyFiveDown"
	TrendSingleDown     Trend = "SingleDown"
	TrendDoubleDown     Trend = "DoubleDown"
	TrendNotComputable  Trend = "NotComputable"
	TrendRateOutOfRange Trend = "RateOutOfRange"
)

Trends reported by the Share API.

func (Trend) Arrow

func (t Trend) Arrow() string

Arrow returns the arrow the Dexcom apps display for the trend. It is empty for TrendNone and for unrecognized trends.

func (Trend) Description

func (t Trend) Description() string

Description returns a human readable description of the trend, or "unknown" for an unrecognized trend.

func (Trend) Known

func (t Trend) Known() bool

Known reports whether the trend is one this package recognizes.