Obtain bulk-access credentials from the utility's DataCustodian; for Download My Data (as opposed to Connect My Data), the utility provides a pre-authorized export — confirm whether access is via direct file download from a portal or via a DataCustodian API endpoint with a service account token.
For API-based bulk download, authenticate using the service account OAuth 2.0 token (client_credentials grant against the DataCustodian's authorization endpoint); scope is typically 'FB=4_5_15_16_19_31_32_35_37_38_39_40_51' where FB codes correspond to ESPI function blocks.
Request the bulk data at GET /DataCustodian/espi/1_1/resource/Batch/Subscription/{subscriptionID}/UsagePoint or the DataCustodian-specific bulk export URL; the response is an ESPI Atom feed (XML) containing one or more UsagePoint entries.
Parse the ESPI Atom feed: each UsagePoint entry contains MeterReading children, each of which contains IntervalBlock children with IntervalReading elements; each IntervalReading has a timePeriod (start in Unix epoch, duration in seconds) and a value (in the unit specified by the ReadingType).
Retrieve the ReadingType resource linked from each MeterReading to decode the commodity (electricity, gas), unit (Wh, therm), multiplier (PowerOfTenMultiplier), and accumulation behavior — do not assume all values are in Wh without checking the ReadingType.
Handle pagination: large exports may return a next link in the Atom feed header — follow it iteratively and accumulate all IntervalBlock entries before processing; also handle partial-success responses where some UsagePoints return data and others return a fault entry.
Known gotchas
Download My Data (DMD) is a batch/offline export mechanism; it does not provide real-time or near-real-time data — expect data latency of at least 24 hours for residential smart meter data, and some utilities export only monthly billing intervals in DMD even if 15-minute interval data is available via Connect My Data.
ESPI timestamps are Unix epoch seconds in UTC; many utilities export data in local time without a timezone offset in the timePeriod element, which causes DST-boundary errors — always validate the first and last interval of a day against expected count (e.g., 96 × 15-minute intervals per day) and flag anomalies.
The ESPI Atom feed wraps each resource in an XML Atom entry; extracting data requires handling both the Atom namespace and the ESPI namespace — a common error is stripping the Atom wrapper and losing the self-link needed to fetch the full resource.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp