Building software services to leverage Share My Data

Introduction


PG&E's Share My Data service provides a remote connection Application Programming Interface (API) at URL endpoints for external software services to receive PG&E customer authorized account data. The APIs are secured and require properly credentialed access by third parties. Credentials are distributed to third parties through a registration process at http://sharemydata.pge.com/#login, and data access is encrypted using TLS1.2 mutual authentication connection. Tokens are issued and managed in conjunction with both third party registration and end user customer authorization, according to the OAuth2 standard.


Review sample SDKs


To assist with the development of software to connect to the Share My Data platform, it is helpful to see the detailed mechanism involved in each call to the published APIs endpoints. To this end, PG&E has some sample SDKs it has developed in the past for both JavaScript and Python to illustrate key aspects of connecting to the Share My Data platform. These SDKs provide code samples to help guide you through the process of development, but are not intended to provide production code. For JavaScript, you will need to install NodeJS, and make sure to "npm install –save …" to update relevant NodeJS library modules. The code is not standalone, but provides snippets that illustrate how the interaction happens between a third-party data client code and PG&E's Share My Data API services.


Software Development Kits (SDKS)


To assist with the implementation of the Share My Data platform, PG&E developed SDKs in both JavasScript and Python. These SDKs provide samples to help guide you through the process of development, but are not intended to provide functioning code. 

Download Supported APIs (PDF, 88 KB)
The Supported APIs document shows the APIs supported by PG&E's implementation of Share My Data, as well as the PG&E specific API URL.


Download Supported Function Blocks (PDF, 108 KB)
The Supported Function Blocks document lists which ESPI standard function blocks PG&E's Share My Data implementation supports.


Download Supported Relational Data Model (PG&E Implementation of ESPI) (PDF, 282 KB)
In conjunction with the Supported Data Elements document, the Supported Relational Data Model illustrates how the relationship between the different PG&E data elements is captured by the ESPI standard.


Download Supported Data Elements (PDF, 135 KB)
The Supported Data Elements document provides a mapping between the ESPI standard data elements and PG&E's data elements.


Download XSDs (ZIP, 50 KB)
These XSDs correspond to the version of the ESPI schema definition that our Share My Data implementation uses (XSDs provide ESPI standard defined data elements).


DOWNLOAD PROCESS FLOW (PDF, 550 KB)
These process flow diagrams illustrate the redirects, authorization token flows necessary to implement PG&E's Share My Data interaction.

Share My Data implementation follows the national Energy Service Provider Interface (ESPI) standard. The standard has also been branded as the Green Button Connect My Data initiative (GBCMD) as promoted by the White House Chief Technology Officer and Presidential Innovation Fellows. The ESPI standard outlines the technical framework for delivering functionality around customer authorization, data exchange and the format of the authorized data that is exchanged. These details are covered in the ESPI standard and GBCMD documentation. Find the documentation  at Green Button Data.


To utilize Share My Data, third parties must first obtain and provision an X.509 digital certificate from a trusted certificate authority on their API connection servers. Third parties can then complete registration with PG&E at the third party registration site, upload their certificate there also, receive credentials from PG&E that enable them to test their connection, and subsequently obtain bearer tokens through our data custodian authorization token endpoints. These bearer tokens are described in the OAuth2 standard and enable third party software to securely connect PG&E's data access APIs. The SDK's provide interaction details on how to obtain the tokens in the script code.


Client access bearer tokens and Customer data access bearer tokens are obtained separately and are called Client Access Tokens and Access Tokens, respectively. Access Tokens are obtained per individual PG&E customer authorization. A typical workflow is one that follows OAuth2, per standard (IETF 6749) authorization mechanism, where a customer begins at a third party site, and that site redirects the customer to https://sharemydata.pge.com/#MyAuthorization/ first for authentication. There, the customer authenticates with PG&E and goes through a scope defining authorization of their data access to the third party ("Click-through" process). Upon completion, PG&E redirects back to the third party with an HTTP 302 response, whereupon the third party is ready to obtain bearer tokens (access token). Review a detailed flow of the process.


The third party data client server connects to PG&E's data access API endpoints by mutual TLS 1.2 connection. The individual API endpoint access controlled by bearer tokens; once a request is accepted and processed, the data is returned in a synchronous response or an asynchronous response based on a notification to a third party specified URL.


The data follows the aforementioned ESPI schema. Review a description of the supported elements.


PG&E releases data according to the scope allowed for the third party type and customer authorization.


Review a definition of the scope, and also follow the Green Button scope definitions.


Prior to registering to use Share My Data, we highly recommend that you and your organization familiarize yourselves with the following resources:


Visit the Green Button Data SDK
Tools for creating, testing, and displaying Green Button data files. Find the SDKs developed by PG&E: JavaScript | Python)


Visit the Green Button API Sandbox
This API sandbox allows developers full access, in Green Button Format, to Energy Usage Information for the purpose of developing new Green Button applications.

Due to finite system resources as well as to allow PG&E to reduce operational risks, we recommend limiting your rate of requests to:


  • 1 request per second
  • 1 months' worth of interval meter data per request

Please be aware that our acceptable use conditions are subject to change. The Share My Data team is continually evaluating our ability to support third party requests as the platform grows and more users integrate with the system. However, we will be certain to communicate any such change in advance of implementation. We are not able to adjust or otherwise modify our rate limits for any individual third party.

Please see the following release notes for improvements and changes we've made to Share My Data. If you encounter an issue with Share My Data or have a suggestion for improving the service, contact us at ShareMyData@pge.com.