Mapping Service-Location to a Metered Usage-Point
cust:ServiceLocation & espi:UsagePoint
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>
details, which emphasize access and inspection information, including the meter’s address and associated <UsagePoint>
. Each Retail Customer <UsagePoint>
entry within <UsagePoints>
(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>
within the <UsagePoints>
collection within the Energy Usage data. By leveraging this URI of the Retail Customer <ServiceLocation>
, which corresponds to the href
attribute within the Energy Usage data’s <link rel="self" href="{URI}"/>
entry, we precisely identify which <UsagePoint>
aligns with the <ServiceLocation>
address, ensuring accurate and reliable location mapping.
Example
An example of a single <UsagePoint>
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>
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>
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: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.