pydexcom

Install the pydexcom package using pip to interact with the Dexcom Share service for real-time CGM sensor data.

Prerequisites:

1. Download a compatible Dexcom mobile app (G7, G6, G5, G4, or ONE+).
2. Enable the Share service in the app. Note that the Share service requires at least one follower to be set up to be active.

pip install pydexcom

The GlucoseReading class is used to parse and represent a single glucose reading retrieved from the Dexcom Share API. You initialize it by passing the raw JSON dictionary received from the API.

If the JSON structure is invalid or missing required keys (like Value, Trend, or DT), it will raise an ArgumentError with ArgumentErrorEnum.GLUCOSE_READING_INVALID.

from pydexcom.glucose_reading import GlucoseReading

# Example JSON structure expected from Dexcom Share API
raw_json = {
    "Value": 120,
    "Trend": "Steady",
    "DT": "Date(1672531200000+0000)"
}

reading = GlucoseReading(raw_json)
print(f"Value: {reading.mg_dl} mg/dL")

All errors in pydexcom inherit from the DexcomError base class. You can catch specific error types to handle different failure scenarios (e.g., authentication issues vs. invalid arguments). Each error can optionally be associated with a DexcomErrorEnum value, which provides a machine-readable error string via the .enum property.

from pydexcom.errors import DexcomError, AccountError, ArgumentError

try:
    # Perform Dexcom operations
    pass
except AccountError as e:
    print(f"Authentication failed: {e}")
    if e.enum:
        print(f"Error code: {e.enum.value}")
except ArgumentError as e:
    print(f"Invalid argument provided: {e}")
except DexcomError as e:
    print(f"An unexpected Dexcom error occurred: {e}")

If you only need a single data point, use these convenience methods:

• get_latest_glucose_reading(): Returns the most recent GlucoseReading available within the last 24 hours. Returns None if no reading is found.
• get_current_glucose_reading(): Returns the most recent GlucoseReading available within the last 10 minutes. Returns None if no reading is found.

# Get the single most recent reading
latest = client.get_latest_glucose_reading()
if latest:
    print(f"Latest value: {latest.value}")

# Get the reading from the last 10 minutes
current = client.get_current_glucose_reading()

Retrieve a list of GlucoseReading objects from the Dexcom Share service. The method allows you to limit the scope of the data retrieved using minutes and max_count.

Parameters:

• minutes (int, optional): The number of minutes to look back (range: 1-1440). Defaults to MAX_MINUTES.
• max_count (int, optional): The maximum number of readings to return (range: 1-288). Defaults to MAX_MAX_COUNT.

Behavior: This method automatically handles session expiration. If a SessionError occurs, it attempts to refresh the session ID and retries the request once.

# Get up to 50 readings from the last 60 minutes
readings = client.get_glucose_readings(minutes=60, max_count=50)

for reading in readings:
    print(reading.value)

The primary entry point for the library is the Dexcom class. You use it to authenticate and interact with the Dexcom API. It requires credentials and a Region to specify which Dexcom server to connect to.

from pydexcom import Dexcom, Region

# Example initialization
client = Dexcom(username='your_username', password='your_password', region=Region.US)

The pydexcom library raises specific exceptions to help you diagnose issues with credentials or connectivity:

• AccountError: Raised when authentication fails (e.g., AccountErrorEnum.FAILED_AUTHENTICATION due to invalid password or AccountErrorEnum.MAX_ATTEMPTS due to too many failed attempts).
• SessionError: Raised when the session is invalid or not found (e.g., SessionErrorEnum.INVALID). The client attempts to recover from this automatically during get_glucose_readings().
• ArgumentError: Raised when provided parameters are invalid (e.g., ArgumentErrorEnum.REGION_INVALID, ArgumentErrorEnum.USERNAME_INVALID, or ArgumentErrorEnum.ACCOUNT_ID_INVALID).
• ServerError: Raised when the Dexcom API returns an unexpected error or invalid JSON.

The package provides lookup dictionaries to resolve configuration details based on a Region instance. Use these to programmatically determine the correct API settings:

• DEXCOM_APPLICATION_IDS: Maps a Region to its corresponding Dexcom application ID string.
• DEXCOM_BASE_URLS: Maps a Region to its corresponding Dexcom Share API base URL.

from pydexcom.const import Region, DEXCOM_APPLICATION_IDS, DEXCOM_BASE_URLS

region = Region.JP
app_id = DEXCOM_APPLICATION_IDS[region]
base_url = DEXCOM_BASE_URLS[region]