Green Button Alliance Logo

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.

✏️ Note:  If you are, instead, interested in knowing how to provide Aggregated Data from many meters as a single, virtual meter, you can read more about Aggregated Data with Green Button on that Developer Resources page. 

     

Determining a Meter’s Location

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>) 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 with the kind of service represented: 

<!-- 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>  <!-- “Electricity service.” -->
        </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 (https://data.greenbutton...) as being the unique identifier for itself (<link 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>4321</cust:number>
            <cust:name>Main Blvd</cust:name>
            <cust:suffix>Northwest</cust:suffix>
            <cust:prefix>North</cust:prefix>
            <cust:type>boulevard</cust:type>
            <cust:code>RTE-212</cust:code>
            <cust:buildingName>The Triumph Centre</cust:buildingName>
            <cust:suiteNumber>Apt 987</cust:suiteNumber>
            <cust:addressGeneral>4321 N MAIN BLVD NW APT 987</cust:addressGeneral>
            <cust:addressGeneral2>TRIUMPH CENTRE APARTMENTS</cust:addressGeneral2>
            <cust:addressGeneral2>CITYVILLE  DC 00321</cust:addressGeneral2>
            <cust:withinTownLimits>true</cust:withinTownLimits>
          </cust:streetDetail>
          <cust:townDetail>
            <cust:code>PDQ8ASAP</cust:code>
            <cust:section>36</cust:section>
            <cust:name>Cityville</cust:name>
            <cust:county>Madison</cust:county>
            <cust:stateOrProvince>DC</cust:stateOrProvince>
            <cust:stateOrProvince>United States</cust:stateOrProvince>
          </cust:townDetail>
          <cust:postalCode>00321</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.