Green Button Connect My Data Developer Overview

Green Button Connect My Data Developer Overview

Thank you for your interest in Green Button Connect My Data (‘GBC’). GBC is an Application Programming Interface (‘API’) that provides third parties with access to Pacific Gas and Electric Company’s (‘PG&E’) customers’ SmartMeter™ 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.

At this time, PG&E is no longer accepting applications for access to GBC. PG&E is currently working on GBC updates, please stay tuned for more information.

Green Button Connect My Data updates coming soon!

The next-generation of our GBC product will be available in 2015! This product will be a secure software interface that will allow PG&E customers from all customer classes with interval meter data to easily share their data with registered and authorized service providers. It will be launched in two phases over the next two years:

  • Q1 2015: Electric interval usage data will be available.
  • Q4 2015: Expanded datasets will be available (which may include: gas, pricing, DR event, and/or other messages).

Fill out and click the 'Submit' button on this PDF form (PDF, 134 KB), this will return the form to PG&E (gbc@pge.com) to join our notification list for product updates.

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 SmartMeter™ 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 SmartMeter™ 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 SmartMeter™ 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

Fill out and click the 'Submit' button on this PDF form (PDF, 134 KB), this will return the form to PG&E (gbc@pge.com) to join our notification list for product updates.

  • Energy Upgrade Califorinia
  • eRebates