Green Button Connect Developer Overview

Green Button Connect Developer Overview

Thank you for your interest in Green Button Connect (‘GBC’). GBC is an Application Programming Interface (‘API’) that provides third parties with access to Pacific Gas and Electric Company’s (‘PG&E’) customers’ electricity data, based on those customers’ prior authorization. Once customers set up a PIN code for their electrical service, and provide that information to their chosen third parties, GBC gives those third parties machine-to-machine access to those customers’ electricity data on a recurring basis, with no further action needed on the part of customers. This represents a leap forward in customer data access for third parties and a streamlined experience for customers.

PG&E has already established connections with an initial group of third parties (‘Requestors’) that are offering unique ways to help customers save energy. PG&E has received many applications for GBC access. At this time, PG&E has already selected the first round of expanded third parties requestors based on the order they were submitted. The number of 3rd party applicants selected was dependent on the nature and scale of requests provided by each applicant. PG&E’s goal is to work within the system limits and ensure that the response time per request is reasonable. For this to be a successful pilot program, GBC needs to be able to provide a satisfactory customer experience. PG&E will stabilize the platform after the first round of expanded participants. At that time, we will consider expanding the number of third parties with access to the API based on the performance of the API during the first round of testing.

Please submit your application to be put on the waitlist for consideration into the next round of connecting third parties. The next round of applications will also be evaluated, based on the order they were submitted.

How to apply for GBC API access

Fill out and email back this PDF application (PDF, 206 KB) (PDF, 186 KB) to PG&E (gbc@pge.com). A GBC program representative will review your application and contact you with next steps. Please note that due to the nature of this beta program, the number of Requestors that PG&E can accept into the beta program is limited.

How to gain access to customer data

Before Requestors can access customer data via the GBC API, there are two steps that must occur:

  1. Requestors must apply for access to the GBC API beta program. (see: ‘How to apply for GBC API access’)
  2. Customers must create a PIN code for each of the electrical service agreements they wish to share via the GBC API, and provide both their Service ID and PIN code. Please note that customers may suspend Requestor access to their data at any time by changing or deleting the PIN code associated with their Service ID. The Green Button information page provides step-by-step instructions on how to set up a PIN code.

Technical Overview

Security and Authentication

Data requests and responses are made using the secure HTTPS protocol, and authenticated via a two-way certificate exchange with PG&E. Requestors will need to implement Entrust security certificates for secure inbound and outbound API communication. In addition, Requestors will need to provide PG&E with their IP addresses, URLs, and port numbers for both QA and production servers, to assist with PG&E’s firewall configurations. For more information regarding Entrust certificates, visit: http://www.entrust.net/

API Architecture

The GBC API is a RESTful web service, with requests and responses handled asynchronously, as two separate transactions. PG&E accepts an HTTPS post message for the request transaction, and responds by posting a RESTful message back to the third party with the customer energy usage information. Both requests and responses must be in the NAESB ESPI (XML) data format. For more information regarding the NAESB ESPI format, visit: http://collaborate.nist.gov/twiki-sggrid/bin/view/SmartGrid/GreenButtonInitiative

Request limits and data availability

In order to manage transaction load, PG&E has set a maximum request duration per request of 185 days from the start date. Requestors can specify their own date range, and send multiple requests in order to build a complete picture of customer data. In addition, only electrical consumption data for currently active customer Service IDs is available via the GBC API. Note that if a customer receives a new Service ID due to events such as a physical meter swap or payment rate change, their deprecated Service ID will become inactive, disabling GBC API access to the data associated with the deprecated Service ID.

Due to system constraints, PG&E requests that API users not exceed six (6) API requests per minute. For recurring customer data calls, Requestors should shift their API requests to off-peak hours (6pm to 6am, PDT). Please note that PG&E reserves the right to adjust this limit, based on ongoing performance evaluations.

Disclaimers and Terms of Use

Some Important Disclaimers

  1. The GBC API is currently in ‘beta,’ and may be discontinued at any time. PG&E will not be liable for any losses or expenses incurred by Requestor or Customers if and when the GBC API is discontinued.
  2. The number of requestors that PG&E can accept into the program is limited and you are not guaranteed access; we are reviewing applications on a first-come first serve basis…Acceptance into the trial is contingent upon the nature of the vendor’s application and GBC’s ability to support the request.

  3. Only electrical consumption data for currently active customer Service IDs is available via the GBC API. Note: If a customer receives a new Service ID due to events such as a physical meter swap or payment rate change, their old Service ID will become inactive, disabling GBC API access to that Service ID.

  4. GBC API response times can range from less than one minute, to several hours, depending on request traffic. PG&E makes no guarantee of API response time and cautions Requestors against building a ‘real-time’ response into the user experience of their customer-facing applications.

  5. PG&E reserves the right to implement, modify, or remove restrictions and limits to the API or these Disclaimers and Terms of Use at any time. Updates will be posted on PG&E’s website.

  6. PG&E will provide limited GBC API technical support to Requestors during business hours. However, PG&E does not provide any guarantees to Requestors, verbally or in writing, and will not be responsible for any losses or expenses associated with a GBC API interruption, lack of responsiveness, or performance lag.

  7. Any violation of any of the GBC API Terms of Use is grounds for immediate suspension from the GBC API beta program.

Developer Links

View API Terms and Conditions, and apply for access.

  • Ways To Pay