Developers

The Green Button API provides flexible access to Energy Usage Information through a set of RESTful interfaces.

Green Button represents energy usage information as a set of resources as defined in the ESPI standard and uses RESTful 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) encapsulated within an Atom Feed.

</span></a>RetailCustomer, DataCustodian & ThirdParty Actors

Green Button allows data to be exchanged between Utilities, Customers, and Third Party Services Providers. It uses standard (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. </div>

Concepts

Green Button uses the Atom Syndication Format Standard to represent structured energy usage information in an XML format that may be exchanged on the internet. Both Google (GData) and Microsoft (OData) independently recognized the power of the Atom Syndication Format to encode complex data for exchange over RESTful web services. Green Button adopted these concepts in the construction of ESPI.

The resources defined within Green Button, UsagePoints, MeterReadings, etc, are expressed, in XML format, within the Atom feed's Entry tags. This results in a uniform way to expose full-featured data APIs that reference a Retail Customer's encapsulated Energy Usage Information.

Green Button works by placing data within the <entry> tags of the Atom stream. Data records are placed within the <entry> ... <content> tags, and relationships between tables are represented in the <link>tags.

The second thing to note is that in the Atom representation, a feed will always represent a collection of 1 or more Green Button resources:

<feed>
  ...
  <entry>
    ...
    <content>
      <espi-resource />
    </content>
  </entry>
  ...
</feed>

Relationships

So all the espiDerived.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://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint" rel="up"/>
      <link href="https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint/1" rel="self"/>
      <link href="https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint/1/MeterReading" rel="related"/>
      <link href="https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint/1/ElectricPowerUsageSummary" rel="related"/>
      <link href="https://services.greenbuttondata.org/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>

    
</div> </div>

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://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/ApplicationInformation" rel="up"/>
      <link href="https://services.greenbuttondata.org/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://services.greenbuttondata.org/ThirdParty/espi/1_1/Notification</espi:thirdPartyNotifyUri>
                  <espi:dataCustodianBulkRequestURI></espi:dataCustodianBulkRequestURI>
                  <espi:dataCustodianResourceEndpoint>https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource</espi:dataCustodianResourceEndpoint>
                  <espi:thirdPartyScopeSelectionScreenURI>https://services.greenbuttondata.org/ThirdParty/RetailCustomer/ScopeSelection</espi:thirdPartyScopeSelectionScreenURI>
                  <espi:client_secret>secret</espi:client_secret>
                  <espi:redirect_uri>https://services.greenbuttondata.org/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://services.greenbuttondata.org/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://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/Authorization" rel="up"/>
      <link href="https://services.greenbuttondata.org/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://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/Batch/Subscription/5</espi:resourceURI>
                  <espi:authorizationURI>https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/Authorization/5</espi:authorizationURI>
            </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://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint" rel="up"/>
      <link href="https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint/1" rel="self"/>
      <link href="https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint/1/MeterReading" rel="related"/>
      <link href="https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint/1/ElectricPowerUsageSummary" rel="related"/>
      <link href="https://services.greenbuttondata.org/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://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint/1/MeterReading" rel="up"/>
      <link href="https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint/1/MeterReading/1" rel="self"/>
      <link href="https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint/1/MeterReading/1/IntervalBlock" rel="related"/>
      <link href="https://services.greenbuttondata.org/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://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/ReadingType" rel="up"/>
      <link href="https://services.greenbuttondata.org/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://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint/1/MeterReading/1/IntervalBlock" rel="up"/>
      <link href="https://services.greenbuttondata.org/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://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/LocalTimeParameters" rel="up"/>
      <link href="https://services.greenbuttondata.org/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://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint/1/UsageSummary" rel="up"/>
      <link href="https://services.greenbuttondata.org/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. RESTful 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.