Web Service Documentation / Categories / Home Energy Yardstick Servces / Home Energy Yardstick
Updated on September 15, 2020
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
24.0
POST
/hey
Field Name | Value | Comments |
---|---|---|
Authorization | Basic credentials | |
Content-Type | application/xml |
Yes
None
Request/Response | Schema Name |
---|---|
Request | hey.xsd |
Response | propertyMetrics.xsd |
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>
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>