BPD API Documentation
BPD API Documentation
This site has documentation for the Building Performance Database (BPD) Application Programming Interface (API). To request an API license, please email us at [email protected]. For more information about the BPD, visit bpdinfo.lbl.gov. To access the BPD Graphical User Interface (GUI), visit bpd.lbl.gov.
Getting Started
The API URL is: https://bpdapi.lbl.gov
Queries must include the following headers to authorize the user:
{"ContentType": "application/json", "Authorization": "ApiKey USER_NAME:API_KEY"}
To obtain a user name and API key, email us at [email protected].
For Python users, the bpd_api library provides functions for each of the API endpoints.
Categorical Fields
Name 
Description 
Values 

zip_code 
5digit ZIP code in which the building is located. 
94720, 94103, 10007, ... 
city 
City in which the building is located. 
Berkeley, San Francisco, New York, ... 
state 
State in which the building is located. 
CA, NY, FL, TX, ... 
climate 
ASHRAE climate zone in which the building is located. 
3C Warm  Marine (San FranciscoCA), ... 
building_class 
General classification of the building. 
Commercial, Residential 
facility_type 
Primary use type of the building. 
Laboratory, Food Sales, Data Center, ... 
lighting 
Type of lighting system. 
LED, Fluorescent  T8, Incandescent, ... 
air_flow_control 
Whether the HVAC system is VAV or CAV based. 
Variable Volume, Constant Volume, ... 
heating 
Type of heating system. 
Furnace, Boiler  Steam, Perimeter Baseboard, ... 
heating_fuel 
Fuel used for heating. 
Natural Gas, District Steam, Electricity, ... 
cooling 
Type of cooling system. 
Split AC System, Evaporative Cooler, ... 
wall_type 
Type of walls. 
Brick, Concrete  Panels, Sheet Metal, ... 
roof_ceiling 
Type of roof. 
Builtup, Shingles, Concrete, ... 
window_glass_layers 
Numbers of window layers. 
Singlepane, Doublepane, ... 
window_glass_type 
Type of window glass. 
Clear, Tinted, Reflective, ... 
energy_star_label 
Whether or not the building has an ENERGY STAR label. 
Labeled, Not Labeled, Unknown 
leed_score 
Type of LEED certification. 
Platinum, Gold, Silver, ... 
data_source 
Name of the original data source. 
Anonymous, Berkeley Benchmarking Ordinance, ... 
Numerical Fields
Name 
Description 
Minimum 
Maximum 
Unit 

year 
Year in which the data was measured. 
1990 
previous year 
year 
electric_eui 
Annual electric energy use intensity. 
0 
1000 
kBtu/ft^{2}/year 
fuel_eui 
Annual fuel energy use intensity. Includes all nonelectric fuels. 
0 
1000 
kBtu/ft^{2}/year 
site_eui 
Annual site energy use intensity. 
1 
1000 
kBtu/ft^{2}/year 
source_eui 
Annual source energy use intensity. 
1 
3140 
kBtu/ft^{2}/year 
ghg_emissions_int 
Annual greenhouse gas (GHG) emissions intensity. 
0 
400 
kgCO_{2}e/ft^{2}/year 
floor_area 
Gross floor area of the building. 
500 
7000000 
ft^{2} 
year_built 
Year in which the building was constructed. 
1600 
previous year 
year 
number_of_people 
Number of occupants in the building. 
0 
35000 
people 
occupant_density 
Number of occupants normalized by floor area. 
0 
200 
people/1000 ft^{2} 
operating_hours 
Weekly number of hours the building is operating. 
0 
168 
hours/week 
wall_insulation_r_value 
Rvalue of exterior walls. 
0 
60 
Rvalue 
energy_star_rating 
ENERGY STAR score. 
0 
100 
score 
Several API endpoints accept the filters parameter to allow selecting a subset of the data to apply the query to. Any API field can be used to filter queries, and multiple fields can be used simultaneously. The following examples illustrate the use of filters on both categorical and numerical fields, and by both including and excluding specific values or ranges.
Example 1: Equivalent methods for selecting buildings in either California or Washington.
filters = {"state": ["CA", "WA"]} filters = {"state": {"values": ["CA", "WA"]}} filters = {"state": {"values": ["CA", "WA"], "exclude": False}}
Example 2: Equivalent methods for selecting buildings not in California or Washington.
filters = {"state": ["AL", "AK", "AZ", "AR", "CO", ..., "VI", "WV", "WI", "WY", "Unknown"]} filters = {"state": {"values": ["CA", "WA"], "exclude": True}}
Example 3: Equivalent methods for selecting buildings whose floor area is >= 500 ft^{2} and <= 2000 ft^{2}.
filters = {"floor_area": {"min": 500, "max": 2000}} filters = {"floor_area": {"min": 500, "max": 2000, "exclude": False}}
Example 4: Selecting buildings whose floor area is < 500 ft^{2} or > 2000 ft^{2}.
filters = {"floor_area": {"min": 500, "max": 2000, "exclude": True}}
Example 5: Selecting buildings whose floor area is between 500 ft^{2} and 2000 ft^{2} and are in California or Washington.
filters = {"floor_area": {"min": 500, "max": 2000}, "state": ["CA", "WA"]}
All API endpoints return the following metadata JSON object along with their response.
Property 
Type 
Description 

request_time 
float 
The time (in seconds) needed to complete the request. 
message 
string 
Indicates whether the request was successful. Either "success" or "error". 
error_type 
string 
Type of the error that occurred. Only returned if request does not succeed. 
error 
string 
Description of the error that occurred. Only returned if request does not succeed. 
Endpoints
Characteristic 
Value 

Method 
GET 
URL 

Description 
Returns general information about the API. 
Response
Property 
Type 
Description 

message 
JSON object 
General information about the API (see below). 
metadata 
JSON object 
General information about the request (see Metadata section above). 
Response: message
Property 
Type 
Description 

url 
string 
URL of the API documentation. 
version 
string 
Current version of the API. 
ip 
string 
IP address of the API server. 
Examples
Example 1: General information about the API.
Request URL: https://bpdapi.lbl.gov/ Response: {"message": {"url": "https://bpdapidocs.lbl.gov", "version": "2.4.0", "ip": "172.33.59.46"}, "metadata": ...}
Characteristic 
Value 

Method 
GET 
URL 

Description 
Returns a list of all fields. Optionally, returns only numerical fields or only categorical fields. 
Parameters
Property 
Type 
Optional 
Description 

field_type 
string 
True 
The type of field to be returned. Either "categorical" or "numerical". Defaults to both types. Specified in URL (see example below). 
Response
Property 
Type 
Description 

fields 
list of lists 
The name and type of each field. 
metadata 
JSON object 
General information about the request (see Metadata section above). 
Examples
Example 1: List of all fields.
Request URL: https://bpdapi.lbl.gov/api/v2/introspection/fields Response: {"fields": [["zip_code", "categorical"], ["state", "categorical"], ["number_of_people", "numerical"], ...], "metadata": ...}
Example 2: Only numerical fields.
Request URL: https://bpdapi.lbl.gov/api/v2/introspection/fields?field_type=numerical Response: {"fields": [["number_of_people", "numerical"], ["operating_hours", "numerical"], ["energy_star_rating", "numerical"], ...], "metadata": ...}
Characteristic 
Value 

Method 
GET 
URL 
https://bpdapi.lbl.gov/api/v2/introspection/fields/field_name 
Description 
For categorical fields, returns a list of all legal values of the field (except for variables with many values, i.e., city and zip_code). For numerical fields, returns the minimum and maximum values, and the unit of measure. 
Parameters
Property 
Type 
Optional 
Description 

field_name 
field 
False 
The field to return the field information for. Specified in URL (see examples below). 
building_class 
string 
True 
The class of buildings to return facility types for. Either "Commercial" or "Residential". Can only be used with field_name = "facility_type". Specified in URL (see example below). 
Response
Property 
Type 
Description 

field_info 
JSON object 
For categorical variables: Field name, type, and list of legal values. For numerical variables: Field name, type, minimum and maximum legal values, and unit of measure. 
metadata 
JSON object 
General information about the request (see Metadata section above). 
Examples
Example 1: Legal values of the climate field.
Request URL: https://bpdapi.lbl.gov/api/v2/introspection/fields/climate Response: {"field_info": {"name": "climate", "type": "categorical", "values": ["1A Very Hot  Humid (MiamiFL)", "2A Hot  Humid (HoustonTX)", "2B Hot  Dry (PhoenixAZ)", ..., "8 Subarctic (FairbanksAK)", "Unknown"]}, "metadata": ...}
Example 2: Minimum and maximum legal values of the operating_hours field.
Request URL: https://bpdapi.lbl.gov/api/v2/introspection/fields/operating_hours Response: {"field_info": {"max": 168.0, "min": 0.0, "name": "operating_hours", "type": "numerical", "unit": "hours/week"}, "metadata": ...}
Example 3: Legal values of the facility_type field, but only for residential buildings.
Request URL: https://bpdapi.lbl.gov/api/v2/introspection/fields/facility_type?building_class=Residential Response: {"field_info": {"name": "facility_type", "type": "categorical", "values": ["Single Family  Uncategorized", "Single Family  Attached", "Single Family  Detached", ..., "Mixed Use  Predominantly Commercial", "Mixed Use  Predominantly Residential"]}, "metadata": ...}
Characteristic 
Value 

Method 
POST 
URL 

Description 
Returns the number of buildings matching the specified filters. 
Parameters
Property 
Type 
Optional 
Description 

filters 
JSON object 
True 
Filters defining the set of buildings to be included (see Filters section above). Defaults to including all buildings. 
Response
Property 
Type 
Description 

totals 
JSON object 
Number of buildings matching the filters (see below). 
modified 
boolean 
True if fewer than 10 buildings match the filters. If True, totals are set to zero. Only returned if True. 
metadata 
JSON object 
General information about the request (see Metadata section above). 
Response: totals
Property 
Type 
Description 

number_of_matching_buildings 
integer 
Number of buildings matching the filters. 
number_of_buildings_in_bpd 
integer 
Total number of buildings in the BPD. 
number_of_matching_building_years 
integer 
Number of buildingyears matching the filters. 
number_of_building_years_in_bpd 
integer 
Total number of buildingyears in the BPD. 
Examples
Example 1: Number of commercial buildings in California, New York, or Texas.
Request parameters: {"filters": {"building_class": ["Commercial"], "state": ["CA","NY","TX"]}} Response: {"totals": {"number_of_building_years_in_bpd": 1559940, "number_of_buildings_in_bpd": 1115196, "number_of_matching_building_years": 116311, "number_of_matching_buildings': 47867}, "metadata": ...}
Characteristic 
Value 

Method 
POST 
URL 

Description 
Returns a histogram with bins defined by the specified field. 
Parameters
Property 
Type 
Optional 
Description 

group_by 
list of fields 
False 
Fields used to define the histogram bins. 
filters 
JSON object 
True 
Filters defining the set of buildings to be included (see Filters section above). Defaults to including all buildings. 
resolution 
string 
True 
Determines the number of bins used. Higher resolution results in more bins. Either "high", "med", or "low". Defaults to "high". Only applies to numerical group_by fields. 
include_all_years 
boolean 
True 
If True, include all years of data for each building. If False, only include the most recent year. Defaults to False. 
Response
Property 
Type 
Description 

groups 
list of JSON objects 
Groups defining the histogram bins. 
counts 
list of integers 
Number of buildings in each of the bins. 
counts_modified_mask 
list of integers 
Masks indicating whether each bin has been modified. By default, all masks are 0. If there are fewer than 10 buildings in the bin, the mask for that bin is set to 1 and the count for that bin is set to 0. 
mean 
float 
Mean of the counts. 
standard_deviation 
float 
Standard deviation of the counts. 
quartiles 
list of floats 
0th, 25th, 50th, 75th, and 100th percentiles of the counts (where the 0th percentile is the minimum and the 100th percentile is the maximum). 
totals 
JSON object 
Number of buildings matching the filters and summary statistics of the group_by field (see below). 
metadata 
JSON object 
General information about the request (see Metadata section above). 
Response: totals
Property 
Type 
Description 

number_of_matching_buildings 
integer 
Number of buildings matching the filters, and having data for the group_by field. 
number_of_buildings_in_bpd 
integer 
Total number of buildings in the BPD. 
number_of_matching_building_years 
integer 
Number of buildingyears matching the filters, and having data for the group_by field. 
number_of_building_years_in_bpd 
integer 
Total number of buildingyears in the BPD. 
percentile_0 
float 
Minimum value of the group_by field. False if group_by is categorical. 
percentile_25 
float 
25^{th} percentile of the group_by field. False if group_by is categorical. 
percentile_50 
float 
50th percentile of the group_by field. False if group_by is categorical. 
percentile_75 
float 
75^{th} percentile of the group_by field. False if group_by is categorical. 
percentile_100 
float 
Maximum value of the group_by field. False if group_by is categorical. 
mean 
float 
Mean of the group_by field. False if group_by is categorical. 
standard_deviation 
float 
Standard deviation of the group_by field. False if group_by is categorical. 
Examples
Example 1: High resolution histogram of fuel_eui for commercial buildings not in Alaska or Hawaii.
Request parameters: {"filters": {"building_class": ["Commercial"], "state": {"values": ["AK","HI"], "exclude": "True"}}, "group_by": ["fuel_eui"], "resolution": "high"} Response: {"groups": [{"field": "fuel_eui", "type": "numerical", "name": "010 kBtu/sqft/yr", "min": 0.0, "max": 10.0}}, {"field": "fuel_eui", "type": "numerical", "name": "1020 kBtu/sqft/yr", "min": 10.0, "max": 20.0}, ...]}, "counts": [14066, 7583, ...], "counts_modified_mask": [0, 0, ...], "quartiles": [1.0, 8.0, 23.0, 114.0, 14066.0], "mean": 725.9411764705883, "standard_deviation": 2353.787581000161, "totals": {"number_of_matching_buildings": 37023, "number_of_buildings_in_bpd": 794030, "number_of_matching_building_years": 52715, "number_of_building_years_in_bpd": 976633, "percentile_0": [0.0], "percentile_25": [6.579761143100875], "percentile_50": [15.861682489451477], "percentile_75": [32.176977826444016], "percentile_100": [1000.0], "mean": [26.557140156119168], "standard_deviation": [41.57248711736111]}, "metadata": ...}
Characteristic 
Value 

Method 
POST 
URL 

Description 
Returns summary statistics of a specified numerical variable for each group of buildings, as defined by a specified field. 
Parameters
Property 
Type 
Optional 
Description 

analyze_by 
numerical field 
False 
Numerical field to compute the summary statistics on. 
group_by 
list of fields 
False 
Fields used to define the table groups. 
filters 
JSON object 
True 
Filters defining the set of buildings to be included (see Filters section above). Defaults to including all buildings. 
resolution 
string 
True 
Determines the number of groups used. Higher resolution results in more bins. Either "high", "med", or "low". Defaults to "med". Only applies to numerical group_by fields. 
include_all_years 
boolean 
True 
If True, include all years of data for each building. If False, only include the most recent year. Defaults to False. 
Response
Property 
Type 
Description 

table 
list of JSON objects 
Summary statistics of the analyze_by field for the buildings in each group (see below). 
summary 
JSON object 
Summary statistics of the analyze_by field for the buildings in all groups. 
totals 
JSON object 
Number of buildings matching the filters (see below). 
metadata 
JSON object 
General information about the request (see Metadata section above). 
Response: table
Property 
Type 
Description 

group 
JSON object 
Definition of the group. 
modified 
boolean 
True if more than zero or less than 10 buildings in group. If True, other summary statistics are set to null. Only returned if True. 
count 
integer 
Number of buildings in the group. Zero if no buildings in group or group has been modified. 
percentile_0 
float 
Minimum value of the analyze_by field for buildings in the group. Null if no buildings in group or group has been modified. 
percentile_25 
float 
25th percentile of the analyze_by field for buildings in the group. Null if no buildings in group or group has been modified. 
percentile_50 
float 
50th percentile of the analyze_by field for buildings in the group. Null if no buildings in group or group has been modified. 
percentile_75 
float 
75th percentile of the analyze_by field for buildings in the group. Null if no buildings in group or group has been modified. 
percentile_100 
float 
Maximum value of the analyze_by field within the group. Null if no buildings in group or group has been modified. 
mean 
float 
Mean of the analyze_by field for buildings in the group. Null if no buildings in group or group has been modified. 
standard_deviation 
float 
Standard deviation of the analyze_by field for buildings in the group. Null if no buildings in group or group has been modified. 
Response: totals
Property 
Type 
Description 

number_of_matching_buildings 
integer 
Number of buildings matching the filters, and having data for the analyze_by and group_by fields. 
number_of_buildings_in_bpd 
integer 
Total number of buildings in the BPD. 
number_of_matching_building_years 
integer 
Number of buildingyears matching the filters, and having data for the analyze_by and group_by fields. 
number_of_building_years_in_bpd 
integer 
Total number of buildingyears in the BPD. 
Examples
Example 1: Summary statistics of fuel_eui grouped by heating type for buildings in Boston, MA.
Request parameters: {"filters": {"state": ["MA"], "city": ["Boston"]}, "group_by": ["heating"], "analyze_by": "fuel_eui"} Response: {"summary": {"count": 58, "group": "ALL", "mean": 33.343181663672411, "percentile_0": 0.180938558, "percentile_100": 132.86934389999999, "percentile_25": 11.14824578, "percentile_50": 28.117647465000001, "percentile_75": 41.073610799999997, "standard_deviation": 32.049486118632096}, "table": [{"count": 0, "group": [{"field": "heating", "type": "categorical", "value": "District Steam"}], "mean": null, "percentile_0": null, "percentile_100": null, "percentile_25": null, "percentile_50": null, "percentile_75": null, "standard_deviation": null}, {"count": 54, "group": [{"field": "heating", "type": "categorical", "value": "Unknown"}], "mean": 27.889599032833328, "percentile_0": 0.180938558, "percentile_100": 117.9575883, "percentile_25": 10.9687122975, "percentile_50": 27.722417145000001, "percentile_75": 34.554031035000001, "standard_deviation": 24.950879222962861}, ...], "totals": ..., "metadata": ...}
Characteristic 
Value 

Method 
POST 
URL 

Description 
Returns a random sample of up to 3 fields for up to 1000 buildings. 
Parameters
Property 
Type 
Optional 
Description 

xaxis 
field 
False 
First field to include in sample. 
yaxis 
field 
True 
Second field to include in sample. Defaults to nothing. 
additional_fields 
list of fields 
True 
Additional fields to include in sample. Defaults to empty list. 
filters 
JSON object 
True 
Filters defining the set of buildings to be included (see Filters section above). Defaults to including all buildings. 
limit 
integer 
True 
Maximum number of buildings to return samples for. Maximum value is 1000. Defaults to 1000. 
include_all_years 
boolean 
True 
If True, include all years of data for each building. If False, only include the most recent year. Defaults to False. 
Response
Property 
Type 
Description 

scatterplot 
list of lists 
Sampled values of each field for each building. 
totals 
JSON object 
Number of buildings matching the filters and summary statistics of the sampled fields (see below). 
metadata 
JSON object 
General information about the request (see Metadata section above). 
Response: totals
Property 
Type 
Description 

number_of_matching_buildings 
integer 
Number of buildings matching the filters, and having data for the xaxis, yaxis, and additional_fields fields. 
number_of_buildings_in_bpd 
integer 
Total number of buildings in the BPD. 
number_of_matching_building_years 
integer 
Number of buildingyears matching the filters, and having data for the xaxis, yaxis, and additional_fields fields. 
number_of_building_years_in_bpd 
integer 
Total number of buildingyears in the BPD. 
percentile_0 
list of floats 
Minimum value of each of the sampled fields. False if field is categorical. 
percentile_25 
list of floats 
25^{th} percentile of each of the sampled fields. False if field is categorical. 
percentile_50 
list of floats 
50th percentile of each of the sampled fields. False if field is categorical. 
percentile_75 
list of floats 
75^{th} percentile of each of the sampled fields. False if field is categorical. 
percentile_100 
list of floats 
Maximum value of each of the sampled fields. False if field is categorical. 
mean 
list of floats 
Mean of each of the sampled fields. False if field is categorical. 
standard_deviation 
list of floats 
Standard deviation of each of the sampled fields. False if field is categorical. 
Examples
Example 1: Samples of floor_area, source_eui, and heating type for buildings in California, Ohio, or Pennsylvania and with fluorescent T8 lighting.
Request parameters: {"filters": {"state": ["CA","OH","PA"], "lighting": ["Fluorescent  T8"]}, "xaxis": "floor_area", "yaxis": "source_eui", "additional_fields": ["heating"]} Response: {"scatterplot": [[1125.0, 109.4375, "District Hot Water"], [911.0, 93.0128, "Other Or Combination"], [31741.5, 125.0690, "Unknown"], ...], "totals": {"mean": [131518.32770958205, 264.4664704201189, False], "number_of_buildings_in_bpd": 1008855, "number_of_matching_buildings": 565, "percentile_0": [480.44039160556537, 7.909425398957303, False], "percentile_100": [1450995.821590411, 2274.042372789253, False], "percentile_25": [9395.090020005267, 113.54026940028744, False], "percentile_50": [49742.41753707226, 186.4512151404417, False], "percentile_75": [141453.96150376898, 337.33778878639873, False], "standard_deviation": [218947.69888027647, 261.5053234277449, False]}, "metadata": ...}
Characteristic 
Value 

Method 
POST 
URL 

Parameter 
method = "actuarial" 
Description 
Returns a histogram of relative percent differences of a specified numerical field. The differences are computed by randomly selecting pairs of buildings matching a specified pair of filters. 
Parameters
Property 
Type 
Optional 
Description 

analyze_by 
numerical field 
False 
Numerical field to compute differences for. 
base 
JSON object 
False 
Filters defining the set of buildings to be included in both the "from" and "to" groups (see Filters section above). 
from 
JSON object 
False 
Filters defining the set of buildings to be included in the "from" group. The "from" group contains buildings matching both the "base" filters and the "from" filters. 
to 
JSON object 
False 
Filters defining the set of buildings to be included in the "to" group. The "to" group contains buildings matching both the "base" filters and the "to" filters. 
method 
string 
True 
Method used to compute the differences. Either "actuarial" or "regression". Defaults to "actuarial". 
include_all_years 
boolean 
True 
If True, include all years of data for each building. If False, only include the most recent year. Defaults to False. 
Response
Property 
Type 
Description 

groups 
list of JSON objects 
Groups defining the histogram bins. 
counts 
list of integers 
Number of buildings in each of the bins. 
statistics 
JSON object 
Summary statistics of the computed differences (see below). 
totals 
JSON object 
Number of buildings matching the filters (see below). 
metadata 
JSON object 
General information about the request (see Metadata section above). 
Response: statistics
Property 
Type 
Description 

percentile_0 
float 
Minimum value of the differences. 
percentile_25 
float 
25th percentile of the differences. 
percentile_50 
float 
50th percentile of the differences. 
percentile_75 
float 
75th percentile of the differences. 
percentile_100 
float 
Maximum value of the differences. 
mean 
float 
Mean of the differences. 
standard_deviation 
float 
Standard deviation of the differences. 
Response: totals
Property 
Type 
Description 

number_of_matching_buildings 
integer 
Number of buildings matching the "base" filters and either the "from" or "to" filters, and having data for the analyze_by field. 
number_of_buildings_in_bpd 
integer 
Total number of buildings in the BPD. 
number_of_pre_matching_buildings 
integer 
Number of buildings matching the "base" and "from" filters, and having data for the analyze_by field. 
number_of_post_matching_buildings 
integer 
Number of buildings matching the "base" and "to" filters, and having data for the analyze_by field. 
number_of_matching_building_years 
integer 
Number of buildingyears matching the "base" filters and either the "from" or "to" filters, and having data for the analyze_by field. 
number_of_building_years_in_bpd 
integer 
Total number of buildingyears in the BPD. 
number_of_pre_matching_building_years 
integer 
Number of buildingyears matching the "base" and "from" filters, and having data for the analyze_by field. 
number_of_post_matching_building_years 
integer 
Number of buildingyears matching the "base" and "to" filters, and having data for the analyze_by field. 
Examples
Example 1: Differences in source_eui between buildings in California with constant volume air handling vs. buildings with variable volume air handling, using the actuarial method.
Request parameters: {"base": {"state": ["CA"]}, "from": {"air_flow_control": ["Constant Volume"]}, "to": {"air_flow_control": ["Variable Volume"]}, "analyze_by": "source_eui" "method": "actuarial"} Response: {"counts": [2548, 5102, 4675, ...], "groups": [{"field": "site_eui", "min": 98.02578676152483, "type": "numerical", "max": 83.63160792680833}, {"field": "site_eui", "min": 83.63160792680833, "type": u'numerical', "max": 69.23742909209183}, {"field": "site_eui", "min": 69.23742909209183, "type": "numerical", "max": 54.84325025737534}, ...}, "statistics": {"percentile_0": 98.02578676152483, "percentile_25": 62.195070923022655, "percentile_50": 23.25245702551483, "percentile_75": 53.59332895553282, "percentile_100": 2059.8456310281877, "mean": 22.23233186097467, "standard_deviation": 141.31275685447335}, "totals": {"number_of_matching_buildings": 836, "number_of_buildings_in_bpd": 755638, "number_of_post_matching_buildings": 409, "number_of_pre_matching_buildings": 427, ...}, "metadata": ...}
Characteristic 
Value 

Method 
POST 
URL 

Parameter 
method = "regression" 
Description 
Returns a histogram of relative percent differences of a specified numerical field. The differences are computed by fitting a multiple linear regression model to buildings matching the "base" filters, then using the model to compute the difference in the numerical field due to changing from the "from" filters value to the "to" filters value. 
Parameters
Property 
Type 
Optional 
Description 

analyze_by 
numerical field 
False 
Numerical field to compute differences for. Either "electric_eui", "fuel_eui", "site_eui", "source_eui", or "ghg_emissions_int". 
base 
JSON object 
False 
Filters defining the set of buildings to use when fitting the multiple linear regression model. Must include both values of the change field specified in the "from" and "to" filters (see examples below). 
from 
JSON object 
False 
Filter defining the value of the field to be changed from. Must have only one field (one of the change fields listed below) and one value of that field. Must be the same field, but different value, as the "to" filter (see examples below). 
to 
JSON object 
False 
Filter defining the value of the field to be changed to. Must have only one field (one of the change fields listed below) and one value of that field. Must be the same field, but different value, as the "from" filter (see examples below). 
method 
string 
True 
Method used to compute the differences. Either "actuarial" or "regression". Defaults to "actuarial". 
include_all_years 
boolean 
True 
If True, include all years of data for each building. If False, only include the most recent year. Defaults to False. 
Change Fields
year_built
operating_hours
occupant_density
facility_type
climate
lighting
heating
heating_fuel
cooling
air_flow_control
window_glass_type
window_glass_layers
wall_type
roof_ceiling
energy_star_label
leed_score
Response
Property 
Type 
Description 

groups 
list of JSON objects 
Groups defining the histogram bins. 
counts 
list of integers 
Number of buildings in each of the bins. 
statistics 
JSON object 
Summary statistics of the computed differences (see below). 
totals 
JSON object 
Number of buildings matching the filters (see below). 
metadata 
JSON object 
General information about the request (see Metadata section above). 
Response: statistics
Property 
Type 
Description 

percentile_0 
float 
Minimum value of the differences. 
percentile_25 
float 
25th percentile of the differences. 
percentile_50 
float 
50th percentile of the differences. 
percentile_75 
float 
75th percentile of the differences. 
percentile_100 
float 
Maximum value of the differences. 
mean 
float 
Mean of the differences. 
standard_deviation 
float 
Standard deviation of the differences. 
Response: totals
Property 
Type 
Description 

number_of_matching_buildings 
integer 
Number of buildings matching the "base" filters, and having data for the analyze_by field. 
number_of_buildings_in_bpd 
integer 
Total number of buildings in the BPD. 
number_of_pre_matching_buildings 
integer 
Number of buildings matching the "base" and "from" filters, and having data for the analyze_by field. 
number_of_post_matching_buildings 
integer 
Number of buildings matching the "base" and "to" filters, and having data for the analyze_by field. 
number_of_matching_building_years 
integer 
Number of buildingyears matching the "base" filters, and having data for the analyze_by field. 
number_of_building_years_in_bpd 
integer 
Total number of buildingyears in the BPD. 
number_of_pre_matching_building_years 
integer 
Number of buildingyears matching the "base" and "from" filters, and having data for the analyze_by field. 
number_of_post_matching_building_years 
integer 
Number of buildingyears matching the "base" and "to" filters, and having data for the analyze_by field. 
Examples
Example 1: Differences in source_eui between commercial buildings in California with fluorescent T8 lighting vs. buildings with fluorescent T12 lighting, using the regression method.
Request parameters: {"base": {"state": ["CA"], "building_class": ["Commercial"], "lighting": ["Fluorescent  T8", "Fluorescent  T12"]}, "from": {"lighting": ["Fluorescent  T8"]}, "to": {"lighting": ["Fluorescent  T12"]}, "analyze_by": "source_eui", "method": "regression"} Response: {"counts": [9, 3, 1, 1, ...], "groups": [{"field": "source_eui", "max": 29.423281631550218, "min": 134.75000467437292, "type": "numerical"}, {"field": "source_eui", "max": 26.138865500103101, "min": 29.423281631550218, "type": "numerical"}, ...], "statistics": ..., "totals": ..., "metadata": ...}
Characteristic 
Value 

Method 
POST 
URL 

Description 
Returns coefficients and fit statistics for a linear regression model fit using the specified dependent and independent variables. 
Parameters
Property 
Type 
Optional 
Description 

xfields 
list of Field Strings 
False 
Numerical or categorical fields to be used as the independent variables in the model. If the city or zip_code categorical variables are in the model, they must also be used when filtering the peer group. 
yfield 
Field String 
False 
Numerical field to be used as the dependent variable in the model. 
filters 
JSON object 
True 
Filters defining the set of buildings to be included (see Filters section above). Defaults to including all buildings. 
log_fields 
list of Field Strings 
True 
Numerical fields (dependent or independent) that should be transformed by the natural logarithm before fitting the model. Defaults to not transforming any fields. 
include_all_years 
boolean 
True 
If True, include all years of data for each building. If False, only include the most recent year. Defaults to False. 
Response
Property 
Type 
Description 

coefficients 
JSON object 
Regression coefficients for each independent variable in the model. Numerical variables have only one coefficient. Categorical variables have a coefficient for all except one of their values (the alphabetically last value). There is also a coefficient for the model intercept. 
statistics 
JSON object 
Summary statistics related to the coefficients and the model fit (see below). 
totals 
JSON object 
Number of buildings matching the filters (see below). 
metadata 
JSON object 
General information about the request (see Metadata section above). 
Response: statistics
Property 
Type 
Description 

aic 
float 
Akaike information criterion value of the model. 
df_resid 
integer 
Residual degrees of freedom of the model. 
f_pvalue 
float 
pvalue of the Fstatistic of the model. 
fvalue 
float 
Fstatistic of the model. 
loglikelihood 
float 
Loglikelihood of the model. 
nobs 
integer 
Number of observations used to fit the model. Buildings with missing data for numerical variables are excluded when fitting the model. 
p_values 
JSON Object 
pvalue corresponding to the tvalue associated with each of the model coefficients. 
residual 
float 
Sum of the squared residuals. 
rsquared 
float 
Coefficient of determination. 
std_errors 
JSON Object 
Standard error associated with each of the model coefficients. 
t_values 
JSON Object 
tvalue associated with each of the model coefficients. 
Response: totals
Property 
Type 
Description 

number_of_matching_buildings 
integer 
Number of buildings matching the filters. 
number_of_buildings_in_bpd 
integer 
Total number of buildings in the BPD. 
number_of_matching_building_years 
integer 
Number of buildingyears matching the filters. 
number_of_building_years_in_bpd 
integer 
Total number of buildingyears in the BPD. 
Examples
Example 1: Fitting a linear regression model of site_eui as a function of energy_star_rating and climate zone to buildings in California.
Request parameters: {"filters": {"state": ["CA"]}, "xfields": ["energy_star_rating", "climate"], "yfield": "site_eui"} Response: {"coefficients": {"climate": {"2B Hot  Dry (PhoenixAZ)": 3.863999035566146, ..., "5B Cool  Dry (BoiseID)": null}, "energy_star_rating": 1.639027103422914, "intercept": 178.89859848709875}, "statistics": {"aic": 56463.974026323776, "df_resid": 5314.0, "f_pvalue": 0.0, "fvalue": 393.84467577217305, "loglikelihood": 28224.987013161888, "nobs": 5321.0, "p_values": {"climate": {"2B Hot  Dry (PhoenixAZ)": 0.8600352637941979, ..., "5B Cool  Dry (BoiseID)": null}, "energy_star_rating": 0.0, "intercept": 5.098189412681182e38}, "residual": 12615574.585443843, "rsquared": 0.30780866312718813, "std_errors": {"climate": {"2B Hot  Dry (PhoenixAZ)": 21.912479319381085, ..., "5B Cool  Dry (BoiseID)": null}, "energy_star_rating": 0.033838066179026564, "intercept": 13.76943743371712}, "t_values": {"climate": {"2B Hot  Dry (PhoenixAZ)": 0.17633782919984448, ..., "5B Cool  Dry (BoiseID)": null}, "energy_star_rating": 48.43737507785868, "intercept": 12.992440638789722}}, "totals": ..., "metadata": ...}
Example 2: Fitting a model of electric_eui as a function of city, operating_hours, and log(floor_area) to refrigerated warehouses in New York or Philadelphia. Since city is in the model, it must also be in the filters.
Request parameters: {"filters": {"facility_type": ["Warehouse  Refrigerated"], "city": ["New York", "Philadelphia"]}, "xfields": ["city", "operating_hours", "floor_area"], "yfield": "electric_eui", "log_fields": ["floor_area"]} Response: {"coefficients": {"city": {"New York": 32.09093153301865, "Philadelphia": null}, "floor_area": 0.16605987352583612, "intercept": 6.036557502092312, "operating_hours": 0.0018602295599883635}, "statistics: ..., "totals": ..., "metadata" ...}
Characteristic 
Value 

Method 
POST 
URL 

Description 
Returns a random sample of up to 3 fields for up to 1000 buildings. Returns all years of data for each building, rather than just most recent. 
Parameters
Property 
Type 
Optional 
Description 

data_fields 
list of fields 
False 
Fields to include in the sample. Must include "year" and 1 or 2 additional fields. 
filters 
JSON object 
True 
Filters defining the set of buildings to be included (see Filters section above). Defaults to including all buildings. 
limit 
integer 
True 
Maximum number of buildings to return samples for. Maximum value is 1000. Defaults to 1000. 
min_data_years 
integer 
True 
Number of years of data a building must have to be included in the results. 
Response
Property 
Type 
Description 

multiyear 
list of lists of lists 
Sampled values for each field, for each building, and for each year. 
statistics 
JSON object 
Summary statistics of the sampled fields for each year (see below). 
totals 
JSON object 
Number of buildings matching the filters and summary statistics of the sampled fields (see below). 
metadata 
JSON object 
General information about the request (see Metadata section above). 
Response: statistics
Property 
Type 
Description 

year 
list of floats 
Years the statistics correspond to. 
count 
list of floats 
Number of buildings with data in each year. 
mean 
list of lists of floats 
Mean of each data field in each year. 
standard_deviation 
list of lists of floats 
Standard deviation of each data field in each year. 
percentile_0 
list of lists of floats 
Minimum value of each data field in each year. 
percentile_25 
list of lists of floats 
25th percentile of each data field in each year. 
percentile_50 
list of lists of floats 
50th percentile of each data field in each year. 
percentile_75 
list of lists of floats 
75th percentile of each data field in each year. 
percentile_100 
list of lists of floats 
Maximum value of each data field in each year. 
Response: totals
Property 
Type 
Description 

number_of_matching_buildings 
integer 
Number of buildings matching the filters, and having data for the data_fields fields. 
number_of_buildings_in_bpd 
integer 
Total number of buildings in the BPD. 
number_of_matching_building_years 
integer 
Number of buildingyears matching the filters, and having data for the data_fields fields. 
number_of_building_years_in_bpd 
integer 
Total number of buildingyears in the BPD. 
percentile_0 
list of floats 
Minimum value of each of the sampled fields. False if field is categorical. 
percentile_25 
list of floats 
25^{th} percentile of each of the sampled fields. False if field is categorical. 
percentile_50 
list of floats 
50th percentile of each of the sampled fields. False if field is categorical. 
percentile_75 
list of floats 
75^{th} percentile of each of the sampled fields. False if field is categorical. 
percentile_100 
list of floats 
Maximum value of each of the sampled fields. False if field is categorical. 
mean 
list of floats 
Mean of each of the sampled fields. False if field is categorical. 
standard_deviation 
list of floats 
Standard deviation of each of the sampled fields. False if field is categorical. 
Examples
Example 1: Getting at least 2 years of source_eui per building for buildings in Seattle.
Request parameters: {"filters": {"city": ["Seattle"]}, "data_fields": ["year","source_eui"], "min_data_years": 2} Response: {"multiyear": [[[2008.0, 162.8313368551825], [2009.0, 168.5828260161064], ..., [2014.0, 106.59808549745293]], [[2008.0, 137.70437989221665], [2010.0, 145.16865682723798], ..., [2014.0, 107.84494297048668]], ...], "statistics": {"count": [3, 3, ..., 906, 894], "mean": [[2008.0, 142.72500207827554], [2009.0, 145.13191519991432], ... [2017.0, 141.08625912561232]], "percentile_0": [[2008.0, 127.63928948742738], [2009.0, 124.27710165520314], ... [2017.0, 12.85718072903791]], ... "standard_deviation": [[0.0, 18.12525957979472], [0.0, 22.26665878771054], ... [0.0, 157.63633927001706]], "year": [2008.0, 2009.0, ..., 2017.0]}, "totals": {"number_of_building_years_in_bpd": 1405509, "number_of_buildings_in_bpd": 1066891, "number_of_matching_building_years": 16349, "number_of_matching_buildings": 3586, "percentile_0": [2008.0, 4.811113347264607], "percentile_100": [2017.0, 2991.1806545711174], "percentile_25": [2014.0, 72.89874308294019], "percentile_50": [2015.0, 97.02420527753938], "percentile_75": [2016.0, 155.43307905630786], "mean": [2014.9707820738138, 148.01008410698321] "standard_deviation": [1.4533781571350493, 178.94704302433345]}, "metadata": ...}