Share My Data for third parties

In order to comply with the current North American Energy Standards Board (NAESB) Energy Service Provider Interface (ESPI) standard for authorization, PG&E has implemented OAuth 2.0 Authorization framework for authorizing the access of data. The diagram below illustrates how customers initiate authorization, choose scope parameters and then submit their authorization.

Additional reference material beyond information below:

Download the ESPI OAuth 2.0 Sequence Diagram (PDF)
View the Green Button data SDK at Github

 Note: For Community Choice Aggregators, only the client_access_token is needed to request data (via 2-Legged OAuth) and the following does not apply.

Authorizations initiated at the third party site

To begin an authorization from a third party site as illustrated in the first diagram above, an authorization code request is made by redirecting the customer's browser from your third party site to PG&E's AuthorizationServer Authorization Endpoint URL with appropriate request parameters as exampled below. Upon redirection, the customer will be presented a PG&E log-in page for authentication, followed by an authorization page for authorizing data access to your third party:

authorizationServerAuthorizationEndpoint URI (with request parameters)
https://sharemydata.pge.com/myAuthorization?client_id=A1b2C3&redirect_uri={redirect_uri}&response_type=code&state={optionalState}

• Mandatory Request Parameters:
  • client_id = Client ID from your Share My Data registration milestones (i.e., client_id/client_secret pair).
  • redirect_uri = redirect URL that you specified in your Share My Data registration (URLs must match).
     Note: We recommend URL encoding be applied to the redirect_uri as per example below.
  • response_type = code (static value)
• Optional Request Parameter(s):
  • state = optional opaque state parameter as allowed by the OAuth 2.0 standard that is returned back with the authorization code in order to help maintain state. For example, the state parameter might be used by a third party to uniquely identify customer origination and to prevent cross-site forgery.
  • login={guest} Provide the option for a third party to redirect customers to either PG&E’s My Energy log‐in or to the Guest Access tab as part of the online authorization flow.

EXAMPLE: Auth code request

GET: https://sharemydata.pge.com/myAuthorization?client_id=A1b2C3&redirect_uri=https%3A%2F%2Fthirdparty.com%2FredirectUrl&response_type=code&state=pge12advertisement

 Note: example redirect_uri parameter above has URL encoding applied (i.e. URL encoding of https://thirdparty.com/redirectUrl)

If you make a valid request as above, and the customer successfully authenticates and authorizes, the customer will subsequently be redirected to your redirect_uri with the authorization code, (authorized) scope parameter, and optional state parameter (if provided as part of authorization request) as exampled below:

https://thirdparty.com/redirectUrl?authorization_code=7afc7c4f-778a-4ad8-8337-5e19218a2219&scope=FB=1_3_8_13_14_18_19_31_32_35_37_ 38_39_40_4_5_10_15_16_46_47;AdditionalScope=Usage_Billing_Basic_Account_ProgramEnrollment;IntervalDuration=900_3600;BlockDuration=Daily;HistoryLength={3P Registered historical length};AccountCollection={count of authorizedSAs};BR={ThirdPartyID};dataCustodianId=PGE &state=pge12advertisement

 Note: The Authorization Code is short-lived (expires in 600 seconds), and must be subsequently exchanged for an access token/refresh token pair so as to complete the authorization and allow on-going data access. See the next section (Section 2) for details on the Access Token/ Refresh Token request.

The (authorized) scope parameter exampled above is returned as part of responses to the Authorization Code Request, the Access Token Request, as well as the Authorization API. This scope parameter allows for communicating the final scope of customer authorization. In particular, the scope parameter includes an "AdditionalScope" value that maps to PG&E's supported customer authorization selections of data groups (e.g., "Usage", "Billing", "Basic", "Account", "Program Enrollment"). The scope parameter values are further captured per the following reference documentation: Download Supported Function Block Scope String Mapping Click Thru 2.0 (PDF).

Error Scenarios

Third Party Implementation Errors: If the required request parameters of client_id or redirect_uri are invalid or missing upon requesting an authorization code, the customer will be shown an explanatory message along with the standard HTTP 400 series error. Similarly, if the required request parameter of response_type is missing or invalid, the customer will be redirected back to your redirect_uri with the OAuth 2.0 defined "invalid_request" error parameter as well as the optional state parameter if first provided as part of the original authorization code request.

Customers Declining to Authorize: Upon a third party redirecting a customer to authorize with PG&E, a customer has the option to decline via a "cancel" button at both the log-in page and the authorization page. In such instances, the customer will be redirected back to your redirect_uri with the OAuth 2.0 defined "access_denied" error parameter appended to indicate the customer declined to authorize. In addition, the optional state parameter will be returned if first provided as part of the original authorization code request.

Authorizations Initiated at PG&E

When customers start out on PG&E's customer web portal, "Your Account," and then navigate to the Share My Data landing page, they are presented a dropdown of registered and visible third parties. As illustrated in the second diagram above, upon a customer selecting a third party from the list of registered third parties and selecting "Next," the customer will be redirected to the third party's registered "Third Party Portal URI," at which point customers can proceed with the third-party initiated OAuth process described in the preceding section.

 Note: Some third parties have inquired about how to streamline the customer experience for this use case (i.e., authorizations initiated on PG&E's site) such that to the customer it appears they are taken directly to an authorization page upon selecting a third party from the dropdown. To facilitate such a customer experience, third parties can elect to set their "Third Party Portal URI" (via the Share My Data manage registration page) to an endpoint that automatically redirects the customer back to PG&E as part of an authorization code request. Upon automatic redirect back to PG&E's authorization Server Authorization Endpoint, the customer will skip the customer login page (as they are already logged in) and will go directly to the authorization page. For some third parties who have registered prior to the Share My Data Click Thru 2.0 release in late June of 2018, this can be accomplished by simply defining the Third Party Portal URI to equal the no longer used "Third Party Scope Selection Screen" URI (field to be retired in a future release).

In contrast, some third parties may want to first engage and screen customers on their side when customers are redirected to their "Third Party Portal" URI before requesting an authorization code, so the above approach is only a suggestion.

To obtain an Access Token, use the Authorization Code received and call the below endpoint with request parameters as described below. As described above, the Authorization Code is short lived, expiring after 10 minutes (600 seconds), so please ensure the Access Token is promptly requested upon receipt of an Authorization Code.

authorizationServerAuthorizationEndpoint: https://api.pge.com/datacustodian/oauth/v2/token

• Mandatory Request Parameters:
  • grant_type = authorization_code (static value)
  • code = authorization code received in response to authorization code request
  • redirect_uri = redirect URL that you specified in your Share My Data registration (URLs must match).
     Note: As with the authorization code request, we recommend URL encoding be applied to the redirect_uri.

EXAMPLE: Access Token request
POST: https://api.pge.com/datacustodian/oauth/v2/token?grant_type=authorization_code&code={authorizationcode}&redirect_uri={redirect_uri}

Add basic Authorization header parameter with Base64 encoding applied "clientID:clientSecret"

 Note: The clientId:clientSecret values correspond to the clientID values provided in your Share My Data registration milestones.
The header parameter will be in the following format:
Param name : Authorization
Param value : Basic "base64encoded string"

A successful response will look like this:

<Response xmlns="https://api.pge.com/datacustodian/oauth/v2/token">
<access_token>774ff105-7ad5-40c8-a6ec-f60675dc0e41</access_token>
<expires_in>3600</expires_in>
<refresh_token>998c6654-5b3b-4385-af4f-4e5c46c1bb04</refresh_token>
<scope>scope=FB=1_3_8_13_14_18_19_31_32_35_37_38_39_40_4_5_10_15_16_46_47;AdditionalScope=Usage_Billing_Basic_Account_ProgramEnrollment;IntervalDuration=900_3600;BlockDuration=Daily;HistoryLength={3P Registered historical length};AccountCollection={count of authorized SAs};BR={ThirdPartyID};dataCustodianId=PGE</scope>
resourceURI:{ResourceURI} e.g.: https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Subscription/{subscriptionID}
authorizationURI:{AuthorizationURI} e.g.: https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Authorization/{authorizationID}
customerResourceURI:{customerResourceURI} e.g:https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/RetailCustomer/{RetailCustomerID}
<token_type>Bearer</token_type>
</Response>

 Note: An Access Token expires in 3600 secs (1 hour), while the corresponding Refresh Token expires in 1 year. See next section 3 for details on acquiring a new Access Token/Refresh Token pair.

Save the access and refresh token pair.
To request initial historical data and ongoing daily data, visit data access.

As per best practice, the Access Token is a short-lived token (1 hour) while the corresponding Refresh Token is a long-lived token (1 year) that you can use to acquire a new Access Token/Refresh Token pair when the Access Token expires. To obtain a new Access Token and Refresh Token pair for existing non-expired authorizations, use the "current Refresh Token" and call the below endpoint with parameters as described below.

authorizationServerAuthorizationEndpoint: https://api.pge.com/datacustodian/oauth/v2/token ?grant_type= refresh_token&refresh_token={current_refresh_token}

EXAMPLE: Refresh Token request
POST: https://api.pge.com/datacustodian/oauth/v2/token?grant_type= refresh_token&refresh_token={current_refresh_token}

Add basic Authorization header parameter with Base64 encoding applied "clientID:clientSecret"

 Note: The clientId:clientSecret values correspond to the clientID values provided in your Share My Data registration milestones.
The header parameter will be in the following format:
Param name : Authorization
Param value : Basic "base64encoded string"

A successful response will look like this:
{
"access_token": "677e6ef8-1e1a-43f0-85b8-5692fcbc72b2",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "0eef9a9f-60c6-40bb-b33f-910e322c0298",
"scope": "scope=FB=1_3_8_13_14_18_19_31_32_35_37_38_39_40_4_5_10_15_16_46_47;AdditionalScope=Usage_Billing_Basic_Account_
ProgramEnrollment;IntervalDuration=900_3600;BlockDuration=Daily;HistoryLength={3P Registered historical length};AccountCollection={count of authorized SAs};BR={ThirdPartyID};dataCustodianId=PGE",
"resourceURI": "https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/Subscription/test",
"authorizationURI": "https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Authorization/test"
}

 Note: Similarly, the Client Access Token is a short-lived token (1 hour) while its corresponding Refresh Token is a long-lived token (1 year) that you can use to acquire a new Client Access Token/Refresh Token pair when the Client Access Token expires. To obtain a new Client Access Token/Refresh Token pair, reference the same steps described above.

Customers will be able to update their authorizations by doing the following:

• Removing Service IDs from their authorizations
• Extending the end date of the authorization period
• Canceling the authorization

 Note: Customers will only be able to make changes to their authorizations by logging in to their online PG&E account and following the required steps. If any of these actions are taken, we will notify you via the Notification URI that you provided during registration.

There are options for managing and viewing details of your customer authorizations:

• You can call the authorization API (http GET operation) using your client_access_token either at the third party level (for details on all authorizations) at https://api.pge.com/GreenButtonConnect /espi/1_1/resource/Authorization or at the individual customer authorization level at https://api.pge.com/GreenButtonConnect /espi/1_1/resource/Authorization/{AuthorizationID}.
• Separately, you can also view individual authorization details manually by logging in to your Share My Data account via the third party portal and entering the Subscription ID for the authorization you’re searching for.

If you no longer want to access data associated with an authorization, there are optional methods to cancel an authorization:

• You can call the authorization revocation API (http DELETE operation) using your client_access_token at https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Authorization/{AuthorizationID}.
• Alternatively, you can manually cancel an authorization by logging in to your Share My Data account via the third party portal and entering the Subscription ID for the authorization you wish to cancel.

 Note: The customer will be notified that you have elected to cancel their authorization. In addition, once an authorization is cancelled, the action cannot be reversed.

• 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.

Please keep in mind the token lifetime of the Access Tokens, Client Access Token, and their corresponding Refresh Tokens used in the data requests. As per best practice, the Access Token is a short-lived token (1 hour) while the refresh token is a long-lived token (1 year) that you can use to acquire a new Access Token/Refresh Token pair when the Access Token expires. Similarly, the Client Access Token is a short-lived token (1 hour) while its corresponding Refresh Token is a long-lived token (1 year) that you can use to acquire a new Client Access Token/Refresh Token pair when the Client Access Token expires. For more details on obtaining a new token pair, refer to Step 3, Requesting a new access token, in our authorization details tab. Go to authorization details

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. (RetailCustomerID=SubscriptionID)

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.

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. (BulkID=ClientID)

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.

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.

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. (SubscriptionID=RetailCustomerID)

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 () and bill data ().

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) associated to the date range requested as well as any monthly usage totals and bills that overlapped with the requested date range (under ).

• 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

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 () as well as bill information () for the requested period.

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. (BulkID=ClientID)

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 () as well as bill information () for the requested period.

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 () as well as bill information () for the requested period.

June 20, 2024

PG&E’s Share My Data Platform (SMD) for Customer-Authorized Data Sharing with third-party Service Providers released Phase 2 of our Meter ID Enhancement, allowing for identification of the individual Meter ID associated with electric interval meter data.  

This enhancement is particularly useful for user scenarios where multiple meters are associated with one service agreement.

Phase 1:  Released March 2023 - Modified the impacted APIs to begin adding a <utcNumber/> value along with the <serialNumber/> value in the response returned, under the <Meter/> tag. There is a one-to-one correspondence between the serialNumber value and utcNumber value.

This information allows vendors using these API’s to build a store of records with the utcNumber along with the serialNumber value associated with a given meter for their customer base before the Phase 2 enhancement is released.

Phase 2:  Released June 20, 2024 - Replaces the MeterReadingID values from the current encode64 format of meter descriptive values with the utcNumber. Once these changes are fully implemented, Share My Data users will have an improved ability to link to specific meters interval usage, in cases where there are multiple meters of the same commodity linked to a single service agreement on premise, to the specific meter ID that generated the usage. 

The following APIs are impacted by the Phase 2 changes

Impacted API:

.../espi/1_1/resource/Subscription/{SubscriptionID}/UsagePoint/{UsagePointID}/MeterReading

.../espi/1_1/resource/Subscription/{SubscriptionID}/UsagePoint/{UsagePointID}/MeterReading/{MeterReadingID}

.../espi/1_1/resource/Subscription/{SubscriptionID}/UsagePoint/{UsagePointID}/MeterReading/{MeterReadingID}/IntervalBlock

.../espi/1_1/resource/Subscription/{SubscriptionID}/UsagePoint/{UsagePointID}/MeterReading/{MeterReadingID}/IntervalBlock/{IntervalBlockID}

All other API’s with interval reads are unchanged and represent SUM of meter intervals in both flow directions and with all meters under a service agreement.

Prior to the release the MeterReadingID field was Base64 encoded and the value returned shows as follows:

MeterReadingID= TnpJNmJuVnNiRG96TmpBd09qRT06MTox

Decoded from Base64 format as:  NzI6bnVsbDozNjAwOjE=:1:1

This shows readingTypeID:rownum:count, and readingTypeID value is decoded from Base64 again as:

72:null:3600:1 where values are uom:phase:intervalLength:flowDir

UOM=72, phase=null, intervalLength=3600, and flowDir=1 (delivered)

In Phase 2, the MeterReadingID field is appended with additional characters and after going through an initial decoding will return the following example results

MeterReadingID=TnpJNmJuVnNiRG96TmpBd09qRT06MToxOjQ0MTEzMTA1NDYgICAgICAgICAg

Decoded from Base64 once:  NzI6bnVsbDozNjAwOjE=:1:1:4411310546, 

This shows meter_UUID is 4411310546, and this value should match the <utcNumber/> value available in the RetailCustomer API under the <Meter/> tag.

The value of “NzI6bnVsbDozNjAwOjE=:1:1:” is the readingTypeID:rownum:count, i.e. the row number is 1 and count is 1 related to PG&E’s internal database records. The readingTypeID is decoded again as:

72:null:3600:1, where values are uom:phase:intervalLength:flowDir

UOM=72, phase=null, intervalLength=3600, and flowDir=1 (delivered)

This change allows users to specify the physical meter and flow direction of interest in the interval reads. Note that all XML files will now carry the new MeterReadingID values and will be applying the new Phase 2 form of encoding. Share My Data advises all vendors who use any API call using MeterReadingID, make the following API call to get the new MeterReadingID: .../espi/1_1/resource/Subscription/{SubscriptionID}/UsagePoint/{UsagePointID}/MeterReading

March 20, 2023

What’s new:

1. Release of a new API HTTP response code (204) for both synchronous and asynchronous API calls to indicate when no data is available for the requested range.
2. Supporting an x-transaction header label that supports the ability to link PG&E’s response to specific Asynchronous API calls by returning this value along with a Correlation ID when the requested file is ready.
3. Improved additional data granularity to the UsagePoint/MeterReadingID API by providing electric interval data for multiple meters to single Service Agreement scenarios.
4. Provided additional clarity to Reading Quality Indicator values for ESTIMATED interval data to describe the type of estimation used for that interval. New values indicating estimation logic has been applied are below:
   
   

5. RQI value and description

   0 - Valid: data that has gone through all required validation checks and either passed them all or has been verified

   7 - Manually edited: replaced or approved by a human

   8 - Estimated using reference day: data value was replaced by a machine computed value based on analysis of historical data using the same type of measurement

   9 - Estimated using linear interpolation: data value was computed using linear interpolation based on the readings before and after it

   10 - Questionable: data that has failed one or more checks

   11 - Derived: data that has been calculated (using logic or mathematical operations), not necessarily measured directly

   12 - Projected (forecast): data that has been calculated as a projection or forecast of future readings

   13 - Mixed: indicates that the quality of this reading has mixed characteristics

   14 - Raw: data that has not gone through the validation, editing and estimation process. NOTE MV90 Meters RQI indicator will remain in 14 as a final RQ status

   15 - Normalized for weather: the values have been adjusted to account for weather, to compare usage in different climates

   16 - Other: specifies that a characteristic applies other than those defined

   17 - Validated: data that has been validated and possibly edited and/or estimated in accordance with approved procedures

   18 - Verified: data that failed at least one of the required validation checks but was determined to represent actual usage

   19 - Revenue quality: valid and acceptable for billing purposes [possible extension for ESPI standard, and not part of original ESPI]

    

6. Release of vendor API usage metrics in the Share My Data Third Party vendor portal.

November 15, 2018

What's new:

1. Customer Class Indicator has been added. Each SAID that is authorized will be identified as either RES, AGR, COM/IND or Other.
2. Billing and Usage APIs will be updated to accept updated-max and updated-min query parameters (as an alternative to published-min and published-max). The data returned will be all changes that have occurred within the updated-max and updated-min parameters.
3. Replacing the use of a third party's 5-digit Bulk ID with the third party’s Client ID for the online authorization flow.
4. Providing the option for a third party to redirect customers to either PG&E's account login or the Guest Access tab as part of the online authorization flow.
5. Improving PG&E’s Share My Data customer dashboard to make it easier for customers to view all of their existing data sharing authorizations with third parties.

September 27, 2018

What's new:

PG&E added new data elements to the Rule 24 data set as part of PG&E's Expanded Data Set (EDS) project, and corresponding new data elements are introduced in Rule 25 data set. The specific data elements comprising PG&E's expanded Rule 25 data set are set forth below with designation EDS:

Rule 25 Data Elements

Notes
Account Elements
Account Name
Account Address
Account ID
EDS: Outage Block
Service Elements
PG&E UUID
Service ID
Future Changes to Status of Service
SA Status
Service Start Date
Service Address
Current Service Tariff
Historical Billed Service Tariff
Tariff Options (Medical Baseline, CARE, FERA, TBS, CCA_TBS, Solar Choice
Current Service Voltage and Commodity Historical Billed Service Voltage
Service Meter Number
Number of Service Meters
Meter Type
Current Meter Read Cycle
Historical Billed Meter Read Cycle
Current Standby Rate Option if On-site Generation Indicator
Historical Billed Standby Rate Option
EDS: Customer Class Indicator
Historical Billing Elements
Bill start date
Bill end date
Bill total charges($)
Bill total kWh
EDS: Name of Service Provider
Historical Bill Tier Breakdown (if any)
EDS: Line Item Bill Period
EDS: Name (Over Baseline 1%-30%)
EDS: Volume (1234.2)
EDS: Rate ($0.032/kWh)
EDS: Cost ($100.23)
Historical Bill TOU kWh breakdown (except for ABS-TX billed)
EDS: Line Item Bill Period (for TOU breakdown)
EDS: Name (of TOU charge)
EDS: Volume (1234.2)
EDS: Rate ($0.032/kWh)
EDS: Cost ($100.23)
Historical Bill Demand Breakdown
EDS: Line Item Bill Period (for Demand breakdown)
EDS: Name
EDS: Volume (1234.2)
EDS: Rate ($0.032/kWh)
EDS: Cost ($100.23)
Historical Bill Line Items
EDS: Line Item Bill Period
EDS: Charge name (DWR Bond Charge)
EDS: Volume (1234.2)
EDS: Unit (kWh)
EDS: Rate ($0.032/kWh)
EDS: Cost ($100.23)
Historical Usage Intervals
Interval Usage Start
Default Interval Duration (in seconds)
Interval usage Volume (1234.2)
Unit (kWh/Therms)
Utility Demand Response Programs
(DR) Program Name
Earliest Termination Date without Financial Obligation
Earliest Termination Date regardless of Financial Obligation
DR Program Status
DR Program Enrollment Date
DR Program De-Enrollment Date
Data Elements
Commodity
Local Time Parameters (DST details)
Default Data Quality
Energy Direction
Power of Ten Multiplier (for interval usage values)
Power of Ten Multiplier (for Billed Demand)
Power of Ten Multiplier (For Billed total usage)
Interval Length(of Usage Reading)
Currency of bill total cost
Electric Interval TOU Indicators

June 28, 2018

As part of the Click-Through project and the continued improvements to the Share My Data Platform, PG&E launched Click-Through Phase 2 on June 28, 2018.

What's new:

The most critical changes that impact third parties are changes to conform to the OAuth 2.0 protocol (PG&E eliminated the initial series of redirects). Find details below.

IMPORTANT: Third parties are REQUIRED to make changes to their existing OAuth implementation. PG&E's Click-Through Phase 2 changes are NOT backwards compatible, so it is necessary for third parties to implement changes concurrent with PG&E's implementation. Without implementation, the current customer authorization process will stop working on the cut-off date of June 29, 2018. Existing authorizations, however, are unaffected.

1. To conform to the OAuth 2.0 protocol, PG&E has reduced the number of redirect steps for authorization. The initial redirect to PG&E for customers to log in and submit an authorization has been combined with the authorization code request as follows:
   • As shown in the example below, third-party Authorization code requests now comprise a redirect of the customer's browser to PG&E's new authorizationServerAuthorizationEndpoint URI, along with appropriate request parameters:
     GET https://sharemydata.pge.com/myAuthorization?client_id=xxxxx&redirect_uri={redirect_uri}&response_type=code&state={optionalState}
   • The following endpoint has been retired: https://api.pge.com/datacustodian/oauth/v2/authorize...
     
2. New error handling messages for authorization code requests with missing or invalid scope parameters as follows:
   • If the required client_id or redirect_uri parameters are missing or invalid, an (http 400) error with explanatory message is shown to the customer
   • If the required response_type parameter is missing or invalid, the customer will be redirected back to the third party's redirect_uri with an "invalid_request" error parameter (appended to the redirect_uri)
     
3. For customers with an existing online authorization, the ability for a third party to request a new access_token/refresh_token pair as part of a new authorization that replaces the existing one (i.e., online authorization of the same third party and customer combination). This functionality addresses scenarios of third parties losing an access_token/refresh_token pair or otherwise needing to change the scope of the original authorization per customer approval.
   • For re-authorization requests, the customer sees the new authorization page instead of the "manage authorization" page when redirected by a third party to PG&E for authorization
   • Upon customer authorization, third parties receive a notification to their registered notification URL that the old subscription ID is canceled (notification comprises authorization API URL endpoint for the old subscription ID)
     
4. The ability for a customer to exit via a "cancel" button on either the authentication page or authorization page with redirect back to the third party's redirect_uri with an "access_denied" error parameter (appended to the redirect_uri)
5. For third parties who register with the "visibility" setting on and are therefore included in the list of registered third parties customers will see when they go to their PG&E online account and navigate to the Share My Data landing page:
   • For customers who log in to their PG&E online account and navigate to the Share My Data landing page and are then redirected to third party's registered "Third Party Portal URI" upon selecting a third party from the list of registered third parties. At that point, customers can proceed with the third party initiated OAuth process. When going through this path, customers will no longer be shown the authorization page upon selecting a third party from the dropdown list of third parties, but instead be redirected to the third party's registered "Third Party Portal URI" where they can begin the third party initiated OAuth process
   •  Note: Some third parties have inquired about how to streamline the customer experience for this use case (i.e., authorizations initiated on PG&E's site) such that to the customer it appears they are taken directly to an authorization page upon selecting a third party from the dropdown. To facilitate such a customer experience, third parties can elect to set their "Third Party Portal URI" (via the Share My Data manage registration page) to an endpoint that automatically redirects the customer back to PG&E as part of an authorization code request. Upon automatic redirect back to PG&E's authorizationServerAuthorizationEndpoint, the customer will skip the customer login page (as they are already logged in) and will go directly to the authorization page. For some third parties who have registered prior to the Share My Data Click Thru 2.0 release, this can be accomplished by simply defining the Third Party Portal URI to equal the no longer used "Third Party Scope Selection Screen"URI (old SMD Registration field to be retired in a future release).
     In contrast, some third parties may want to instead first engage and screen customers on their side when customers are redirected to their 'Third Party Portal' URI before requesting an authorization code, so the above approach is only a suggestion.
     
6. SMD will now be providing enhanced Scope parameter details as part of the responses to the Authorization Code Request, the Access Token Request, and the Authorization API. The enhanced scope parameter allows for communicating the final scope of customer authorization. In particular, the scope parameter includes an "AdditionalScope" value that maps to PG&E's supported customer authorization selections of data groups (e.g. "Usage", "Billing", "Basic", "Account", "Program Enrollment"). The scope parameter values are further captured per the following documentation: Download Supported Function Block Scope String Mapping Click Thru 2.0 (PDF)
   
   An example Token response below illustrates some possible scope parameter values.
   • Example Token Response:
     <Response xmlns="https://api.pge.com/datacustodian/oauth/v2/token">
     <access_token>774ff105-7ad5-40c8-a6ec-f60675dc0e41</access_token>
     <expires_in>3600</expires_in>
     <refresh_token>998c6654-5b3b-4385-af4f-4e5c46c1bb04</refresh_token>
     <scope>scope=FB=1_3_8_13_14_18_19_31_32_35_37_38_39_40_4_5_10_15_16_46_47;AdditionalScope=Usage_Billing_Basic_Account_ProgramEnrollment;IntervalDuration=900_3600;BlockDuration=Daily;HistoryLength={3P Registered historical length};AccountCollection={count of authorized SAs};BR={ThirdPartyID};dataCustodianId=PGE</scope>
     resourceURI:{ResourceURI} e.g: https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Subscription/{subscriptionID}
     authorizationURI:{AuthorizationURI} e.g: https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Authorization/{authorizationID}
     customerResourceURI:{customerResourceURI} e.g:https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/RetailCustomer/{RetailCustomerID}
     <token_type>Bearer</token_type>
     </Response>
     
     
7. Third parties can now register to receive authorized Program Enrollment information via the new "Program Enrollment" data group. Both interval metered as well as non-interval metered customers will be eligible to authorize sharing of data for SMD Click-Through Phase 2. A high-level summary of the newly available data elements provided by the Program Enrollment data group is as follows:
   • Program Enrollment (PG&E Demand Response program name/status and CAISO information):
   • (Billing) Account address
   • Service Agreement Status
   • (Current) Service tariff
   • (Current) Service voltage (electric only)
   • Service meter number (if any)
   • Meter type
   • (Current) Meter Read Cycle
   • (Current) Standby Rate Option if On-Site Generation Indicator
   • (default interval usage) Duration (length in seconds)
   • (Enrolled PG&E Demand Response) Program Name (if applicable)
   • Earliest Termination Date from PG&E enrolled Demand Response (DR) Program without Financial Obligation
   • Earliest Termination Date from PG&E enrolled Demand Response (DR) Program regardless of Financial Obligation
   • PG&E Demand Response (DR) Program (enrollment) Status
   • PG&E Demand Response (DR) Program Enrollment Date
   • PG&E Demand Response (DR) Program De-Enrollment Date
   • The Atom XML XSD (XML Schema Definition) mapping for these new data elements are captured as per the following documentation:
     Download Supported Data Elements (PDF)
   • Associated relational data hierarchy model is outlined per the following:
     Download PGE ESPI Data Model (PDF)
   • UsagePoint (aka SA UUID)
     • ServiceDeliveryPoint\tariffProfile(current service tariff AKA rate schedule including Standby Rate Option if applicable)
     • readCycle (current Meter Read Cycle)UsageSummary
     • readCycle (billing service cycle)
     • Commodity (includes billed voltage level for electric)
     • tariffProfile (billed service tariff including Standby Rate option if applicable
   • Reading Type
     • Commodity (includes current voltage level for electric and prefix for Standby Rate Option where applicable)
   • Customer Account
     • (Acct Billing Address):
     • mainAddress/streetDetail...
     • mainAddress/townDetail...
     • mainAddress/postalCode...
   • Customer Agreement
     • status\value (SA Status
   • Demand Response Program
     • programName
     • enrollmentStatus
     • programDate/programDate
     • programDate/programDateDescription
   • Meter
     • serialNumber (meter id)
     • type (meter type)
     • (current) intervalLength
   • Latest ESPI xml schema definitions (XSDs) used for these new data element is outlined per the following:
     Download XSDs (ZIP)
      Note: The XSDs are backwards compatible.
   • Third parties will have the ability to change their registration to allow customers to select this data group during the time of authorization via the third party portal under manage registration >Edit > section: Indicate the customer information you require", select the Program Enrollment check box.
   •  Note: This will only apply to new customer authorizations.
     
   • New APIs to retrieve DR Enrollment information is available at the Bulk 3rd party level as well as at the individual customer authorization level (RetailCustomerID level), outlined per the following:
     Download new PGE Supported APIs (PDF)
   • Asynchronous API for requesting DR Enrollment information for all authorizations to a third party
     • https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/BulkRetailDRPrgInfo/{BulkID}
   • Synchronous API for requesting DR enrollment information at the individual customer authorization level
     • https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/RetailDRPrgInfo/{RetailCustomerID}

 Note: Besides the changes to the customer authorization process, other changes are also backwards compatible and are voluntary enhancements third parties can elect to support.

If you have any questions or need additional support, feel free to email sharemydata@pge.com.

What’s new:

1. Customers can now benefit from the streamlined Click-Through authorization process.
   • We’ve updated the details about how a customer can now share data with your company.
     Learn how customers share data with a company
     
      Note: These changes, particularly improvements to our authorization UI, have been optimized for mobile devices (e.g., phones or tablets).
   • Changes have been made to the manage authorization process accessible to customers through their PG&E online account:
     • A customer can still remove SAIDs from an existing authorization, extend the authorization end date and/or cancel the authorization at any time. However, to add additional SAIDs and/or change authorized data elements the existing authorization needs to be cancelled and a new authorization needs to be created.
2. If desired, third parties can now use this API for revoking individual customer authorizations using their third party Client Access Token (provided during initial SMD third party registration process) via a DELETE operation: https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Authorization/{AuthorizationID}
   
    Note 1: For PG&E’s implementation, the AuthorizationID parameter is the same value as the SubscriptionID.
   
    Note 2: The new API provides third parties the ability to revoke (cancel) an authorization. However, only customers themselves can remove SA IDs and/or update the authorization end date via our SMD manage authorization pages.
   
   Reminder: As with all API data requests, third parties must first request a new Token Pair (Client Access + Refresh Token) using their latest Refresh Tokens.
   
   Reminder of Token Expiration Periods:
   • Access Token:1hr
   • Client Access Token: 5 min
   • Corresponding Refresh Tokens: 1Yr
3. Third parties can now create multiple Share My Data (SMD) registrations using the same company name and Tax ID if needed. However, the display name (which customers see when authorizing) still needs to be unique.
   
    Note: All of the changes above are backwards compatible and are voluntary enhancements third parties can elect to support. Download supporting documents for this release:
   
   SUPPORTED_APIS.SMD_CLICK-THRU_1.0 (PDF)
   
   SUPPORTED_DATA_ELEMENTS_RETAILCUSTOMER.SMD_CLICK_THRU_1.0 (PDF)
   
   PGE_ESPI_DATA_MODEL.SMD_CLICK-THRU_1.0 (PDF)
   
   SUPPORTED_DATA_ELEMENTS_ESPIDERIVED.SMD_CLICK_THRU_1.0 (PDF)
   
   ESPI_XSDS (ZIP)

December 20, 2015

Required changes: the following SMD 2.0 updates require changes on the part of third parties.

1. In consideration of third parties with GBCMD (Green Button Connect My Data) implementations at multiple utilities besides just PG&E, we will be passing back the dataCustodianID (i.e., dataCustodianID=PGE) in the redirect to thirdPartyScopeSelectionScreenURI during the OAuth authorization sequence.
2. API requests that accept date parameters (e.g., batch request), must use Zulu data parameters (e.g., published-max/ published-min). Other date formats for the date parameters in API requests will not be supported.
   • APIs that accept date parameters are documented per the attached, Supported APIs.xlsx
3. Interval TOU indicators included with Interval metered electric usage data (as applicable, indicator of what TOU period each interval corresponds to)
   • Please reference the static Program ID Mappings detailing what each interval TOU enumeration corresponds to (e.g., 1 = Summer Peak etc.). (See attached, Supported Data Elements.xlsx)
4. The client_id as found in the dataCustodianScopeSelectionScreenURI (used for third party initiated OAuth) and provided in the Application Information Resource third parties request during Registration Testing is being updated to 5 digits if it's not already (e.g., adding leading zeros etc). In addition, the URL no longer includes '&verified=true' at the end. Third parties will need to update their URLs accordingly.
   • To elaborate, the dataCustodianScopeSelectionScreenURI looks as follows: https://sharemydataqa.pge.com/myAuthorization/?clientId=XXXX (XXXX is the clientID)
   • So a current clientID of 123 will change to something like 00123 meaning their new dataCustodianScopeSelectionScreenURI will be as follows:
     https://sharemydataqa.pge.com/myAuthorization/?clientId=00123 (old URL being as follows: https://sharemydataqa.pge.com/myAuthorization/?clientId=00123&verified=true)
5. Third parties registered as "ESP" or "Energy Service Provider" are changing to Standard User Type. There are no changes functionally, only in user type title. Distinguishing ESP user type (from Standard User type) is an un-necessary differentiation, causing confusion during the registration process without providing any differentiated functionality, hence it is being retired.

Optional Enhancements: The following changes are backwards compatible, and are voluntary enhancements third parties can elect to support.

1. Third parties will have the ability to automatically change/update their SSL certs which they originally provided during registration (e.g., when cert nears expiration) via the third party portal under manage registration >Edit > new section: SSL Certificate Information (Update option).
2. Third parties can register to receive authorized basic billing info, customer info, and gas data.  Both interval metered as well as non-interval metered customers will be eligible to authorize sharing of data for SMD 2.0. A high level summary of newly available data elements is as follows:
   • Billing Info: (for both Interval and non-interval metered SAs)
     • Rate schedule, billing $ totals, Tiered usage (as applicable), Demand (as applicable), TOU totals (as applicable)
     • Note: For authorized non-interval metered customers, third parties will only receive billing usage totals (i.e., in Usage Summary) and no interval usage reads (e.g., hourly/daily reads as they are not available)
   • Customer Info: (for both interval and non-interval metered SAs)
     • Customer Name, Service Address, Account ID, Service Agreement ID, Service Agreement service Start Date,
   • Interval Gas usage data: (interval metered gas SAs only)
     • Interval (i.e., daily) gas reads
   • New data elements are diagramed as per the attached, Supported Data Elements.xlsx
   • Associated relational data hierarchy is outlined in the attached, PGE ESPI Data Model.xlsx
   • Latest ESPI xml schema definitions (XSDs) used for these new data elements are per the attached XSDs. Note: the XSDs are backwards compatible:
     • espiDerived.xsd (Interval Usage and Billing Info)
     • retailcustomer.xsd (customer info)

Should you have any questions or need for additional support, please feel free to contact us at ShareMyData@pge.com.

December 18, 2015
 

Required changes: the following SMD 2.0 updates require changes on the part of those users accessing their own data:

1. API requests that accept date parameters (e.g., batch request), must use Zulu data parameters (e.g., published-max/ published-min). Other date formats for the date parameters in API requests will not be supported.
   • APIs that accept date parameters are documented per the attached, Supported APIs.xlsx
2. Interval Time of Use (TOU) indicators included with Interval metered electric usage data (as applicable, indicator of what TOU period each interval corresponds to)
   • Please reference the static Program ID Mappings detailing what each interval TOU enumeration corresponds to (e.g., 1 = Summer Peak etc.). (See attached, Supported Data Elements.xlsx)

Optional Enhancements: The following changes are backwards compatible, and are voluntary enhancements third parties can elect to support.

1. Self Access users will have the ability to automatically change/update their SSL certs which they originally provided during registration (e.g., when cert nears expiration) via the third party portal under manage registration > Edit > new section: SSL Certificate Information (Update option)
2. Self Access user registrations will be updated to include authorized basic billing info, customer info, and gas data. Both interval metered as well as non-interval metered Service Agreements will be eligible for (self) authorization for SMD 2.0 A high level summary of newly available data elements is as follows:
   • Billing Info: (for both Interval and non-interval metered SAs)
     • Rate schedule, billing $ totals, Tiered usage (as applicable), Demand (as applicable), TOU totals (as applicable)
     •  Note: For authorized non-interval metered customers, third parties will only receive billing usage totals (i.e., in Usage Summary) and no interval usage reads (e.g., hourly/daily reads as they are not available)
   • Customer Info: (for both interval and non-interval metered SAs)
     • Customer Name, Service Address, Account ID, Service Agreement ID, Service Agreement service Start Date,
   • Interval Gas usage data: (interval metered gas SAs only)
     • Interval (i.e., daily) gas reads
   • New data elements are diagramed as per the attached, Supported Data Elements.xlsx
   • Associated relational data hierarchy is outlined in the attached, PGE ESPI Data Model.xlsx
   • Latest ESPI xml schema definitions (XSDs) used for these new data elements are per the attached XSDs. Note: the XSDs are backwards compatible:
     • espiDerived.xsd (Interval Usage and Billing Info)
     • retailcustomer.xsd (customer info)

Should you have any questions or need for additional support, please feel free to contact us at ShareMyData@pge.com.

December 18, 2015
 

Required changes: the following SMD 2.0 updates require changes on the part of CCA implementations.

1. Ad hoc requests (e.g., for historical data), must be made using Zulu time date parameters. Other date formats for the date parameters in API requests will not be supported.
2. The daily bulk usage feed will begin to include basic billing info while the daily bulk customer feed will include additional customer info. This new data will be provided both for interval metered customers that they receive data for currently, as well as for non-interval metered customers in their territory for which they don't receive data currently. Lastly, interval usage values provided in the daily bulk usage feed will include interval TOU indicators where applicable. High level summary of new data elements is as follows:
   • Billing Info: (for both Interval and non-interval metered SAs)
     • Rate schedule, billing $ totals, Tiered usage (as applicable), Demand (as applicable), TOU totals (as applicable)
   • (Additional) Customer Info: (for both interval and non-interval metered SAs)
     • Customer Name, Service Address, Service Agreement service Start Date, Account ID
   • Interval TOU indicators included with Interval metered electric usage data (as applicable, indicator of what TOU period each interval corresponds to)
     • Please reference the static Program ID Mappings detailing what each interval TOU enumeration corresponds to (e.g., 1 = Summer Peak etc.). (See attached, Supported Data Elements.xlsx)
   • Latest ESPI xml schema definitions (XSDs) used for these new data elements are per the attached XSDs. Note, the XSDs are backwards compatible:
     • espiDerived.xsd (Interval Usage and Billing Info)
     • retailcustomer.xsd (Customer Info)
   • New data elements are diagramed as per the attached, Supported Data Elements.xlsx
   • Associated relational data hierarchy is outlined in the attached, PGE ESPI Data Model.xlsx

Optional Enhancements: The following changes are backwards compatible, and are voluntary enhancements third parties can elect to support.

1. CCA's can make ad hoc requests for customer information at: https://api.pge.com/GreenButtonConnect/espi/1_1/Batch/BulkRetailCustomerInfo/{BulkID} (returns latest snapshot of customer info at time of request), in addition to the daily notification received.
2. CCA's will have the ability to automatically change their SSL cert which they originally provided during registration (e.g., when the cert nears expiration) via the third party portal, under manage registration > Edit > new section: SSL Certificate Information (Update option)

Should you have any questions or need for additional support, please feel free to contact us at ShareMyData@pge.com.

August 21, 2015
 

What's new:

1. State param and resource URI changes in Oauth responses
   • As part of the OAuth authorization code request, the third party has the option to send in a state parameter which PG&E would send back to the third party. PG&E will also send the authorization code on successful completion of authorization. This optional state param can be used to help the third party identify where the request was initiated, and to tie the request back to the authorizations they initiated.
   • As part of the successful completion of token request, we share back resourceURI and authorizationURI separately from the token information. Currently these URIs are flipped and as part of this release we will be correcting that.

Fixed defects:

1. Default dates published-max and published-min
   Currently PG&E mandates the third party sends in published-min and published-max parameters in epoch seconds for each data request to tell PG&E the duration for which they are requesting data. We are implementing a change to handle requests for the following scenarios:
   • published-min and published-max values are missing
   • published-min and published-max values are in UTC
   • published-min and published-max values are in epoch seconds
   In the event that the parameters are missing, PG&E will return default dates, as opposed to error messages as returned prior to this change. Default, in our case, is one day's data for the date T-2. If the parameters are present and formatted correctly we will continue to honor the parameters.
2. Fix for dates in authorization xml
   Currently in the authorization xml we shared the published date and authorization date. These dates are in milliseconds as opposed to seconds which is the standard. We are fixing it to be sent back in epoch seconds instead of milliseconds.
3. Incorrect XML returned for /resource/Subscription/{id}/UsagePoint/{id}/MeterReading/{id}/IntervalBlock
   Currently we are returning incorrect response for the above resource level GET where the structure of the XML is incorrect and we are repeating entries for each interval instead of creating one single interval block for a 24 hour duration.
   
   This is being fixed and only a single interval block will be returned for a 24 interval block.

Questions or concerns? Please contact ShareMyData@pge.com.

• Customers authorize you to access their data via My Energy, their PG&E online account. For a detailed overview of how customers can authorize third parties or other entities to access their data, please view the Share My Data Third-Party Overview.

Go to authorization details

• Currently, there is no limit.

• Customers can either choose a specified amount of time for which you can access their data, or they can leave the authorization period open.
• Your application can check the end date of a customer authorization along with other authorization details by calling the authorization resource APIs (e.g., .../espi/1_1/resource/Authorization and/or.../espi/1_1/resource/Authorization/{AuthorizationID}).
• Alternatively, you can manually check authorization end dates by logging in to your account and selecting Manage Authorizations.

• If a customer chooses a defined period of authorization, then their authorization expires at the end of that time period. If they cancel the authorization, then their authorization expires the day after they cancel the authorization.
• If a customer chooses Indefinite as their authorization period, then their authorization does not expire. Note, in consideration of Rule 24 Demand Response Providers and other programs using Share My Data, after-the-fact corrections for previously authorized date ranges may be provided to third parties for up to three years after authorization expiration.
• See "How will data corrections be handled?" for further details on receiving corrections.

• Any PG&E customer with a currently active Service ID for gas or electric service can authorize you to access their data using the new Share My Data tool.

• Customers interested in participating in sharing their data via the Share My Data program are highly encouraged to register for a My Energy account. This will make the entire process more efficient and also gives them the capability to manage their authorizations online.
• Customers can sign up for a My Energy account during the authorization process.
• There is a manual process available to customers to obtain a Share My Data Authorization Form online and submit the completed form via email.
• For more information about the manual process, please contact us at ShareMyData@pge.com.

• Customers are required to make their own authorizations online through their PG&E online account. However, if they complete and sign the Share My Data Authorization form, then you may submit it to PG&E on their behalf.

Download Share My Data Customer Authorization or Revocation of Authorization form (PDF, 308 KB)

• You can update your OAuth URIs by logging into your account, navigating to Manage Registration > Edit > and updating the fields under the OAuth 2.0 Information section.

• You can update your Notification URI by logging into your account, navigating to Manage Registration > Edit > and updating the fields under the Data Access Information section.

• You can update your SSL certificate by logging into your account, navigating to Manage Registration > Edit > and selecting "Update" in the SSL Certificate Information section. Note that for new certificate uploads, it may take several days to update PG&E systems with the new certificate.  
• A confirmation email from the Share My Data Support team will be sent when the new certificate has been applied.

• Once you receive an email indicating your registration has been accepted, you will be able to log in to your Share My Data account and download our SSL Certificate via the Download PG&E SSL Certificate page.

Login to Share My Data

• Share My Data follows the Green Button Connect My Data implementation agreements. Share My Data also employs OAuth 2.0 for authorization, Transport Layer Security (TLS) 1.2 and the minimum suite of cyber security protocols approved by NIST (National Institute of Standards and Technology) such that no information is exchanged in the clear.

• Protecting customer information is a top priority for PG&E. PG&E treats information about their customers—including personal information—as confidential, consistent with all legal and regulatory requirements, including those established by the California Public Utilities Commission and others.  
• For more than two decades, PG&E and other investor-owned utilities in California have been subject to very strict CPUC regulations that prohibit them from disclosing customer-specific information, such as billing data, to third parties without the express consent of the customer.  
• Once a customer authorizes the release of data, it is the customer’s and third party’s responsibility to protect that data.
• A customer can elect to stop sharing data with a third party at any time by logging in to their PG&E online account and cancelling their authorization. PG&E’s complete privacy policy and Notice of Accessing, Collecting, Storing, Using and Disclosing Energy Usage Information is available at pge.com/privacy.

• Within the scope of the Share My Data program, Third parties are subject to the Customer Data Privacy and Protection Rules specified in the Share My Data platform terms and conditions and to the requirements included in the Customer Data Access Tariff.
• Third parties are also subject to all other applicable laws and regulations relating to the protection of customer privacy, including, but not limited to, the Rules Regarding Privacy and Security Protections for Energy Usage Data adopted by the CPUC as Attachment D to Decision 11-07-056 (Electric), also summarized in PG&E’s Electric Rule No. 27, and California Civil Code Section 1798.80 – 1798.84.
• For more information, please select the links, below:
  Share My Data terms and conditions (PDF)
  Electric Rule No. 27 (PDF)
  Attachment D to Decision 11-07-056 (PDF)
  Find more information: California Civil Code Section 1798.80 – 1798.84

• Please refer to the link, below, for a detailed list of the data elements that are supported.

Get more information about data access

• On occasion, interval usage data is missing because our upstream data validation processes find there are missing or incorrect data reads that may require further processing (editing and or estimation).
• For interval billed customers (e.g., customers with Time-of-Use billing considerations), these instances are corrected in time to ensure accurate bill calculation on their upcoming monthly bill.

• If you would like to receive data corrections, please ensure that you check the Notify Me as Data is Ready checkbox during registration or by logging in to your online account and selecting this checkbox under Edit Profile. We will then include data corrections that have been captured by our system during the previous 24 hours, as part of the daily usage feed, for any data you are authorized to access.
• Data corrections will cover any changes for the authorized period, up to a maximum of three years.

 Note: In consideration of Rule 24 Demand Response Providers and other programs using Share My Data, after-the-fact corrections for previously authorized date ranges may be provided to 3rd parties for up to three years after authorization expiration.

• If applicable, PG&E will send notifications to your notification URL provided during registration. Notifications comprise URLs corresponding to already pre-packaged 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 on the Data Access Page and scenario 2 is illustrated under the "DATA ACCESS: AD HOC REQUEST (ASYNCHRONOUS)" section of the same diagrams also on the Data Access Page.

Visit data access above

• The electric usage data provided by Share My Data is not Settlement Quality Meter Data (SQMD) as specified by the California Independent System Operator (CAISO). SQMD is generated by multiplying Revenue Quality Meter Data (RQMD) by the Distribution Loss Factor (DLF) applicable to that customer's voltage level for that interval, converting the metered intervals to the interval period required by the CAISO and then summing the results for each interval to the aggregate level required by the CAISO.
  
• PG&E is implementing flags of the "QualityOfReading" (QOR) Type provided by the ESPI standard to communicate whether data is Revenue Quality. The QOR Type captures different possible quality values for usage data, including an explicit value for “Revenue Quality Meter Data” or "RQMD." PG&E will use this QOR Type in its data transmittal as follows:
  • PG&E supports the ESPI provided "UsageSummary" class, which will be used to identify the dates for which a service agreement is billed, the billed usage amount, and the usage data quality at the time of request. The UsageSummary will be populated once the bill is available for the requested data and will include two flags (elements) of QOR Type:
    • The UsageSummary.QualityOfReading element (at the UsageSummary level) indicating the quality at the time of request of latest provided interval usage values plus corrections corresponding to the UsageSummary.billingPeriod dates.
    • The DefaultQuality element for OverallConsumptionLastPeriod (as part of UsageSummary.OverallConsumptionLastPeriod.ReadingTypeRef) indicating the quality of the total billed usage.
  • PG&E will also communicate the quality of usage data at the interval level at the time of request using the IntervalReading.ReadingQuality.Quality element.

• During registration you can select how much historical data you need, either 24, 36, or 48 months under the "How much historical data is requested" dropdown.
• As part of a customer's authorization allowing you to access their data, the historical period for authorization will be defaulted to your registration selection for the Service IDs (usage points) included in the authorization.
• You can update your requested historical data, by logging into to your account, navigating to Manage Registration > Edit > and selecting from the dropdown labeled "How much historical data is requested."
• Please note that the data provided in the historical request will begin with the date that the customer makes the authorization, as opposed to the date that you make the request to the API.

 Note: Changes to your requested historical data only affect new customer authorizations, while previous customer authorizations will reflect your selection at the time of authorization.

• As per the ESPI standard, the response uses the Atom Publishing Standard. Please select the link, below, to see a complete list of APIs that are supported, along with available data elements.

Get more information about data access

• Active electric and gas Service IDs installed and read by PG&E are eligible for authorization via the Share My Data platform.
• If the Service ID associated with an authorization changes due to one of the following reasons, the authorization will transition to the new Service ID and access to historical interval usage data will continue:
  • Temporary shut off due to non-payments
  • Move to Interval Billing
  • Exchange of meter
  • Rate change
• Other scenarios that result in a change in Service ID such as moving locations or the change of a company will terminate access. In addition, if an account is unlinked from your My Energy account, all underlying Service IDs that were authorized via Share My Data will be unauthorized as a result.

• To determine the granularity of authorized interval data, please reference the Interval Length element as provided by the ESPI standard.
• PG&E is providing interval usage data at the same granularity as collected for billing purposes, which is generally on an hourly or 15-minute basis for electric data and daily for gas data for those customers with interval meters. Whereas it can vary by customer, electric interval meter usage is generally available at the hourly level for most residential customers and at the 15-minute interval level for most commercial customers, and gas interval meter usage is generally available at the daily level for most customers.
• For non-interval meters, data will be provided when available.

• For the large majority of PG&E customers with a Smart Meter installed, electric and gas interval usage data is available by the end of the next day via the Share My Data platform.
• The small portion of PG&E electric customers with power line carrier based MV90 meters installed may require additional time for data to be available.

• While we cannot directly support setup of your APIs, we do have a number of resources available to assist your IT and technical resources in the development process. Please reference our API Documentation page to learn more. Please also feel free to contact ShareMyData@pge.com with any additional questions.

For more information, visit application programming interface (API)