Utility customers have greater expectations for their providers than ever before. In addition to providing consistent, quality energy, water, or other resources, customers also want access to an increasing amount of data about their consumption and usage. Fortunately, it is possible to provide customers access to download and connect their data through the Green Button Initiative.
The Green Button API provides a highly effective way for utility companies to deliver essential information to their customers. The Green Button API is also a secure way for customers to authorize data sharing with third parties who provide other services to them. A Green Button API can be developed, implemented, and tested according to the standards set by the Green Button Alliance.
Inclind offers a range of website design and development solutions for utility companies. This includes custom integrations to implement APIs with content management systems like WordPress and Drupal. Custom integrations are a great way to ensure that you get the most out of your website - and that your customers get the information that they need. To learn more about our custom integration options and other solutions, reach out today to talk to a member of our team.
What Is a Green Button API?
To understand what a Green Button API is, it is first important to define an API. This abbreviation stands for Application Programming Interface. It is a piece of software that is used to allow two other software programs to communicate. With an API, data, features, and functionalities can be shared between software applications.
APIs are used in most modern applications, including cloud services, enterprise software, web applications, and mobile apps. They allow software development teams to essentially pull in data, services, and/or capabilities from other applications. This can streamline software development by eliminating the need to develop these features for each piece of software.
APIs consist of two elements. First, a specification defines how information is exchanged between the programs (a request for processing and return of data). Second, a software interface is written based on this specification and published. These APIs are then integrated to both make it easier for software programs to communicate and to control access to certain data.
Green button APIs are a specific type of API that allows utility customer bill and usage data to be shared. As its name indicates, Green Button APIs are about being green or eco-friendly. In fact, the Green Button Initiative was formed to respond to a 2012 call-to-action from the White House for companies to provide utility customers with simple, secure access to their electricity, natural gas, and water usage.
The goal of this initiative is to empower customers to understand their energy and water usage so that they can make more informed decisions. In 2012, this sort of data was not widely available, so implementing Green Button APIs was more innovative. Now, customers expect detailed information about their usage, making Green Button APIs more of a necessity. When installed, customers can securely download their detailed energy usage data by clicking a green button on the utility company’s website.
The Green Button Initiative sets an international standard for sharing utility customer bills and usage data. It is a complicated standard, but at its core, it has three specifications:
- XML format for customer utility data
- REST API for downloading the XML data
- OAuth 2.0 method for authorizing data sharing
Through these standards, the Green Button API provides access to energy usage information (EUI) and Personal Identifiable Information (PII). When installed, it allows data to be exchanged between utility companies, customers, and third-party service providers.
Green Button API: Key Roles & Functions
Before integration begins, it’s important to understand the three roles defined in the Green Button ecosystem:
- Data custodian: any enterprise that holds retail customer energy usage information (usually acquired from a meter) in the course of providing electricity, water, or gas service to a retail customer.
- Retail customer: any individual or enterprise that receives utility services from a data custodian. This includes residential, industrial, and commercial account holders.
- Third party: any individual or enterprise authorized by a retail customer to access their metered data held by the data custodian, for the purpose of providing a service to the retail customer.
Green Button APIs are built using a standardized machine-to-machine interface known as the Energy Service Provider Interface (ESPI). The ESPI allows a data custodian to share a retail customer’s information with authorized third parties. Within the ESPI, there are two functions: Green Button Connect My Data (CMD) and Green Button Download My Data (DMD).
- Connect My Data (CMD) enables secure, automated data sharing between utility companies and authorized third parties.
- Download My Data (DMD) allows customers to download their usage data in a standardized format (which is usually XML).
Both of these options can be found on your utility's website.
How the OAuth 2.0 Flow Works
The Green Button CMD interface uses the OAuth 2.0 protocol to allow customers to authorize access to their data. The flow typically works like this:
- The customer selects a third-party app or service on the utility’s Green Button portal.
- The customer is redirected to the utility’s authorization server.
- The customer logs in and grants permission for data sharing.
- The utility returns an authorization code to the third party.
- The third party exchanges the code for an access token, which is used to securely access the customer’s data.
- The utility API provides data in ESPI-compliant XML format via a RESTful endpoint.
Tokens are scoped (i.e., limited to specific access rights), time-limited, and can optionally be refreshed using refresh tokens for long-term access.
How To Integrate Green Button APIs Into Your CMS
The process for integration can vary greatly depending on your tech stack and site design. We’ve outlined a high-level roadmap for integrating the API into any CMS below.
Develop A Green Button-Compliant Interface
To implement the Green Button API, a utility company will need to develop a Green Button-compliant interface for CMD and/or DMD. This interface must be built in accordance with the ESPI standard, providing access to the necessary data via RESTful APIs. Ideally, utility companies will use OAuth 2.0 to allow customers to securely authorize third parties to access their data.
Implement CMD And/Or DMD Endpoints
Next, you will need to implement endpoints to retrieve data based on the customer’s authorization and the ESPI standard. You will check to ensure that the API returns data in the correct format (XML). These endpoints should return data in the Green Button XML schema, aligned with the appropriate version (e.g., v2.0, v3.3, etc.).
Design The Customer Experience
Creating an intuitive user interface is one of the most important components of the process. You don’t want customers frustrated while trying to download their data. A well-designed “Download My Data” button or Connect App interface helps increase adoption and trust. You’ll want to design interfaces for:
- Downloading usage data (DMD)
- Connecting to third-party services (CMD)
- Viewing permissions and managing access tokens
Test The Integration
At this point, test your Green Button API implementation to ensure it adheres to ESPI standards and functions correctly. The Green Button Alliance offers a testing harness that tests both CMD and DMD implementations to make sure that they are properly integrated and will work properly and securely.
Receive Green Button Certification
Once your implementation passes this testing, the Alliance will issue a Green Button Certified mark. This certification will assure both third-party developers and customers that the implementation has been tested and is compliant. It also assures customers that their data privacy will be protected.
Green Button’s ESPI standards are open. That means that they are free to implement, without mandatory registration, licensure, or royalties. This makes developing a Green Button interface much more accessible.
Many content management systems (CMS), such as WordPress and Drupal, offer plugins that make it easy to integrate an API. For a Green Button API, you will typically need a custom integration to ensure that the software is appropriately integrated with your website. Our team can work with you to develop a custom integration to ensure that your Green Button API meets ESPI standards and passes the Green Button Alliance testing for certification.
Interested in a Green Button API for Your Utility Company Website? Give Us a Call.
Many utility company customers don’t simply want to learn about their energy consumption when they get their bill each month. Instead, they prefer to access data closer to real-time so that they get a better picture of how they are using energy (or another resource) and adapt accordingly. A custom Green Button API integration can allow your utility company website to offer this data directly to your customers.
Inclind works with mid-sized utility companies throughout the United States to provide high-quality website design and development services. We tackle each project with an eye towards long-term growth and development, while focusing on cybersecurity and industry best practices. Whether you want to implement a Green Button API or another API, we can make it happen through a custom integration.
If you’d like to learn more about our website design and development services for public utilities, we’re happy to chat. You can fill out our online contact form or call us at 800-604-8139 to talk to one of our experts about your website.