If you have ever tried to pull a customer's or a building's energy history from a utility, you have probably run into the same fork in the road. One path hands you a file you download by hand, once, from a web portal. The other path sets up an authorized connection that keeps delivering data on its own. Both carry the Green Button name, and they look similar on the surface, but they solve different problems. Choosing the wrong one wastes weeks of manual effort or leaves you without the ongoing feed your product actually needs.
This guide explains the two Green Button access modes, Download My Data and Connect My Data, what each one is good for, what the authorization step really requires, and how Ontario's energy data rules put both in reach across the province. EZGB (Easy Green Button Connector) works with both modes, so the goal here is to help you pick the right one for your use case before you build around it.
What Green Button Is
Green Button is a set of open standards for sharing energy usage information in a consistent format. Both access modes are based on the North American Energy Standards Board (NAESB) Energy Services Provider Interface (ESPI) standard, known as REQ.21. The usage data itself is expressed in a standard XML schema, wrapped in the Atom syndication format, and the automated sharing mode uses the OAuth authorization framework so a customer can grant and revoke access. Because the format is standardized, data from one utility looks structurally like data from another, which is the whole point: you write your ingestion logic once instead of once per utility.
Download My Data: The One-Time Manual Export
Download My Data (DMD) is the access of energy usage information by a customer from their utility through the utility's web portal, resulting in a file that gets downloaded to their computer. The customer logs into their account, selects a date range, and exports a Green Button XML file. That file contains their interval and billing history in the standard format.
DMD is a snapshot. It reflects the data as it stood at the moment of export. If you need last month's numbers again, or if a new bill posts, someone has to log in and export again. There is no automatic refresh. That makes DMD a good fit for occasional, point-in-time needs: a one-off energy audit, a benchmarking exercise, a historical baseline, or a customer who wants to hand you their file directly. It requires no integration between systems, only that the customer can reach their utility portal and knows where the export button is.
The limits show up at scale. Managing dozens or hundreds of accounts through manual exports means chasing logins, tracking which files are current, and stitching files together by hand. The format is consistent, but the collection is entirely human, and human collection does not scale cleanly.
Connect My Data: Authorized Ongoing Sharing
Connect My Data (CMD) lets a customer authorize a third party to access their energy usage information directly from the utility, without further action by the customer each time. Once the customer grants authorization, the utility delivers data to the authorized party through an API on a recurring basis. New reads and new bills flow through automatically. The customer can revoke access at any time, which keeps them in control of who sees their data.
CMD is the right mode when you need data that stays current: an ongoing analytics dashboard, a retail offer engine that watches recent usage, portfolio tracking across many sites, or any product where stale data is a problem. The trade is that CMD requires a real authorization flow. The customer has to explicitly consent, the third party has to be set up to receive the authorized feed, and the connection is scoped to what the customer approved. That setup is more involved than clicking export, but it only happens once per account, and after that the data keeps arriving.
Side by Side
| Aspect | Download My Data | Connect My Data |
|---|---|---|
| Delivery | Manual export by the customer | Authorized API feed from the utility |
| Freshness | Point-in-time snapshot | Ongoing, refreshes automatically |
| Who acts each time | A person logs in and exports | No repeat action after authorization |
| Authorization | Customer's own portal login | Explicit customer consent, revocable |
| Best for | Audits, baselines, one-off analysis | Dashboards, tracking, recurring products |
| Scales to many accounts | Poorly, manual per account | Well, once each account is connected |
| Format | Standard Green Button XML | Standard Green Button XML over API |
What Authorization Actually Requires
For Download My Data, authorization is simply the customer's ability to log into their own utility account. They already have the right to their own data, so the export is theirs to make. When a customer sends you a file, you should keep a record of how you received it and confirm they intended to share it.
For Connect My Data, authorization is a formal, auditable consent. The customer approves a specific third party to receive specific data for a specific purpose, and that grant can be withdrawn. Under the hood this uses OAuth, so the connection is token-based rather than password-based, and revocation cuts off future access cleanly. When you build on CMD, treat the consent record as a first-class asset: know who authorized what, when, and be ready to honor a revocation promptly.
The Ontario Context
Ontario is one of the places where both modes are broadly available, because the province regulated it. Ontario Regulation 633/21, Energy Data, requires electricity and natural gas utilities to offer Green Button Connect My Data and Download My Data access built to the NAESB ESPI standard. The requirement took full effect on November 1, 2023. The Green Button Alliance tested and certified utility platforms across Ontario against the standard, with certified platforms reported for 55 Ontario utilities as of November 2023.
To be clear about what that certification covers: it is the utilities' own platforms that are certified by the Green Button Alliance, not third-party tools that read from them. What the regulation means for you in practice is that across Ontario's utilities you can expect a consistent, standardized way to obtain data in both modes, which is exactly what makes province-wide collection realistic instead of a patchwork of one-off arrangements.
How to Choose
- Choose Download My Data when you need a snapshot, work with a handful of accounts, or a customer will simply hand you a file.
- Choose Connect My Data when data must stay current, when you serve many accounts, or when the feed powers a live product.
- Consider using both: DMD to backfill history quickly at onboarding, then CMD to keep the account current afterward.
- Whichever mode you pick, plan for the format to be standard Green Button XML, so your ingestion works the same across utilities.
For accounts and utilities where Green Button is not available or where you need older bills that predate a connection, PDF bill digitization fills the gap by turning paper and PDF bills into the same structured data. That way your dataset is complete regardless of how any single account's data arrives.
Get Started
EZGB is built to use both Green Button modes together, plus bill digitization for the accounts that need it, and to deliver the result as clean, standardized data by API, CSV, or SFTP. If you are deciding between a one-time export and an ongoing authorized feed, the fastest way to get it right is to talk through your use case with us. Book a walkthrough or start a pilot from the EZGB pricing and signup pages at ezgb.ca, and we will help you set up the right mode for your accounts, in Ontario and beyond.
Sources
- Ontario Regulation 633/21, Energy Data, CanLII: https://www.canlii.org/en/on/laws/regu/o-reg-633-21/latest/o-reg-633-21.html
- Green Button Connect My Data (CMD), Green Button Alliance: https://www.greenbuttonalliance.org/green-button-connect-my-data-cmd
- Green Button Connect My Data overview, greenbuttondata.org: https://www.greenbuttondata.org/cmd.html
- Green Button Alliance announces 55 Ontario utilities' platforms certified: https://www.greenbuttonalliance.org/news/green-button-alliance-announces-55-ontario-based-utilities-platforms-are-now-green-button-certified
- Green Button Standard and NAESB ESPI technical information: https://www.greenbuttonalliance.org/technical-info
Source: canlii.org