The first time you open a Green Button file, it rarely looks like the tidy table you expected. You get an XML document full of Atom feeds, nested entries, cross references by URL, and numeric readings that only make sense after you apply a multiplier and a unit code. For developers and energy consultants who just want kilowatt-hours by hour, the format can feel like more work than it should be. This article walks through what is actually inside a Green Button file and why it is built the way it is.
Understanding the structure pays off, because the same model shows up across every certified utility. Once you can read one Green Button feed, you can read them all, whether it arrives as a manual Download My Data export or through a Connect My Data API.
What Green Button actually is
Green Button is a common name for the North American Energy Standards Board (NAESB) Retail Energy Quadrant Book 21, known as REQ.21, the Energy Services Provider Interface (ESPI). ESPI defines both a data model for energy usage and a set of business practices for exchanging that data between a utility (the Data Custodian) and an authorized third party. The Green Button Alliance maintains developer resources and runs the testing and certification program that utilities use to confirm their implementations match the standard.
The standard has continued to evolve. NAESB released version 4.0 of the ESPI standard in December 2023, building on the earlier 3.x versions that many production systems still use. When you build a parser, it helps to know which version a given utility publishes, because element availability and some conventions differ between releases.
Atom is the wrapper, not the data
Green Button does not invent its own container format. It reuses the Atom Syndication Format, the same XML syndication standard originally designed for web feeds. A Green Button document is an Atom `<feed>` holding one or more `<entry>` elements, and each ESPI resource lives inside the content of an entry. A single API call may return just one entry as the document root to reduce overhead.
The reason for choosing Atom is the `<link>` element. Every entry carries links with `rel` attributes such as `self`, `up`, and `related` that connect resources to one another using absolute URLs as identifiers. This linking mechanism removes redundancy: a UsagePoint can reference a shared LocalTimeParameters entry that holds daylight saving rules once, instead of repeating time zone details inside every reading. When you parse, you are really walking a small graph of entries joined by their links.
The ESPI resource model
Inside the Atom wrapper, the ESPI namespace defines the energy data itself. The core resources form a hierarchy that you will meet in almost every feed:
- UsagePoint: a single metered point of service, such as one electricity meter or one gas meter. Portfolios with many meters produce many UsagePoints.
- MeterReading: a container that ties a UsagePoint to a specific ReadingType and to the interval data collected for it.
- ReadingType: the metadata that tells you how to interpret the numbers, including the unit of measure, the power of ten multiplier, the commodity, the flow direction, and the default interval length.
- IntervalBlock: a block of readings covering a period, for example one day or one billing period.
- IntervalReading: a single measured value with a start time and a duration, which is the actual number you plot.
The MeterReading is characterized by its ReadingType and quantified by one or more IntervalReadings that contain the measurement values, timestamps, and optionally cost. Keeping the ReadingType separate from the readings is deliberate. It lets a large block of interval values stay compact, because the units and scaling are defined once rather than repeated on every row.
Reading the numbers correctly
A common early mistake is to treat the raw `value` inside an IntervalReading as a finished figure. It is not. Each value is an integer that you scale using the `powerOfTenMultiplier` and interpret using the unit of measure code from the ReadingType. A value expressed in watt-hours with a multiplier of three, for example, represents kilowatt-hours. Skipping this step is the most frequent cause of readings that are off by orders of magnitude.
Time is the other place to slow down. IntervalReading timestamps are typically expressed as epoch seconds, and the LocalTimeParameters resource carries the time zone and daylight saving rules you need to convert them to local wall clock time. If you ignore the time parameters, hourly data can drift by an hour twice a year and quietly corrupt any day over day comparison.
The same resource model covers more than one commodity. Electricity, natural gas, and other measured services all fit the UsagePoint to IntervalReading structure, with the ReadingType naming the commodity, the unit of measure, and the flow direction so a parser can tell gas volume from electricity energy. Granularity differs in practice: electricity often arrives at short intervals such as 15 or 60 minutes, while gas is frequently reported at coarser, often monthly, granularity. Reading the interval length from the ReadingType, rather than assuming it, keeps your ingestion correct whatever the commodity.
Validating against the schema
ESPI ships with XML Schema Definition (XSD) files that describe the allowed elements and namespaces, including the Atom namespace, the ESPI energy namespace, and the retail customer namespace. Validating an incoming document against the published ESPI schema catches structural problems early, before your downstream code tries to read fields that are missing or in the wrong place. It is a cheap first gate in any ingestion pipeline.
How EZGB handles the format for you
EZGB (Easy Green Button Connector) is built to absorb these details so your team does not have to hand write a parser for every utility. It collects Green Button data through both Download My Data and Connect My Data, walks the Atom link graph, applies the ReadingType multiplier and unit codes, and resolves timestamps against the correct time parameters. The result is standardized interval and billing data you can pull through an API or an ongoing feed, across many utilities, in one consistent shape. When a bill only exists as a PDF, EZGB can also turn it into structured data so your dataset stays complete.
The Green Button format looks intimidating on first contact, but it is logical once you separate the Atom wrapper from the ESPI resources and remember that the readings are scaled integers described by a shared ReadingType. Learn that shape once and every certified utility feed becomes readable. From there, the interesting work of analysis can begin.
Source: greenbuttonalliance.org