announcement

There has been a lapse in Environmental Protection Agency appropriations. EPA intends to keep the ENERGY STAR website, tools, and resources available, however they will not be updated regularly. If you submit a question, application, or request to EPA, it may not be processed during this period.

Web Service Documentation / Categories / Home Energy Yardstick Servces / Home Energy Yardstick

Home Energy Yardstick

Updated on September 15, 2020

Description

This web service returns a list of performance-based home assessment metrics for a specified home's design characteristics and energy use. Home Energy Yardstick Service does require user authentication but the home design information that you submit will not be saved for later reference.

The following meter types are only allowed:
         - Coal Bituminous
         - Electric
         - Fuel Oil No 2
         - Kerosene
         - Natural Gas
         - Propane
         - Wood

Version

25.0

HTTP Method

POST

Resource URL

/hey

Header

Field Name Value Comments
Authorization Basic credentials
Content-Type application/xml

Authorization Required

Yes

Parameters

None

XML Schemas

Request/Response Schema Name
Request hey.xsd
Response propertyMetrics.xsd

Example Request

The following example specifies a 1500 square foot property with 12 months of electric and natural gas energy data.

POST  /hey

<?xml version="1.0" encoding="UTF-8"?>
<hey>
     <propertyInfo>
          <postalCode>60304</postalCode>
          <numberOfOccupants>2</numberOfOccupants>
          <grossFloorArea units="Square Feet" temporary="false">
               <value>1500</value>
          </grossFloorArea>
     </propertyInfo>
     <meter>
          <type>Electric</type>
          <unitOfMeasure>kBtu (thousand Btu)</unitOfMeasure>
          <meterData>
               <meterConsumption>
                    <startDate>2019-01-01</startDate>
                    <endDate>2019-01-31</endDate>
                    <usage>4000</usage>
               </meterConsumption>
               <meterConsumption>
                    <startDate>2019-02-01</startDate>
                    <endDate>2019-02-28</endDate>
                    <usage>4000</usage>
               </meterConsumption>
               <meterConsumption>
                    <startDate>2019-03-01</startDate>
                    <endDate>2019-03-31</endDate>
                    <usage>4000</usage>
               </meterConsumption>
               <meterConsumption>
                    <startDate>2019-04-01</startDate>
                    <endDate>2019-04-30</endDate>
                    <usage>4000</usage>
               </meterConsumption>
               <meterConsumption>
                    <startDate>2019-05-01</startDate>
                    <endDate>2019-05-31</endDate>
                    <usage>4000</usage>
               </meterConsumption>
               <meterConsumption>
                    <startDate>2019-06-01</startDate>
                    <endDate>2019-06-30</endDate>
                    <usage>4000</usage>
               </meterConsumption>
               <meterConsumption>
                    <startDate>2019-07-01</startDate>
                    <endDate>2019-07-31</endDate>
                    <usage>4000</usage>
               </meterConsumption>
               <meterConsumption>
                    <startDate>2019-08-01</startDate>
                    <endDate>2019-08-31</endDate>
                    <usage>4000</usage>
               </meterConsumption>
               <meterConsumption>
                    <startDate>2019-09-01</startDate>
                    <endDate>2019-09-30</endDate>
                    <usage>4000</usage>
               </meterConsumption>
               <meterConsumption>
                    <startDate>2019-10-01</startDate>
                    <endDate>2019-10-31</endDate>
                    <usage>4000</usage>
               </meterConsumption>
               <meterConsumption>
                    <startDate>2019-11-01</startDate>
                    <endDate>2019-11-30</endDate>
                    <usage>4000</usage>
               </meterConsumption>
               <meterConsumption>
                    <startDate>2019-12-01</startDate>
                    <endDate>2019-12-31</endDate>
                    <usage>4000</usage>
               </meterConsumption>
          </meterData>
     </meter>
     <meter>
          <type>Natural Gas</type>
          <unitOfMeasure>kBtu (thousand Btu)</unitOfMeasure>
          <meterData>
               <meterConsumption>
                    <startDate>2019-01-01</startDate>
                    <endDate>2019-01-31</endDate>
                    <usage>2000</usage>
               </meterConsumption>
               <meterConsumption>
                    <startDate>2019-02-01</startDate>
                    <endDate>2019-02-28</endDate>
                    <usage>2000</usage>
               </meterConsumption>
               <meterConsumption>
                    <startDate>2019-03-01</startDate>
                    <endDate>2019-03-31</endDate>
                    <usage>2000</usage>
               </meterConsumption>
               <meterConsumption>
                    <startDate>2019-04-01</startDate>
                    <endDate>2019-04-30</endDate>
                    <usage>2000</usage>
               </meterConsumption>
               <meterConsumption>
                    <startDate>2019-05-01</startDate>
                    <endDate>2019-05-31</endDate>
                    <usage>2000</usage>
               </meterConsumption>
               <meterConsumption>
                    <startDate>2019-06-01</startDate>
                    <endDate>2019-06-30</endDate>
                    <usage>2000</usage>
               </meterConsumption>
               <meterConsumption>
                    <startDate>2019-07-01</startDate>
                    <endDate>2019-07-31</endDate>
                    <usage>2000</usage>
               </meterConsumption>
               <meterConsumption>
                    <startDate>2019-08-01</startDate>
                    <endDate>2019-08-31</endDate>
                    <usage>2000</usage>
               </meterConsumption>
               <meterConsumption>
                    <startDate>2019-09-01</startDate>
                    <endDate>2019-09-30</endDate>
                    <usage>2000</usage>
               </meterConsumption>
               <meterConsumption>
                    <startDate>2019-10-01</startDate>
                    <endDate>2019-10-31</endDate>
                    <usage>2000</usage>
               </meterConsumption>
               <meterConsumption>
                    <startDate>2019-11-01</startDate>
                    <endDate>2019-11-30</endDate>
                    <usage>2000</usage>
               </meterConsumption>
               <meterConsumption>
                    <startDate>2019-12-01</startDate>
                    <endDate>2019-12-31</endDate>
                    <usage>2000</usage>
               </meterConsumption>
          </meterData>
     </meter>
</hey>

Example Response

The following example shows the calculated metrics for the specified home.

<?xml version="1.0" encoding="UTF-8"?>
<propertyMetrics month="12" year="2019">
     <metric name="sourceTotal" uom="kBtu" dataType="numeric">
          <value>159600.0</value>
     </metric>
     <metric name="siteEnergyUseElectricityGridPurchase" uom="kBtu" dataType="numeric">
          <value>48000.0</value>
     </metric>
     <metric name="siteEnergyUseNaturalGas" uom="kBtu" dataType="numeric">
          <value>24000.0</value>
     </metric>
     <metric name="score" dataType="numeric">
          <value>35</value>
     </metric>
     <metric name="n/a" dataType="string">
          <value>60304</value>
     </metric>
     <metric name="coolingDegreeDaysCDD" uom="°F" dataType="numeric">
          <value>1074.0</value>
     </metric>
     <metric name="heatingDegreeDaysHDD" uom="°F" dataType="numeric">
          <value>6126.0</value>
     </metric>
     <metric name="singleFamilyHomeNumberOfPeople" dataType="numeric">
          <value>2.00</value>
     </metric>
     <metric name="nonTimeWeightedFloorArea" uom="ft²" dataType="numeric">
          <value>1500.0</value>
     </metric>
     <metric name="scoreMotivationText" dataType="string">
          <value>Consider taking action to reduce your home's energy use. You could save about  $210 per year by improving your score to a 50, the average U.S. home score.</value>
     </metric>
</propertyMetrics>
LIVE