Green Button Developer

From Open Energy Information


Green Button uses consensus-based standards that have been developed in collaboration with the Smart Grid Interoperability Panel. This page outlines Green Button standards, technical specifications, and development resources for software developers useful for creating green button applications.

Green Button Standards & Specifications

  • OpenADE: Requirements specification for secure delivery of historical and ongoing usage information to 3rd Party
  • PAP 10: Seed standard that defines a common energy usage information data model, for use across and interoperability between multiple standards
  • NAESB ESPI: Standard that satisfies the requirements laid out in OpenADE and incorporates the data model from NAESB PAP 10 Energy Usage Information
  • Green Button: File format subset of ESPI provides usage information to the consumer’s via Web site

Energy Services Provider Interface (ESPI)

The purpose of the NAESB Energy Services Provider Interface (ESPI) standard (REQ.21) is to create a standardized process and interface for the exchange of a retail customer’s energy usage information between their designated data custodian (i.e. distribution company) and an authorized third party service provider. Providing a consistent method for the authorization of third party access to retail consumer’s usage information and a standardized interface for the exchange of the that information will support the development of innovative products that will allow consumers to better understand their energy usage and to make more economical decisions about their usage. The NAESB ESPI standard provides model business practices, use cases, models and an XML schema that describe the mechanisms by which the orchestrated exchange of energy usage information may be enabled. The NAESB standards development effort was conducted with the support of the National Institute of Standards & Technology and the Smart Grid Interoperability Panel and serves as an extension of the NAESB Energy Usage Information Model developed at the request of NIST and the SGIP.

Accessing the Standard

NAESB offers several options for access to the ESPI standard, click here for details.


The Energy Services Provider Interface (ESPI) provides a way for Energy Usage Information (EUI) to be shared, in a controlled manner, between participants in the energy services markets.

The OpenESPI project provides support for the development of deployable ESPI components that will help to rapidly and consistently engage the community with this exciting and enabling technology.

Project Description

The OpenESPI implementation consists primarily of two instances -- a Data Custodian and a Third Party. Each implements the corresponding roles of the ESPI standard. These components can be utilized as the starting point for formal implementation based on the standard. Additionally, they can be used to test implementations against a working reference. It is designed that the DataCustodian and ThirdParty can be utilized by a test harness to orchestrate conformance tests which include proper and improper behavior to verify the robustness of an implementation.

Each component exposes four interfaces:

  1. Authentication - used for implementing the OAuth authentication mechanism
  2. Transfer - used for exchanging Energy Usage Information (EUI) according to the ESPI data model
  3. Back End - used to simulate a back-end repository of usage information primarily in the Data Custodian
  4. Test Orchestration - a test interface that can direct the code to implement scripted good and bad behavior designed to test the interface.

It is the stated goal of this development to address specifically the implementation and conformance testing requirements of the UCAIug OpenADE Task Force. These requirements are linked to this development and constrain the releases to perform to them. The OpenADE task force will provide to this project a document(s) describing the “Implementation Agreement and Certification and Test Suite for ESPI and Green Button” that will circumscribe the behavior and capabilities of this software.

The Open Energy Services Provider Interface (ESPI) Repository on Github

The Open Energy Services Provider Interface (ESPI) Repository

ESPI Toolkit

By downloading these standards, you agree to the following terms of use for access to NAESB standards for evaluation purposes. Should you need to use the NAESB standards for other than evaluation purposes, please contact the NAESB office at

OpenSG & OpenADE

The OpenSG site is used to collaborate and share information related to our work. The OpenADE Task Force is a group of smart energy management vendors, utilities, and consumer interests developing recommendations toward building interoperable data exchanges that will allow customer authorization and sharing of utility consumption information with 3rd party service providers.

Energy Use Information (EUI)

Currently, EUI is obtained from residences and businesses. There are two dimensions to energy usage that include information/data and the dialogue/interaction where all interactions are based on the same representation of data. There are two different audiences for the data, which include humans and machines.

There are three main classifications of this information:

  • Identification – this identifies the source of the information including how it was acquired. Also note that in some applications of the availability of EUI this identification information is kept separate from the rest because it can contain privacy-sensitive information.
  • Summary Information – this contains the summary of usage from the current period to date and some references for comparison. One might envision that this represents the current level of detail available to consumers through their energy bills.
  • Measure Component – here are the details of actual minute by minute / hour by hour / day by day usage of energy. This component is designed so that it can represent any set of measurements from watt-hours to watts to volt-amp-reactive to related measurements such as voltage and even temperature if necessary. Of course, the most common content will be watt-hours.

Some Context for EUI

  • When a meter is read, this is the origin of EUI
  • When a consumer participates in a demand response program, his EUI (including its cost) is key feedback to the consumer of the consequences of their actions
  • When a consumer plans how to conserve energy, EUI is the reference that they use for study/planning
  • Appliances and devices operating on behalf of the consumer can benefit from knowledge of past usage profiles.
  • Businesses with energy controls use EUI as feedback to minimize cost and maximize comfort

EUI Data Examples

  • Hourly load profile for past billing period plus current period to date
  • Fifteen minute load profile for most recent 15 days
  • Daily load profile for past month or year
  • Summary only data
  • Energy usage and energy demand readings
  • Gas, Water usage profiles
  • Yearly summary data with monthly parts

Summary View of ESPI Model Based on EUI

Note: This information is multidimensional. Many different reading types, summaries, and readings possible. i.e. not “flat”

Composition of EUI.PNG

EUI File Format

  • XML Schema (XSD)
    • Describes the rules of file format
  • XML
    • Contains customer EUI data in standard file format and references to XSD and XSLT
  • XSLT
    • Transforms the EUI file to web browser readable form

Understanding what is in the data

Useful information is available to help developers understand what the data represents. Organizations such as Tendril offer a general overview on their developer pages that covers the basics of cost compelexities, metering, and energy pricing. provides sample data for visualizing what green button data may look like.

Green Button Developer Resources

Green Button Code Repository

NIST Smart Grid Collaboration Wiki

Green Button SDK

Green Button Developmental Website

Virtual Machine for OpenESPI Development

The OpenESPI Development Virtual Machine is a Linux Ubuntu desktop environment that may be used to jumpstart your OpenESPI development efforts.

  • The VM connects to the GitHub remote repository
  • All Development Tools, Web Servers, and Test Tools are Incorporated into Free VM
  • VM Player for Windows is Free
  • VM Player for Apple is ~$50
  • OpenESPI Ubuntu VM

Download the Development VM

To run the OpenESPI Development Environment, you will need to first install the VM Ware client on you development machine.


VM configuration steps available on OpenESPI Github Virtual-Machine-Setup

Further instructions on getting started may be found here.

Green Button Logos and Graphics

Green Button Developer Community

User Groups

Development Coordination

Additional Energy Data APIs, Tools, and Services

OpenEI Hackathon Resources

OpenEI Energy Datasets


Open Energy Information connects people with energy related information and data. OpenEI contains nearly 800 energy related datasets.

The Energy Datasets section of OpenEI stores structured information in widely-used formats such as CSV, XML, and XLS. Users can browse all energy related datasets, or narrow Datasets results by searching with keywords.

Examples of helpful keywords for Green Button related data include: green button, electricity, AEO, and EIA.

Examples of datasets include:


If you have a green button related energy-related dataset to contribute, please consider uploading it to OpenEI.

  1. From the Datasets section, click Upload open data.
  2. Complete the form and be sure to tag the dataset with the keyword green button so it can be found by searching for green button in the Dataset search.
  3. Upload the dataset/file.
  4. Submit for approval.

The OpenEI Datasets are reviewed and once accepted you'll be notified via email that the Dataset has been published. Submitted datasets can be reviewed and edited.

OpenEI Knowledge Base

Search the OpenEI wiki for energy-related information.

Additional Data Resources