Data Access

Prerequisites

The following prerequisites must be met before you can access our APIs:

  1. You must register to use the Share My Data platform before customers can authorize you to access their data. If you have not registered, please visit Share My Data: Get Started to register and complete testing.
  2. You should have completed API Connectivity and OAuth Testing. If you have not yet completed testing, please see the testing instructions.
    Visit Testing Details
  3. If your User Type requires customer authorization to access data, please ensure that the customer has granted you authorization to access their data and that you have exchanged the authorization code for an access token. If you have not yet received customer authorization, please review the customer authorization process.
    Go to Authorization details

Overview

There are several ways to access customer-authorized data via API. Our latest APIs follow the current North American Energy Standards Board (NAESB) Energy Service Provider Interface (ESPI) standard and provide access to Energy Usage Information (EUI) through a set of RESTful interfaces

 

Supported Function Blocks, APIs and Data Elements

Download Supported APIs (PDF, 217 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, 278 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, 244 KB)
The Supported Data Elements document provides a mapping between the ESPI standard data elements and PG&E’s data elements.


PG&E's implementation is compatible with the ESPI provided schema definitions found on GitHub. Specifically, our current implementation uses the following schema versions:
Download XSDs (ZIP, 42 KB)

Visit GitHub


Please reference the following sources on how to complete the signature for each API request and to test the API call against GBC's API Sandbox:
Visit the Green Button Document Library
Visit the Green Button API


Notification URI

During registration, you will need to provide a Notification URI so that our systems can notify you when your requested data is ready. If you would like to receive data corrections, please check the Notify me as data is ready checkbox.

FieldDefinition

Notification URI

The URI you provide here is where PG&E will send notifications that customer-authorized data is available (i.e., for asynchronous requests and daily subscription notification).

Notify me as data is ready flag

By checking this box, you are requesting customer-authorized data be published on a daily subscription basis. PG&E will notify you each day when the previous day's data, along with any corrections for the authorized period, is available.

  • PG&E will send notifications to your notification URI provided during registration. Notifications comprise URIs corresponding to already prepackaged data ready for you to come back and request at the provided URLs. Data is prepackaged and notifications sent out in the following two scenarios: (1) you’ve selected “Notify me as data is ready” in your registration profile, in which case we’ll package the latest daily data with any corrections for past dates, or (2) you’ve made an earlier ad hoc asynchronous request for which the requested data is now ready.
  • Scenario 1 is illustrated under the “DATA ACCESS: DAILY SUBSCRIPTION” section of the Data Access Methods diagrams below and Scenario 2 is illustrated under the “DATA ACCESS: AD HOC REQUEST (ASYNCHRONOUS)” section of the same diagrams below.

Data access methods

Data Access: Daily Subscription With the daily subscription model, PG&E will notify you on a daily basis when all authorized data from the previous day, as well as any data corrections, is ready to be retrieved. To receive daily notifications, please ensure you check the Daily Notification flag during registration or by logging into the Share My Data Third-Party Portal and updating your profile. Data Access: Synchronous Ad-Hoc Request The Synchronous Ad-Hoc request allows you to request data for a single Service ID (Usage Point). The request is made using an Access Token. The service can be utilized only by third parties that have received Customer Authorization via three-legged OAuth. Data Access: Ad Hoc Request (Asynchronous) The Asynchronous Ad-Hoc request allows you to request data for multiple Service IDs (Usage Points). The request is made using either your Client Access Token or Access Token.

 


Data request examples

Customer Data
If you are authorized by the customer to receive either “Account Information” (Account IDs, Service Agreement IDs and service start dates) and/or “Basic Information” (i.e. customer name and service address), you can request such customer information via the ESPI defined RetailCustomer APIs for which the data conforms to the schema, retailCustomer.xsd, provided above.

Synchronous (Standard and EEF third parties)
One approach to request customer data is to use the synchronous API for requesting customer information for a single customer authorization for customer data (i.e. Retail Customer):

Example Synchronous Request URL:
https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/RetailCustomer/{RetailCustomerID}
RetailCustomerID = RetailCustomerID you received at the end of the OAuth authorization sequence to get an access token. The RetailCustomerID is part of the customerResourceUri path parameter in the token response.
HTTP Header = Authorization:Bearer {access token for this authorization}
Response = you will get back data synchronously for that RetailCustomerID. The data conforms to the retailCustomer.xsd

Note: the synchronous Retail Customer API is at the individual Retail Customer level which corresponds to a single customer authorization.

For reference: the hierarchical diagram below shows the relationship hierarchy for the ESPI data elements in modeling PG&E customer data.

Asynchronous (All third parties)
You can also request customer data via the asynchronous API for requesting customer information for all of your customer authorizations for customer data (i.e. Retail Customers).
To support Asynchronous requests, your application will need to support Post Notifications we would be sending you (as per the Notification URL you provided during registration).

Example Asynchronous Request URL:
https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/BulkRetailCustomerInfo/{BulkID}
BulkID = BulkID provided in the ApplicationInformation Resource retrieved during registration testing.
HTTP Header = Authorization:Bearer {client access token retrieve during registration testing}
Response = HTTP status code 202 (This is an asynchronous request where the response will be posted to the notification URL when data is ready). Once the data is ready, we will POST a notification to your provided notification URI with a payload of URLs your application can come back to get the pre-packaged. Sample post notification looks as below

<ns0:BatchList xmlns:ns0=”http://naesb.org/espi”>

<ns0:resources>https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/
BulkRetailCustomerInfo/{BulkID}?correlationID={correlationID}</ns0:resources>

</ns0:BatchList>

Perform GET on the above URL with Client Access token to get the data.

For reference: the hierarchical diagram below shows the relationship hierarchy for the ESPI data elements in modeling PG&E customer data.

Daily Subscription (All third parties)
Lastly you can get the latest customer info on a daily basis using the daily subscription model (i.e. by selecting the “Notify me as data is ready (daily)” checkbox during registration).

To support daily subscription model, your application will need to support Post Notifications we would be sending you (as per the Notification URL you provided during registration).

Once the data is ready, we will POST a notification to your provided notification URI with a payload of URLs your application can come back to get the pre-packaged. Sample post notification looks as below:

<ns0:BatchList xmlns:ns0=”http://naesb.org/espi”>

<ns0:resources>https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/
BulkRetailCustomerInfo/{BulkID}?correlationID={correlationID}</ns0:resources>

</ns0:BatchList>

Perform GET on the above URL with Client Access token to get the data.

For reference, the hierarchical diagram below shows the relationship hierarchy for the ESPI data elements in modeling PG&E customer data.


Usage and billing data

If you are authorized by the customer to receive either “Usage Information” and/or “Billing Information”, you can request this data via the subscription APIs for which the data conforms to the schema, espiDerived.xsd, provided above.

Synchronous Ad Hoc Requests (Standard and EEF third parties)
To request historical data (for both interval usage data and bill data), one approach is to use the synchronous APIs with the inclusion of proper start and end date request parameters in Zulu time.

Example Synchronous Request URL:
https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/Subscription/{SubscriptionID}/UsagePoint/{UsagePointID}?published-min={startDate}&published-max={endDate}
published-min = start date that will be applied to this request for pulling data. The date is in Zulu time of yyyy-MM-ddTHH:mm:ssZ (IETC RFC 3339 format)
published-max = end date that will be applied to this request for pulling data. The date is in Zulu time of yyyy-MM-ddTHH:mm:ssZ (IETC RFC 3339 format)
NOTE: For API requests which accept published-max and published-min-date parameters, the default is T-1 (date of request minus 1 day). For usage summary requests (e.g. .../espi/1_1/resource/Subscription/{SubscriptionID}/UsagePoint/{UsagePointID}/UsageSummary) , we suggest providing a range of 30 days or more to ensure there is a bill available that overlaps with that period, otherwise no data will be returned.
Subscription ID = SubscriptionID you received at the end of the OAuth authorization sequence to get an access token. The subscription ID is part of the resourceURI parameter in the token response.
UsagePointID = UsagePoint under the above subscription ID. You can get all the usage points for a given Subscription by calling the below API URL and supplying the access token for that subscription in the authorization header: https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Subscription/{SubscriptionID}/UsagePoint
HTTP Header = Authorization:Bearer {access token for this Subscription}
Response = you will get back data synchronously for that usage point for the requested period. It will have both interval usage data (<IntervalBlock>) and bill data (<UsageSummary>).

Synchronous usage APIs (as indicated by the URL construction which ends with Usage Point ID) are at the individual Usage Point level (i.e. Service Agreement level), so an application would cycle the requests through each of the Usage Point IDs belonging to a given customer authorization (i.e. subscription).

The response to the synchronous requests returns both the interval data (under <IntervalBlock>) associated to the date range requested as well as any monthly usage totals and bills that overlapped with the requested date range (under <UsageSummary>).
• IntervalReading contains interval (15-min/hourly) electric usage and interval (daily) gas usage data
• Usage Summary contains the monthly usage totals and bill details (if authorized)

Within the response you will find data elements corresponding to our ESPI data element mapping table

For reference, the hierarchical diagram below shows the relationship hierarchy for the ESPI data elements in modeling PG&E customer data.

The following are a few key clarifications on these data elements:

• Intervalblock is for 1 day
• IntervalReading (underneath Interval Block) contains the actual 15-min/hourly electric usage values and daily gas usage values
• For electric customers with on-site generation (e.g. Solar), the flowDirection element indicates the delivered (supply) and received (generation) usage data. For customers with meters configured to only read the net usage (i.e. no generation on-site), the flowDirection element indicates the usage is a net amount (difference of delivered minus received):

- Flow direction of 1 = delivered (energy supplied to the customer)
- Flow direction of 19 = received (net generation flowing back onto PG&E grid). (Note, values are absolute)
- Flow direction of 4 = net (delivered minus – received)

• Pay particular attention to Power of ten multiplier and Unit of Measure (uom) so as to ensure correct usage reading


Asynchronous Ad Hoc Requests

Batch Subscription (Standard and EEF third parties)
You can also request usage data via the asynchronous API for all Usage Points belonging to a single customer authorization for usage/billing data (i.e. Subscription).

To support the Ad Hoc Asynchronous requests (i.e. for more than a single Usage Point at a time), your application will need to support Post Notifications we would be sending you (as per the Notification URL you provided during registration)

Example Asynchronous Request URL
https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/Subscription/{SubscriptionID}?published-min={startDate}&published-max={endDate}
Subscription ID = SubscriptionID you received at the end of the OAuth sequence to get an access token. The subscription ID is part of the resourceURI parameter in the token response
published-min = start date that will be applied to this request for pulling data. (RFC 3339 format zulu time. yyyy-MM-ddTHH:mm:ssZ)
published-max = end date that will be applied to this request for pulling data. (RFC 3339 format zulu time. yyyy-MM-ddTHH:mm:ssZ)
HTTP Header = Authorization:Bearer {access token for this Subscription}
Response = HTTP status code 202 (this is a asynchronous request where the response will be posted to the notification URL when data is ready)

Once the data is ready, we will POST a notification to your provided notification URI with a payload of URLs your application can come back to get the pre-packaged. Sample post notification looks as below:

<?xml version=”1.0” encoding=”UTF-8”?>

<ns0:BatchList xmlns:ns0=”http://naesb.org/espi”>

<ns0:resources>https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/Subscription/{SubscriptionID}?correlationID={correlationID}</ns0:resources>

</ns0:BatchList>

Perform GET on the above URL with Access token to get the data. This will contain both interval usage data (<IntervalBlock>) as well as bill information (<UsageSummary>) for the requested period.


Batch Bulk (All third parties)

Batch Subscription (Standard and EEF third parties)
You can also request usage and billing information via the batch bulk asynchronous API for all of your customer authorizations for usage/billing data (i.e. Subscriptions).

Example Batch Bulk Request URL
https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/Bulk/{BulkID}?published-min={startDate}&publishedmax={endDate}
BulkID = BulkID provided in the ApplicationInformation Resource retrieved during registration testing.
published-min = start date that will be applied to this request for pulling data. (RFC 3339 format zulu time. yyyy-MM-ddTHH:mm:ssZ)
published-max = end date that will be applied to this request for pulling data. (RFC 3339 format zulu time. yyyy-MM-ddTHH:mm:ssZ)
HTTP Header = Authorization:Bearer {client access token}
Response = HTTP status code 202 (this is a asynchronous request where the response will be posted to the notification URL when data is ready)

Once the data is ready, we will POST a notification to your provided notification URI with a payload of URLs your application can come back to get the pre-packaged. Sample post notification looks as below:

<?xml version=”1.0” encoding=”UTF-8”?>

<ns0:BatchList xmlns:ns0=”http://naesb.org/espi”>

<ns0:resources>https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/Bulk/{BulkID}?correlationID={correlationID}</ns0:resources>

</ns0:BatchList>

Perform GET on the above URL with Access token to get the data. This will contain both interval usage data (<IntervalBlock>) as well as bill information (<UsageSummary>) for the requested period.


Daily Subscription (all third parties)

Lastly you can get the latest usage and billing information including corrections for past dates within customer authorization periods on a daily basis using the daily subscription model (i.e. by selecting the “Notify me as data is ready (daily)” checkbox during registration).

To support daily subscription model, your application will need to support Post Notifications we would be sending you (as per the Notification URL you provided during registration).

Once the data is ready, we will POST a notification to your provided notification URI with a payload of URLs your application can come back to get the pre-packaged. Sample post notification looks as below:

<?xml version=”1.0” encoding=”UTF-8”?>

<ns0:BatchList xmlns:ns0=”http://naesb.org/espi”

<ns0:resources>https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/Bulk/{BulkID}?correlationID={correlationID}</ns0:resources>

</ns0:BatchList>

Perform GET on the above URL with Access token to get the data. This will contain both interval usage data (<IntervalBlock>) as well as bill information (<UsageSummary>) for the requested period.

general info

Need more information? Contact us

If you have questions or comments, please email our team at ShareMyData@pge.com.