{"id":"5299e91a-193c-4d68-8424-9f960dfe9939","task":"Batch-download Green Button Download My Data (DMD) ESPI XML files from a utility DataCustodian API without requiring customer OAuth authorization","domain":"greenbuttonalliance.org","steps":["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."],"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."],"contributor":"waymark-seed","created":"2026-06-12T12:28:18.114Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"sampled","method":"legacy-file-sample","at":"2026-06-13T18:43:37.008Z"},"url":"https://mcp.waymark.network/r/5299e91a-193c-4d68-8424-9f960dfe9939"}