EnergyIQ: Action-Oriented Benchmarking WebServices System

1. Introduction
1. What are Web Services?
2. Why is EnergyIQ providing Web Services?
3. How can I use these Web Services?
4. Contact information
2. Parameter Documentation
1. User License Key
2. Peer Group Data Set
3. Building Type
4. Building Vintage
5. Building Location
6. Building Size
7. Metrics (Energy Profile)
8. Indicators (Measurement Units)
9. Views (Plot type)
10. Versioning
3. Input Signatures
4. Output XML

• Introduction
• What are Web Services?

Take a look here and here for detailed discussion on what a Web Service is.

In short, it is the programmatic exchange of information between to hosts on the internet without any associated presentation.

• Why is EnergyIQ providing Web Services?

As part of the project scope of EnergyIQ, it was desired that information that is used in Benchmarking and Action Analysis be made available to other entities looking to leverage existing EnergyIQ functionality or get raw data for later processing & presentation.

To this end, EnergyIQ is providing a 'faceless' interface to its information and processing techniques.

• How can I use these Web Services?

Those wishing to access the web services via APIs so as to construct novel user interfaces or otherwise process the data in different fashions may do so through LBNL's licensing process. As these are 'read only' there is no way for the consumer to modify existing data.

The current APIs allow access to EnergyIQ's benchmarking functionality at the individual building level. In the future, other features such as portfolio-level benchmarking, features-based benchmarking, the superimposition of a specific user's own data, and recommended energy-efficiency actions will be supported. Benchmarking can currently be performed using two datasets (one for California and one for the entire United States). Future releases will also provide access to anonymized benchmarking data from individual EnergyIQ users.

• Contact information

For information about licensing these web services, contact the Project Leader, Evan Mills,

For technical support using these web services, contact us at Energy IQ API

• Parameter documentation

In order to access the current release of EnergyIQ's Benchmark web service, you will need to know the required parameters and their valid values (see below). Later versions will have all of this encapsulated in a WSDL document. Therefore your WSDL generator of choice will automatically encode this information in its object generation.

The order of IDs in a given parameter are not important.

• User License Key

Parameter Name: [license_key]

In order to use this Web Service, consumers of EnergyIQ information must be licensed before using. See above regarding licensing. Once licensed, you will receive a key that will be required for each Web Service call.

• Peer Group Dataset

Parameter Name: [data_set]

EnergyIQ exposes Benchmarking support for both CEUS (California) and CBECS (US-wide) datasets. Users need to declare which dataset they wish to benchmark against. Users may choose only one of these for a given WebService call.

Keep in mind that each dataset has it's own unique parameter values. So be careful when building parameter lists.

Dataset
ID	Cannonical Name
CEUS	California—only peer dataset
CBECS	National peer dataset

• Building Type

Parameter Name: [site_code]

If you want to obtain Benchmarking results for a high-level Building Category, you must provide all the individual sub-category building IDs.

For example, in order to examine all the types of food service facilities in the CEUS "Restraunts" category, you must construct the parameter argument as:

&site_code=21,23,25,24,22


CEUS
Office ID Cannonical Name 11 Administration and Management 12 Financial/Legal 13 Insurance/Real Estate 18 Government Services 17 Software Development 63 Medical/Dental Office 15 Assorted/Multi-tenant 19 Other Office	Data Center ID Cannonical Name 14 Data Processing/Computer Center	Laboratory ID Cannonical Name 16 Lab/R&D Facility	Restaurant ID Cannonical Name 21 Fast Food or Self Service 22 Specialty/Novelty Food Service 25 Other Food Service 24 Bar/Tavern/Nightclub/Other 23 Table Service
Food Store ID Cannonical Name 31 Supermarkets 32 Small General Grocery 34 Convenience Store 36 Other Food Store 35 Liquor Store 33 Specialty/Ethnic Grocery	Retail ID Cannonical Name 41 Department / Variety Store 42 Retail Warehouse/Clubs 43 Shop in Enclosed Mall 44 Shop in Strip Mall 46 Other Retail Store 45 Auto Sales	Warehouse (Refrig) ID Cannonical Name 51 Refrigerated Warehouse	Warehouse (Non-Refrig) ID Cannonical Name 52 Unconditioned Warehouse, High Bay 55 Conditioned Warehouse, Low Bay 53 Unconditioned Warehouse, Low Bay 54 Conditioned Warehouse, High Bay
Healthcare ID Cannonical Name 61 Hospital 64 Clinic/Outpatient Care 65 Medical/Dental Lab 62 Nursing Home	School ID Cannonical Name 71 Daycare or Preschool 72 Elementary School 73 Middle / Secondary School	College ID Cannonical Name 74 College or University 75 Vocational or Trade School	Lodging ID Cannonical Name 81 Hotel 84 Other Lodging 83 Resort 82 Motel
Public Assembly ID Cannonical Name 96 Library / Museum 97 Conference/Convention Center 92 Religious Assembly (mixed use) 94 Movie Theaters 93 Health/Fitness Center 91 Religious Assembly (worship only) 95 Theater / Performing Arts 98 Community Center 99 Other Recreational/Public Assembly	Miscellaneous ID Cannonical Name 101 Gas Station / Auto Repair 102 Gas Station With Convenience Store 103 Repair (Non-Auto) 104 Other Service Shop 111 Assembly / Light Mfg. 112 Police / Fire Stations 113 Post Office 130 Other Unlisted Type

CBECS
Education ID Cannonical Name 27 College/university 28 Elementary/middle school 29 High school 30 Preschool/daycare 31 Other classroom education	Food sales ID Cannonical Name 12 Convenience store 13 Convenience store with gas station 14 Grocery store/food market 15 Other food sales	Food service ID Cannonical Name 32 Fast food 33 Restaurant/cafeteria 34 Other food/service 35 Hospital/inpatient health	Health Care - Inpatient ID Cannonical Name 35 Hospital/inpatient health
Health Care - Outpatient ID Cannonical Name 18 Medical office (diagnostic) 19 Clinic/other outpatient health	Laboratory ID Cannonical Name 8 Laboratory	Lodging ID Cannonical Name 37 Dormitory/fraternity/sorority 38 Hotel 39 Motel or inn 36 Nursing home/assisted living 40 Other lodging	Mercantile - Mall ID Cannonical Name 51 Enclosed mall 50 Strip shopping mall
Mercantile - Not Mall ID Cannonical Name 41 Vehicle dealership/showroom 42 Retail store 43 Other retail	Office ID Cannonical Name 2 Administrative/professional office 3 Bank/other financial 4 Government office 5 Medical office (non-diagnostic) 6 Mixed-use office 7 Other office	Public assembly ID Cannonical Name 22 Entertainment/culture 23 Library 24 Recreation 25 Social/meeting 26 Other public assembly	Public order and safety ID Cannonical Name 16 Fire station/police station 17 Other public order and safety
Religious worship ID Cannonical Name 21 Religious worship	Service ID Cannonical Name 44 Post office/postal center 45 Repair shop 46 Vehicle service/repair shop 47 Vehicle storage/maintenance 48 Other service	Warehouse & Storage ID Cannonical Name 9 Distribution/shipping center 10 Non-refrigerated warehouse 11 Self-storage 20 Refrigerated warehouse	Other ID Cannonical Name 49 Other
Vacant ID Cannonical Name 1 Vacant

• Building Vintage

Parameter Name: [building_vintage_id]

Note that EnergyIQ bundles the age of buildings into set bins (see IDs in the tables below). If your queries span vintages, select both bins for best results

Vintage (CEUS)
ID	Cannonical Name
0	1991 through Present
1	1979 through 1990
2	1941 through 1978
3	1901 through 1940
4	Pre-1900
13	Unknown

Vintage (CBECS)
ID	Cannonical Name
1	Before 1920
2	1920 to 1945
3	1946 to 1959
4	1960 to 1969
5	1970 to 1979
6	1980 to 1989
7	1990 to 1999
8	2000 to 2003




Pay close attention to the 'Unknown' value. This is for buildings in the data store that did not have their age recorded.

• Building Location

Parameter Name: [building_location_id]

Check out the CEUS Location, CBECS Climate, and Census maps to determine what the locations boundaries represent.

Location (CEUS)
ID	Cannonical Name
4	North Coast
1	Central Valley
3	Mountains
2	Desert
0	Central Coast
5	South Coast
6	South Inland

Location (CBECS)
ID	Cannonical Name
Climate Zones
1	Zone 1:<2000 CDD, >7000 HDD
2	Zone 2:<2000 CDD, 5500-7000 HDD
3	Zone 3:<2000 CDD, 4000-5499 HDD
4	Zone 4:<2000 CDD, <4000 HDD
5	Zone 5:>=2000 CDD, <4000HDD
7	Withheld to protect confidentiality
Census Regions
	Midwest
30	East North Central
40	West North Central
	Northeast
10	New England
20	Middle Atlantic
	South
50	South Atlantic
60	East South Central
70	West South Central
	West
80	Mountain
90	Pacific

• Building Size

Parameter Name: [building_size_id]

Similar to Building Vintage, buildings are grouped into size bins.

Size (CEUS)
ID	Cannonical Name
0	0 - 25,000 sf
1	25,001 - 150,000 sf
2	Over 150,000 sf

Size (CBECS)
ID	Cannonical Name
1	1000 sq ft or less
2	1001 to 5000 sq ft
3	5001 to 10,000 sq ft
4	10,001 to 25,000 sq ft
5	25,001 to 50,000 sq ft
6	50,001 to 100,000 sq ft
7	100,001 to 200,000 sq ft
8	200,001 to 500,000 sq ft
9	500,001 to 1 million sq ft
10	Over 1 million sq ft

• Metrics (Energy Profile)

Parameter Names: [constraint, constraint_id, constraintGroup, constraintItem]

constraint is always equal to "energy"

&constraint=energy&constraint_id=0&constraintGroup=Total_Energy &constraint=energy&constraint_id=8&constraintGroup=End_Uses&constraintItem=Cooling

Query must choose only one of these:

Metrics (Energy Profile)
constraint_id	constraintGroup	constraintItem	Cannonical Name
0	Total_Energy		Total Energy
1	Total_Electricity		Total Electricity
2	Total_Fuel		Total Fuel
3	End_Use_Breakout	Total	Total Energy usage
4	End_Use_Breakout	Electricity	Electricity only usage
5	End_Use_Breakout	Fuel	Fuel only usages
6	End_Uses	Lighting	Lighting
7	End_Uses	Heating	Heating
8	End_Uses	Cooling	Cooling
9	End_Uses	Ventilation	Ventilation
10	End_Uses	Service Hot Water	Service Hot Water
11	End_Uses	Office Equip.	Office Equipment
12	End_Uses	Refrigeration	Refrigeration
13	End_Uses	Cooking	Cooking
14	End_Uses	Motors	Motors
15	End_Uses	Air Compressors	Air Compressors
16	End_Uses	Process	Process
17	End_Uses	Miscellaneous	Miscellaneous

End Use Breakout metrics may only use Stacked Bar as their view (See Below)



• Indicators (Measurement Units)

Parameter Names: [indicator,indicator_name]

Where indicator gets the Group name and indicator_name gets the specific unit and its id. Note the ":" appender.

&indicator=Source Energy&indicator_name=kBTU/sf-yr:1

Query must choose only one of these:

Site Energy		Source Energy		Cost		Emissions
ID	Cannonical Name
0	kWh/sf-yr	1	kBTU/sf-yr	2	$/sf-yr	3	lbs. CO2/sf-yr
16	kBTU/sf-yr	18	MJ/sq.m-yr	23	$/sq.m-yr	19	lbs. CO2e/sf-yr
17	MJ/sq.m-yr	25	kWh/sq.m-yr			20	kg. CO2/sq.m-yr
22	kWh/sq.m-yr					21	kg. CO2e/sq.m-yr

• Views (Plot type)

Parameter Name: [plot_type]

Query must choose only one of these.

Plot Type
ID	Cannonical Name
range_bar	Range Bar
ranked_bar	Ranked Bar Chart
frequency	Frequency Distribution
stacked_bar_abs	Stacked Bar with absolute values
stacked_bar_pct	Stacked Bar by percentage used
pie	Pie Chart (offline)

Both Stacked Bar views are only functional with End Use Breakout metrics. An error will be thrown if you attempt to visualize other metrics with these views.(See Above)

The Pie Chart is currently not exposed through this web service



• Input signatures

In order to perform a benchmarking calculation, you must make a Web Service call to EnergyIQ's WebService end point. Currently, this is implemented by passing parameters to a URL. The order of parameters in the URL is not important, but they are all required and must meet the aforementioned selection criteria.

constraintType is not currently parameterized.

Example 1:

Benchmark Total Energy for all Warehouses in Coastal California greater than 25,000 sq. ft.
Display Source Energy in kBTU/sf-yr in a Frequency Distribution plot.

http://ws.lbl.gov:8080/axis2/services/DirSvcWS/energyIQPlotInfo?license_key=XYZ &site_code=55,54,51,52,53&building_vintage_id=0,1,2,3,4,13&building_location_id=4,0,5 &building_size_id=1,2&constraint=energy&constraint_id=0&constraintGroup=Total_Energy &constraintItem=&constraintType=&indicator=Source Energy:1 &indicator_name=kBTU/sf&data_set=CEUS&plot_type=frequency

Example 2:

Benchmark Total Electricity for Schools & Colleges in Southern California greater than 25,000 sq. ft. built before 1990.
Display Cost in $/sf-yr in a Frequency Distribution plot.

http://ws.lbl.gov:8080/axis2/services/DirSvcWS/energyIQPlotInfo?license_key=XYZ &site_code=71,72,73,74,75&building_vintage_id=1,2,3,4&building_location_id=2,5,6 &building_size_id=1,2&constraint=energy&constraint_id=1&constraintGroup=Total_Electricity &constraintItem=&constraintType=&indicator=Cost:2 &indicator_name=$/sf-yr&data_set=CEUS&plot_type=frequency

Example 3:

Benchmark Total Fuel for all Retail in all United States climate zones with size 5000 sq. ft. or less and built between 1960 and 1990.
Display Emissions in lbs. CO₂e/sf-yr in a Ranked Bar plot.

http://ws.lbl.gov:8080/axis2/services/DirSvcWS/energyIQPlotInfo?license_key=XYZ &site_code=42,43&building_vintage_id=4,5,6&building_location_id=1,2,3,4,5,6,7 &building_size_id=1,2&constraint=energy&constraint_id=2&constraintGroup=Total_Fuel &constraintItem=&constraintType=&indicator=Emissions:19 &indicator_name=lbs. CO2e/sf-yr&data_set=CBECS&plot_type=ranked_bar

Example 4:

Benchmark Total Energy for all Food Sales and Service in the U.S South Census region, with a Climate zone of 4,
building size of 10000 sq. ft. or less, and built after 1990.
Display Site Energy in kWh/sf-yr in a Range Bar plot.

http://ws.lbl.gov:8080/axis2/services/DirSvcWS/energyIQPlotInfo?license_key=XYZ &site_code=12,13,14,15,32,33,34,35&building_vintage_id=7,8&building_location_id=4,50,60,70 &building_size_id=1,2,3&constraint=energy&constraint_id=0&constraintGroup=Total_Energy &constraintItem=&constraintType=&indicator=Site Energy:0 &indicator_name=kWh/sf-yr&data_set=CBECS&plot_type=range_bar

Example 5:

Benchmark Ventilation End Use for all Offices in California with a building size up to 150,000 sq. ft., and built after 1978.
Display Cost in $/sf-yr in a Frequency Distribution plot.

http://ws.lbl.gov:8080/axis2/services/DirSvcWS/energyIQPlotInfo?license_key=XYZ &site_code=11,12,13,15,17,18,19,63&building_vintage_id=0,1&building_location_id=0,1,2,3,4,5,6 &building_size_id=0,1&constraint=energy&constraint_id=9&constraintGroup=End_Uses &constraintItem=Ventilation&constraintType=&indicator=Cost:2 &indicator_name=$/sf-yr&data_set=CEUS&plot_type=frequency

Example 6:

Benchmark Electrical consumption of all end uses for all Healtcare facilities in California with a building size up to 25,000 sq. ft., and built after 1978.
Display Emissions in equivalent lbs. of CO₂ in a Stacked Bar plot with absolute values

http://ws.lbl.gov:8080/axis2/services/DirSvcWS/energyIQPlotInfo?license_key=XYZ &site_code=61,62,64,65&building_vintage_id=0,1&building_location_id=0,1,2,3,4,5,6 &building_size_id=0&constraint=energy&constraint_id=4&constraintGroup=End_Use_Breakout &constraintItem=Electricity&constraintType=&indicator=Emissions:19 &indicator_name=lbs. CO2e/sf-yr&data_set=CEUS&plot_type=stacked_bar_abs

• Output XML

The Benchmarking WebService currently returns one schema as successful response and one for error conditions. The format is straightforward. The following items are returned for a successful benchmarking request:

Count

The number of buldings that met your filters criteria and were used in the benchmark calculations.

Description

This is a summary paragraph providing high level measurement information for the data used in the calculations. Values will change as the filter criteria change.
There are no line breaks in this string.

Image

This is the URL that has the image of the plot. It will be persistent for approximately 30 days. As a consumer of this Web Service, you are allowed to save and distribute this image with appropriate credits.

Crumbtrail

This represents all the parameters passed to the web service call. This allows you to move them around with the response in your logic easier.

1:<ns:energyIQPlotInfoResponse> 2: <ns:return> 3: <plot> 4: <summary> 5: <count>32</count> 6: <description> 7: The source energy consumed for typical buildings of the type(s) you've 8: specified is 454.7 kBTU/sf-yr [median], with a range of 147.3 to 1324.2 9: kBTU/sf-yr [5th to 95thpercentiles] for the population. 10: Enter your own building information at the left to see how yours compares. 11: Try other Views for graphical and tabular detail. This analysis includes 12: population weights for each building. 13: </description> 14: </summary> 15: <image> 16: http://ws.lbl.gov/EnergyIQ/web/chartfx62/temp/CFTac8c85c78330bc719.png 17: </image> 18: <crumbtrail> 19: <constraint>energy</constraint> 20: <constraintGroup>Total_Energy</constraintGroup> 21: <constraintId>0</constraintId> 22: <BuildingLocale>4,50,60,70</BuildingLocale> 23: <BuildingSize>1,2,3</BuildingSize> 24: <BuildingVintage>7,8</BuildingVintage> 25: <BuildingType>12,13,14,15,32,33,34,35</BuildingType> 26: <Indicator>Site Energy:0</Indicator> 27: <IndicatorName>kWh/sf-yr</IndicatorName> 28: <PeerGroupDataSet>CBECS</PeerGroupDataSet> 29: </crumbtrail> 30: </plot> 31: </ns:return> 32:</ns:energyIQPlotInfoResponse>

In those conditions when an error occurs, the following is returned:

Code

An EnergyIQ defined code for the message. An attempt has been made to make this as distinct as possible to help consumers of the Web Service better handle error states in their system.

Message

A more human readable message that is associated with the code. Consumers may choose to ignore this and provide alternate feedback to their users.

1:<ns:energyIQPlotInfoResponse> 2: <ns:return> 3: <error> 4: <code> 5: user.invalid_key 6: </code> 7: <message> 8: License key is invalid 9: </message> 10: </error> 11: </ns:return> 12:</ns:energyIQPlotInfoResponse>
• Versioning

All AXIS-2 Web Service implemenations will be backward compatible. New versions will just provide new documented functionality. When the WSDL versions are released, older versions may not work as documented. This deprecation will be documented here as appropriate.