Developers

The Green Button API provides flexible access to Energy Usage Information (EUI) and Personal Identifiable Information (PII) through a set of REST interfaces.

Green Button represents energy usage and personal identifiable information as a set of resources, as defined in the NAESB REQ.21 ESPI standard and uses REST APIs to provide standard access to information for metered resources, such as electricity, gas, and water. These interfaces may be used to access and manage the metered data by using atom+xml based streams of Energy Usage Information (EUI) and Personal Identifiable Information (PII) encapsulated within an Atom Feed.

RetailCustomer, DataCustodian & ThirdParty Actors

Green Button allows data to be exchanged between Utilities, Customers, and Third Party Services Providers. It uses standard Secured HTTP based messaging to accomplish these exchanges. So, starting with the Green Button Actors:

RetailCustomer
Any person or enterprise that is provided services such as electricity, water, or gas from a resource service provider. RetailCustomers may be residential, commercial, or industrial.
DataCustodian
Any enterprise that is holding metered data obtained during the course of providing resources to a RetailCustomer. A DataCustodian holds that data as part of the service they provide and may, with the authorization of the RetailCustomer, allow that data to be shared with a third party.
ThirdParty
Any person or enterprise that is authorized to have access to metered data held by a DataCustodian. A ThirdParty, when authorized, may subscribe to a RetailCustomer's data and provide additional services as desired.

Relationships between the Actors

The Actors enter into relationships as depicted in the diagram above. The simplest relationship is the one that exists between the DataCustodian (i.e. the Utility) and their customer (the RetailCustomer). This relationship allows the RetailCustomer to download a file that contains their resource usage information. This simple relationship is the basis for the Green Button Download My Data operation.

Concepts

Green Button uses the Atom Syndication Format Standard to represent structured energy usage information and retail customer data in an XML format. The power of the Atom Syndication Format to encode complex data for exchange over REST web services, were independently recognized by both the GData (Google) and OData (Microsoft) standards. Based on this fact, the Green Button Alliance OpenADE Task Force, previously the UCAIug OpenADE Task Force, adopted this construct in the development of the Energy Service Provide Interface (ESPI).

The high-level structure of an Atom Syndication Format data stream/file is shown below:

<feed>
  urn:uuid:....
  Green Button Usage Feed
  yyyy-MM-ddTHH:mm:ssZ
   rel="self" href="https://..."</link>
  <entry>
    urn:uuid:....
     rel="up" href="https://..."</link>
     rel="self" href="https://..."</link>
     rel="related" href="https://..."</link>
     rel="related" href="https://..."</link>            
    <content>
      <espi-resource />
    </content>
    yyyy-MM-ddTHH:mm:ssZ
    yyyy-MM-ddTHH:mm:ssZ    
  </entry>
  ...
</feed>

An Atom data stream/file contains <feed>, <entry>, <id>, <link>, <content>, <published> and <updated> tags. The <feed>, <entry> and <content> tags create containers of information. Green Button resources (UsagePoints, MeterReadings, CustomerAccount, etc) are expressed in XML format within the Atom feed's <entry> ... tags. Data records are placed within the <entry> ... <content> tags, and relationships between tables are represented in the <link>tags. The result is a uniform way to express full-featured data API responses that reference a Retail Customer's encapsulated Energy Usage and Retail Customer information. Atom feeds always represent a collection of one or more Green Button resources.

Green Button resources:

Relationships

So all the usage.xsd entities may be contained in a feed and the entry/contents describe the ESPI entity itself. In addition, you need to construct (during the parse if possible for you) the associations that need to exist between the ESPI entities. The <link> tags are quite important for use during parsing of the Green Button data. These links allow you to know which MeterReadings are related to a specific UsagePoint.

Within an <entry>, the "related" links point to a collection, for example:

<entry xmlns:espi="http://naesb.org/espi" xmlns="http://www.w3.org/2005/Atom">
      <id>urn:uuid:c8c34b3a-d175-447b-bd00-176f60194de0</id>
      <link href="https://sandbox.greenbuttonalliance.org:8443/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint" rel="up"/>
      <link href="https://sandbox.greenbuttonalliance.org:8443/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint/1" rel="self"/>
      <link href="https://sandbox.greenbuttonalliance.org:8443/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint/1/MeterReading" rel="related"/>
      <link href="https://sandbox.greenbuttonalliance.org:8443/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint/1/ElectricPowerUsageSummary" rel="related"/>
      <link href="https://sandbox.greenbuttonalliance.org:8443/DataCustodian/espi/1_1/resource/LocalTimeParameters/1" rel="related"/>
      <title>Green Button Sample Data File</title>
      <content>
            <espi:UsagePoint>
                  <espi:ServiceCategory>
                        <espi:kind>0</espi:kind>
                  </espi:ServiceCategory>
            </espi:UsagePoint>
      </content>
      <published>2013-09-19T04:00:00Z</published>
      <updated>2013-09-19T04:00:00Z</updated>
<entry>

Green Button Resources

A DataCustodian will, when authorized by a RetailCustomer, publish a GreenButton data stream. A ThirdParty may then subscribe to that stream. Green Button uses the OAuth 2.0 Authorization Framework protocol to provide secure authorization for accessing the published data stream.

Green Button APIs are designed to support data flows that are both large and small. Many Utilities will schedule bulk transfers of hundreds of thousands of 24-hour data sets as a batch process. In this case, the Green Button APIs must be able to accommodate blocked transfers, recovery, and restarts. Other use-cases are driven more by frequent transmissions of smaller data sets, for example the hourly usage of a single outlet in your home. Green Button is designed to handle both!

ApplicationInformation

<entry xmlns:espi="http://naesb.org/espi" xmlns="http://www.w3.org/2005/Atom">
      <id>urn:uuid:af6e8b03-0299-467e-972a-a883ecdcc575</id>
      <link href="https://sandbox.greenbuttonalliance.org:8443/DataCustodian/espi/1_1/resource/ApplicationInformation" rel="up"/>
      <link href="https://sandbox.greenbuttonalliance.org:8443/DataCustodian/espi/1_1/resource/ApplicationInformation/2" rel="self"/>
      <title>GreenButtonData.org  ThirdParty Application</title>
      <content>
            <espi:ApplicationInformation>
                  <espi:dataCustodianId>data_custodian</espi:dataCustodianId>
                  <espi:dataCustodianApplicationStatus>1</espi:dataCustodianApplicationStatus>
                  <espi:thirdPartyNotifyUri>https://sandbox.greenbuttonalliance.org:8443/ThirdParty/espi/1_1/Notification</espi:thirdPartyNotifyUri>
                  <espi:dataCustodianBulkRequestURI></espi:dataCustodianBulkRequestURI>
                  <espi:dataCustodianResourceEndpoint>https://sandbox.greenbuttonalliance.org:8443/DataCustodian/espi/1_1/resource</espi:dataCustodianResourceEndpoint>
                  <espi:thirdPartyScopeSelectionScreenURI>https://sandbox.greenbuttonalliance.org:8443/ThirdParty/RetailCustomer/ScopeSelection</espi:thirdPartyScopeSelectionScreenURI>
                  <espi:client_secret>secret</espi:client_secret>
                  <espi:redirect_uri>https://sandbox.greenbuttonalliance.org:8443/ThirdParty/espi/1_1/OAuthCallBack</espi:redirect_uri>
                  <espi:client_id>third_party</espi:client_id>
                  <espi:contacts>john.teeter@energyos.org,martin.burns@nist.gov,donald.coffin@reminetworks.com</espi:contacts>
                  <espi:token_endpoint_auth_method>client_secret_basic</espi:token_endpoint_auth_method>
                  <espi:scope>FB=4_5_15;IntervalDuration=900;BlockDuration=monthly;HistoryLength=13</espi:scope>
                  <espi:scope>FB=4_5_15;IntervalDuration=3600;BlockDuration=monthly;HistoryLength=13</espi:scope>
                  <espi:scope>FB=4_5_12_15_16;IntervalDuration=3600;BlockDuration=monthly;HistoryLength=13</espi:scope>
                  <espi:grant_types>refresh_token</espi:grant_types>
                  <espi:grant_types>authorization_code</espi:grant_types>
                  <espi:dataCustodianScopeSelectionScreenURI>https://sandbox.greenbuttonalliance.org:8443/DataCustodian/RetailCustomer/ScopeSelectionList</espi:dataCustodianScopeSelectionScreenURI>
            </espi:ApplicationInformation>
      </content>
      <published>2014-01-02T10:00:00Z</published>
      <updated>2014-01-02T10:00:00Z</updated>
</entry>

Authorization

<entry xmlns:espi="http://naesb.org/espi" xmlns="http://www.w3.org/2005/Atom">
      <id>urn:uuid:bdcb34c0-7afd-4812-b30c-0d90fbeab936</id>
      <link href="https://sandbox.greenbuttonalliance.org:8443/DataCustodian/espi/1_1/resource/Authorization" rel="up"/>
      <link href="https://sandbox.greenbuttonalliance.org:8443/DataCustodian/espi/1_1/resource/Authorization/5" rel="self"/>
      <content>
            <espi:Authorization>
                  <espi:authorizedPeriod>
                        <espi:duration>0</espi:duration>
                        <espi:start>0</espi:start>
                  </espi:authorizedPeriod>
                  <espi:publishedPeriod>
                        <espi:duration>0</espi:duration>
                        <espi:start>0</espi:start>
                  </espi:publishedPeriod>
                  <espi:status>1</espi:status>
                  <espi:expires_at>31535999</espi:expires_at>
                  <espi:scope>FB=4_5_15;IntervalDuration=900;BlockDuration=monthly;HistoryLength=13</espi:scope>
                  <espi:token_type>Bearer</espi:token_type>
                  <espi:resourceURI>https://sandbox.greenbuttonalliance.org:8443/DataCustodian/espi/1_1/resource/Batch/Subscription/5</espi:resourceURI>
                  <espi:authorizationURI>https://sandbox.greenbuttonalliance.org:8443/DataCustodian/espi/1_1/resource/Authorization/5</espi:authorizationURI>
                  <espi:retailCustomerURI>https://sandbox.greenbuttonalliance.org:8443/DataCustodian/espi/1_1/resource/Batch/RetailCustomer/5</espi:retailCustomerURI>
            </espi:Authorization>
      </content>
      <published>2014-09-03T06:39:45Z</published>
      <updated>2014-09-03T06:39:45Z</updated>
</entry>

UsagePoint

A UsagePoint is where a resource is measured. Typically, it is your Utility Smart Meter, but it could be the outlet on the wall as well. UsagePoints provide the reference for all meter readings that are contained within the Green Button data. UsagePoints have a ServiceCategory that defines what kind of resource — such as an electricity, gas, or water measurement — is being reported. 

<entry xmlns:espi="http://naesb.org/espi" xmlns="http://www.w3.org/2005/Atom">
      <id>urn:uuid:c8c34b3a-d175-447b-bd00-176f60194de0</id>
      <link href="https://sandbox.greenbuttonalliance.org:8443/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint" rel="up"/>
      <link href="https://sandbox.greenbuttonalliance.org:8443/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint/1" rel="self"/>
      <link href="https://sandbox.greenbuttonalliance.org:8443/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint/1/MeterReading" rel="related"/>
      <link href="https://sandbox.greenbuttonalliance.org:8443/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint/1/ElectricPowerUsageSummary" rel="related"/>
      <link href="https://sandbox.greenbuttonalliance.org:8443/DataCustodian/espi/1_1/resource/LocalTimeParameters/1" rel="related"/>
      <title>Green Button Sample Data File</title>
      <content>
            <espi:UsagePoint>
                  <espi:ServiceCategory>
                        <espi:kind>0</espi:kind>
                  </espi:ServiceCategory>
            </espi:UsagePoint>
      </content>
      <published>2013-09-19T04:00:00Z</published>
      <updated>2013-09-19T04:00:00Z</updated>
</entry>

MeterReading

A MeterReading is a container for all of the measured IntervalBlocks within the Green Button data captured at a UsagePoint.

<entry xmlns:espi="http://naesb.org/espi" xmlns="http://www.w3.org/2005/Atom">
      <id>urn:uuid:4234ae39-fb6d-48ca-8856-ac9f41fb3d34</id>
      <link href="https://sandbox.greenbuttonalliance.org:8443/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint/1/MeterReading" rel="up"/>
      <link href="https://sandbox.greenbuttonalliance.org:8443/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint/1/MeterReading/1" rel="self"/>
      <link href="https://sandbox.greenbuttonalliance.org:8443/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint/1/MeterReading/1/IntervalBlock" rel="related"/>
      <link href="https://sandbox.greenbuttonalliance.org:8443/DataCustodian/espi/1_1/resource/ReadingType/1" rel="related"/>
      <title>Monthly Electricity Consumption</title>
      <content>
            <espi:MeterReading/>
      </content>
      <published>2013-09-19T04:00:00Z</published>
      <updated>2013-09-19T04:00:00Z</updated>
</entry>

ReadingType

A ReadingType provides detail as to the specifics of the reading data that is being obtained. Green Button follows international standards and has the ability to represent large industrial resources as well as those used in a residence.

<entry xmlns:espi="http://naesb.org/espi" xmlns="http://www.w3.org/2005/Atom">
      <id>urn:uuid:99b292fc-55f7-4f27-a3b9-cddab97cca90</id>
      <link href="https://sandbox.greenbuttonalliance.org:8443/DataCustodian/espi/1_1/resource/ReadingType" rel="up"/>
      <link href="https://sandbox.greenbuttonalliance.org:8443/DataCustodian/espi/1_1/resource/ReadingType/1" rel="self"/>
      <title>Type of Meter Reading Data</title>
      <content>
            <espi:ReadingType>
                  <espi:accumulationBehaviour>4</espi:accumulationBehaviour>
                  <espi:commodity>1</espi:commodity>
                  <espi:currency>840</espi:currency>
                  <espi:dataQualifier>12</espi:dataQualifier>
                  <espi:flowDirection>1</espi:flowDirection>
                  <espi:intervalLength>86400</espi:intervalLength>
                  <espi:kind>12</espi:kind>
                  <espi:phase>769</espi:phase>
                  <espi:powerOfTenMultiplier>0</espi:powerOfTenMultiplier>
                  <espi:timeAttribute>0</espi:timeAttribute>
                  <espi:uom>72</espi:uom>
            </espi:ReadingType>
      </content>
      <published>2013-09-19T04:00:00Z</published>
      <updated>2013-09-19T04:00:00Z</updated>
</entry>

IntervalBlock

IntervalBlocks are the primary data carrier within the Green Button data. IntervalBlocks may have one or more Intervals, each with a start and duration, as well as the specific IntervalReading

<entry xmlns:espi="http://naesb.org/espi" xmlns="http://www.w3.org/2005/Atom">
      <id>urn:uuid:e0383570-16b1-4ab9-8642-fdb7e89660db</id>
      <link href="https://sandbox.greenbuttonalliance.org:8443/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint/1/MeterReading/1/IntervalBlock" rel="up"/>
      <link href="https://sandbox.greenbuttonalliance.org:8443/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint/1/MeterReading/1/IntervalBlock/1" rel="self"/>
      <title></title>
      <content>
            <espi:IntervalBlock>
                  <espi:interval>
                        <espi:duration>2678400</espi:duration>
                        <espi:start>1357016400</espi:start>
                  </espi:interval>
                  <espi:IntervalReading>
                        <espi:cost>256347</espi:cost>
                        <espi:timePeriod>
                              <espi:duration>86400</espi:duration>
                              <espi:start>1357016400</espi:start>
                        </espi:timePeriod>
                        <espi:value>21021</espi:value>
                  </espi:IntervalReading>
                  <espi:IntervalReading>
                        <espi:cost>256347</espi:cost>
                        <espi:timePeriod>
                              <espi:duration>86400</espi:duration>
                              <espi:start>1357102800</espi:start>
                        </espi:timePeriod>
                        <espi:value>21021</espi:value>
                  </espi:IntervalReading>
                  ...
                  <espi:IntervalReading>
                        <espi:cost>256347</espi:cost>
                        <espi:timePeriod>
                              <espi:duration>86400</espi:duration>
                              <espi:start>1359608400</espi:start>
                        </espi:timePeriod>
                        <espi:value>21021</espi:value>
                  </espi:IntervalReading>
            </espi:IntervalBlock>
      </content>
      <published>2013-02-01T05:00:00Z</published>
      <updated>2013-02-01T05:00:00Z</updated>
</entry>

LocalTimeParameters

The LocalTimeParameters provide a flexible manner to enable Energy Usage Information (EUI) to be provided with a reference to local time, without including any Personally Identifiable Information. 

<entry xmlns:espi="http://naesb.org/espi" xmlns="http://www.w3.org/2005/Atom">
      <id>urn:uuid:e30ce77d-ec22-4da5-83c2-991ba34c97d6</id>
      <link href="https://sandbox.greenbuttonalliance.org:8443/DataCustodian/espi/1_1/resource/LocalTimeParameters" rel="up"/>
      <link href="https://sandbox.greenbuttonalliance.org:8443/DataCustodian/espi/1_1/resource/LocalTimeParameters/1" rel="self"/>
      <title>DST For North America</title>
      <content>
            <espi:LocalTimeParameters>
                  <espi:dstEndRule>B40E2000</espi:dstEndRule>
                  <espi:dstOffset>3600</espi:dstOffset>
                  <espi:dstStartRule>360E2000</espi:dstStartRule>
                  <espi:tzOffset>-18000</espi:tzOffset>
            </espi:LocalTimeParameters>
      </content>
      <published>2013-09-19T04:00:00Z</published>
      <updated>2013-09-19T04:00:00Z</updated>
</entry>

UsageSummary

<entry xmlns:espi="http://naesb.org/espi" xmlns="http://www.w3.org/2005/Atom">
      <id>urn:uuid:923a7143-263e-421b-bea2-e41b7e240013</id>
      <link href="https://sandbox.greenbuttonalliance.org:8443/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint/1/UsageSummary" rel="up"/>
      <link href="https://sandbox.greenbuttonalliance.org:8443/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint/1/UsageSummary/1" rel="self"/>
      <title>Usage Summary</title>
      <content>
            <espi:UsageSummary>
                  <espi:billingPeriod>
                        <espi:duration>2419200</espi:duration>
                        <espi:start>1391230800</espi:start>
                  </espi:billingPeriod>
                  <espi:billLastPeriod>6752000</espi:billLastPeriod>
                  <espi:billToDate>4807000</espi:billToDate>
                  <espi:costAdditionalLastPeriod>0</espi:costAdditionalLastPeriod>
                  <espi:currency>840</espi:currency>
                  <espi:overallConsumptionLastPeriod>
                        <espi:powerOfTenMultiplier>0</espi:powerOfTenMultiplier>
                        <espi:uom>72</espi:uom>
                        <espi:value>625716</espi:value>
                  </espi:overallConsumptionLastPeriod>
                  <espi:currentBillingPeriodOverAllConsumption>
                        <espi:powerOfTenMultiplier>0</espi:powerOfTenMultiplier>
                        <espi:timeStamp>1395374400</espi:timeStamp>
                        <espi:uom>72</espi:uom>
                        <espi:value>447993</espi:value>
                  </espi:currentBillingPeriodOverAllConsumption>
                  <espi:qualityOfReading>14</espi:qualityOfReading>
                  <espi:statusTimeStamp>1395374400</espi:statusTimeStamp>
            </espi:UsageSummary>
      </content>
      <published>2014-03-01T05:00:00Z</published>
      <updated>2014-03-01T05:00:00Z</updated>
</entry>

ElectricPowerQualitySummary

<?xml version="1.0" encoding="UTF-8"?>
<entry xml:lang="en-us" xsi:schemaLocation="http://naesb.org/espi espiDerived.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.w3.org/2005/Atom" xmlns:espi="http://naesb.org/espi">
  <id>urn:uuid:DEB0A337-C1B5-4658-99BA-4688E253A99B</id>
  <link rel="self" href="Subscription/9b6c7063/ElectricPowerQualitySummary/01"/>
  <link rel="up" type="" href="Subscription/9b6c7063/UsagePoint/01/ElectricPowerQualitySummary"/>
  <title>Quality Summary</title>
  <content>
    <ElectricPowerQualitySummary xmlns="http://naesb.org/espi">
      <flickerPlt>1</flickerPlt>
      <flickerPst>2</flickerPst>
      <harmonicVoltage>3</harmonicVoltage>
      <longInterruptions>4</longInterruptions>
      <mainsVoltage>5</mainsVoltage>
      <measurementProtocol>6</measurementProtocol>
      <powerFrequency>7</powerFrequency>
      <rapidVoltageChanges>8</rapidVoltageChanges>
      <shortInterruptions>9</shortInterruptions>
      <summaryInterval>
        <duration>2119600</duration>
        <start>2330578000</start>
      </summaryInterval>
      <supplyVoltageDips>10</supplyVoltageDips>
      <supplyVoltageImbalance>11</supplyVoltageImbalance>
      <supplyVoltageVariations>12</supplyVoltageVariations>
      <tempOvervoltage>13</tempOvervoltage>
    </ElectricPowerQualitySummary>
  </content>
  <published>2012-10-24T00:00:00Z</published>
  <updated>2012-10-24T00:00:00Z</updated>
</entry>

Samples and Sandboxes

Download My Data
A RetailCustomer may download an XML file from either a Data Custodian or a Third Party. REST interfaces are provided to enable this operation. There are no assumptions made with respect to what the RetailCustomer might do with this XML file, although best practices would be to ensure the file is viewable using a minimal style sheet.
Connect My Data
The RetailCustomer may also authorize Green Button data to move between two machines, such as from their utility to a company that might use the data to estimate the energy efficiency of their facility. In this case, Connect My Data would be used to provide machine-to-machine data transfers. Connect My Data may provide a single transfer of information, or transfers on a predefined schedule.