Mapping Service-Location to a Metered Usage-Point

The Green Button Energy Usage information is designed with customer privacy as a top priority, so it intentionally omits Personally Identifiable Information (PII) when providing energy-usage information.  Despite this focus on privacy, certain applications—such as solar panel sales, installation services, and energy-reduction analytics—require collecting specific personal information.  The exact details required for this collection can vary depending on the application but typically, the precise location of the energy meter(s) is crucial to ensure accurate service delivery.  This page provides an in-depth explanation of how a meter’s location is reported following the Green Button standards, which ensures consistency and clarity.

To determine a meter’s location, we reference the Retail Customer data, specifically focusing on the <ServiceLocation>Cust details, which emphasize access and inspection information, including the meter’s address and associated <UsagePoint>Cust .  Each Retail Customer <UsagePoint>Cust entry within <UsagePoints>Cust (note the plurality of the collection called <UsagePoints>Cust ) includes a particular Uniform Resource Identifier (URI) that serves as a unique identifier to match to a particular <UsagePoint>ESPI within the <UsagePoints>Cust collection within the Energy Usage data.  By leveraging this URI of the Retail Customer <ServiceLocation>Cust , which corresponds to the href attribute within the Energy Usage data’s <link rel="self" href="{URI}"/> entry, we precisely identify which <UsagePoint>ESPI aligns with the <ServiceLocation>Cust address, ensuring accurate and reliable location mapping. 

Example

An example of a single <UsagePoint>ESPI Energy Usage entry: 

<!-- snippet from Energy Usage data file/stream  -->
  <entry>
    <id>urn:uuid:463e8f00-e483-5439-baae-1b718abba15c</id>
    <link rel="up" type="espi-feed/UsagePoint" href="https://data.greenbuttonconnect.org/DataCustodian/espi/1_1/resource/Subscription/04333b8b-e843-32e7-a41d-a1dca39d0fb3/UsagePoint"/>
    <link rel="self" type="espi-entry/UsagePoint" href="https://data.greenbuttonconnect.org/DataCustodian/espi/1_1/resource/Subscription/04333b8b-e843-32e7-a41d-a1dca39d0fb3/UsagePoint/463e8f00-e483-5439-baae-1b718abba15c"/>    
    <link rel="related" type="espi-entry/MeterReading" href="https://data.greenbuttonconnect.org/DataCustodian/espi/1_1/resource/Subscription/04333b8b-e843-32e7-a41d-a1dca39d0fb3/UsagePoint/463e8f00-e483-5439-baae-1b718abba15c/MeterReading/7ab1a5f5-8a85-52bb-85f1-40b16390f6a8"/>
    <link rel="related" type="espi-entry/UsageSummary" href="https://data.greenbuttonconnect.org/DataCustodian/espi/1_1/resource/Subscription/04333b8b-e843-32e7-a41d-a1dca39d0fb3/UsagePoint/463e8f00-e483-5439-baae-1b718abba15c/UsageSummary/3c219aab-c147-5897-a25c-636ac7a28691"/>
    <link rel="related" type="espi-entry/LocalTimeParameters" href="https://data.greenbuttonconnect.org/DataCustodian/espi/1_1/resource/LocalTimeParameters/EST-USA"/>
    <title>Usage Point</title>
    <content>
      <espi:UsagePoint>
        <espi:ServiceCategory>
          <espi:Kind>0</espi:kind>
        </espi:ServiceCategory>
      </espi:UsagePoint>
    </content>
    <published>2024-10-31T16:47:20Z</published>
    <updated>2024-10-31T16:47:20Z</updated>
  </entry>

Of particular note is this <link>Atom reference (from above but here, below, with line-breaks for readability), which denotes the href attribute content as being the unique identifier for itself (rel="self"):

<link rel="self" 
      type="espi-entry/UsagePoint" 
      href="https://data.greenbuttonconnect.org/DataCustodian/espi/1_1/resource/Subscription/04333b8b-e843-32e7-a41d-a1dca39d0fb3/UsagePoint/463e8f00-e483-5439-baae-1b718abba15c"/>

Its corresponding <ServiceLocation>Cust Retail Customer entry would then look like this:

<!-- snippet from Retail Customer data file/stream  -->
  <entry>
    <id>urn:uuid:fba8732a-c211-57bd-baf3-c69fff9e7a3f</id>  
    <link rel="up" type="espi-feed/ServiceLocation" href="https://data.greenbuttonconnect.org/DataCustodian/espi/1_1/resource/RetailCustomer/100045561/CustomerAgreement/7420931/ServiceLocation"/>
    <link rel="self" type="espi-entry/ServiceLocation" href="https://data.greenbuttonconnect.org/DataCustodian/espi/1_1/resource/RetailCustomer/100045561/CustomerAgreement/7420931/ServiceLocation/380443"/>    
    <link rel="related" type="espi-entry/Meter" href="https://data.greenbuttonconnect.org/DataCustodian/espi/1_1/resource/RetailCustomer/100045561/CustomerAgreement/7420931/ServiceLocation/380443/Meter/949100"/>
    <link rel="related" type="espi-ntry/LocalTimeParameters" href="https://data.greenbuttonconnect.org/DataCustodian/espi/1_1/resource/RetailCustomer/100045561/LocalTimeParameters/EST-USA"/>
    <link rel="related" type="espi-entry/CustomerAgreement" href="https://data.greenbuttonconnect.org/DataCustodian/espi/1_1/resource/RetailCustomer/100045561/CustomerAgreement/7420931"/>    
    <title>Service Location</title>
    <content>
      <cust:ServiceLocation>
        <cust:type>Geographical</cust:type>
        <cust:mainAddress>
          <cust:streetDetail>
            <cust:number>4747</cust:number>
            <cust:name>Fountain Way>/cust:name>
          </cust:streetDetail>
          <cust:townDetail>
            <cust:name>Oak Holly Drive</cust:name>
            <cust:county>Madison</cust:county>
            <cust:stateOrProvince>PA</cust:stateOrProvince>
          </cust:townDetail>
          <cust:postalCode>30338>/cust:postalCode>
        </cust:mainAddress>
        <cust:UsagePoints>
          <cust:UsagePoint>https://data.greenbuttonconnect.org/DataCustodian/espi/1_1/resource/Subscription/04333b8b-e843-32e7-a41d-a1dca39d0fb3/UsagePoint/463e8f00-e483-5439-baae-1b718abba15c</cust:UsagePoint>
        </cust:UsagePoints>
      </cust:ServiceLocation>
    </content>
    <published>2024-10-31T16:47:20Z</published>
    <updated>2024-10-31T16:47:20Z</updated>
  </entry>

Note the <cust:UsagePoint> element ( <UsagePoint>Cust ): 

        <cust:UsagePoints>
          <cust:UsagePoint>https://data.greenbuttonconnect.org/DataCustodian/espi/1_1/resource/Subscription/04333b8b-e843-32e7-a41d-a1dca39d0fb3/UsagePoint/463e8f00-e483-5439-baae-1b718abba15c</cust:UsagePoint>
        </cust:UsagePoints>

… where the unique URI href from the Energy Usage data is referenced:

“https://data.greenbuttonconnect.org/DataCustodian/espi/1_1/resource/Subscription/04333b8b-e843-32e7-a41d-a1dca39d0fb3/UsagePoint/463e8f00-e483-5439-baae-1b718abba15c”

This allows a Third Party’s application to map from the Retail Customer entry back to the Energy Usage entry’s <link rel="self" …  to-which it corresponds.

Need more help with this?  Check-out our Technical Education offerings.