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 bpd-support@lbl.gov. For more information about the BPD, visit bpd-info.lbl.gov. To access the BPD Graphical User Interface (GUI), visit bpd.lbl.gov.
Getting Started
The API URL is: https://bpd-api.lbl.gov
Queries must include the following headers to authorize the user:
{"Content-Type": "application/json",
"Authorization": "ApiKey USER_NAME:API_KEY"}
To obtain a user name and API key, email us at bpd-support@lbl.gov.
For Python users, the bpd_api library provides functions for each of the API endpoints.
Categorical Fields
|
Name |
Description |
Values |
|---|---|---|
|
Name zip_code |
Description 5-digit ZIP code in which the building is located. |
Values 94720, 94103, 10007, ... |
|
Name city |
Description City in which the building is located. |
Values Berkeley, San Francisco, New York, ... |
|
Name state |
Description State in which the building is located. |
Values CA, NY, FL, TX, ... |
|
Name climate |
Description ASHRAE climate zone in which the building is located. |
Values 3C Warm - Marine (San Francisco-CA), ... |
|
Name building_class |
Description General classification of the building. |
Values Commercial, Residential |
|
Name facility_type |
Description Primary use type of the building. |
Values Laboratory, Food Sales, Data Center, ... |
|
Name lighting |
Description Type of lighting system. |
Values LED, Fluorescent - T8, Incandescent, ... |
|
Name air_flow_control |
Description Whether the HVAC system is VAV or CAV based. |
Values Variable Volume, Constant Volume, ... |
|
Name heating |
Description Type of heating system. |
Values Furnace, Boiler - Steam, Perimeter Baseboard, ... |
|
Name heating_fuel |
Description Fuel used for heating. |
Values Natural Gas, District Steam, Electricity, ... |
|
Name cooling |
Description Type of cooling system. |
Values Split AC System, Evaporative Cooler, ... |
|
Name wall_type |
Description Type of walls. |
Values Brick, Concrete - Panels, Sheet Metal, ... |
|
Name roof_ceiling |
Description Type of roof. |
Values Built-up, Shingles, Concrete, ... |
|
Name window_glass_layers |
Description Numbers of window layers. |
Values Single-pane, Double-pane, ... |
|
Name window_glass_type |
Description Type of window glass. |
Values Clear, Tinted, Reflective, ... |
|
Name energy_star_label |
Description Whether or not the building has an ENERGY STAR label. |
Values Labeled, Not Labeled, Unknown |
|
Name leed_score |
Description Type of LEED certification. |
Values Platinum, Gold, Silver, ... |
|
Name data_source |
Description Name of the original data source. |
Values 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/ft2/year |
|
fuel_eui |
Annual fuel energy use intensity. Includes all non-electric fuels. |
0 |
1000 |
kBtu/ft2/year |
|
site_eui |
Annual site energy use intensity. |
1 |
1000 |
kBtu/ft2/year |
|
source_eui |
Annual source energy use intensity. |
1 |
3140 |
kBtu/ft2/year |
|
ghg_emissions_int |
Annual greenhouse gas (GHG) emissions intensity. |
0 |
400 |
kgCO2e/ft2/year |
|
floor_area |
Gross floor area of the building. |
500 |
7000000 |
ft2 |
|
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 ft2 |
|
operating_hours |
Weekly number of hours the building is operating. |
0 |
168 |
hours/week |
|
wall_insulation_r_value |
R-value of exterior walls. |
0 |
60 |
R-value |
|
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 ft2 and <= 2000 ft2.
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 ft2 or > 2000 ft2.
filters = {"floor_area": {"min": 500,
"max": 2000,
"exclude": True}}
Example 5: Selecting buildings whose floor area is between 500 ft2 and 2000 ft2 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 |
|---|---|
|
Characteristic Method |
Value GET |
|
Characteristic URL |
Value |
|
Characteristic Description |
Value Returns general information about the API. |
Response
|
Property |
Type |
Description |
|---|---|---|
|
Property message |
Type JSON object |
Description General information about the API (see below). |
|
Property metadata |
Type JSON object |
Description General information about the request (see Metadata section above). |
Response: message
|
Property |
Type |
Description |
|---|---|---|
|
Property url |
Type string |
Description URL of the API documentation. |
|
Property version |
Type string |
Description Current version of the API. |
|
Property ip |
Type string |
Description IP address of the API server. |
Examples
Example 1: General information about the API.
Request URL: https://bpd-api.lbl.gov/
Response: {"message": {"url": "https://bpd-api-docs.lbl.gov",
"version": "2.4.0",
"ip": "172.33.59.46"},
"metadata": ...}
|
Characteristic |
Value |
|---|---|
|
Characteristic Method |
Value GET |
|
Characteristic URL |
Value |
|
Characteristic Description |
Value Returns a list of all fields. Optionally, returns only numerical fields or only categorical fields. |
Parameters
|
Property |
Type |
Optional |
Description |
|---|---|---|---|
|
Property field_type |
Type string |
Optional True |
Description 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 |
|---|---|---|
|
Property fields |
Type list of lists |
Description The name and type of each field. |
|
Property metadata |
Type JSON object |
Description General information about the request (see Metadata section above). |
Examples
Example 1: List of all fields.
Request URL: https://bpd-api.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://bpd-api.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 |
|---|---|
|
Characteristic Method |
Value GET |
|
Characteristic URL |
Value https://bpd-api.lbl.gov/api/v2/introspection/fields/field_name |
|
Characteristic Description |
Value 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 |
|---|---|---|---|
|
Property field_name |
Type field |
Optional False |
Description The field to return the field information for. Specified in URL (see examples below). |
|
Property building_class |
Type string |
Optional True |
Description 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 |
|---|---|---|
|
Property field_info |
Type JSON object |
Description 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. |
|
Property metadata |
Type JSON object |
Description General information about the request (see Metadata section above). |
Examples
Example 1: Legal values of the climate field.
Request URL: https://bpd-api.lbl.gov/api/v2/introspection/fields/climate
Response: {"field_info": {"name": "climate",
"type": "categorical",
"values": ["1A Very Hot - Humid (Miami-FL)",
"2A Hot - Humid (Houston-TX)",
"2B Hot - Dry (Phoenix-AZ)",
...,
"8 Subarctic (Fairbanks-AK)",
"Unknown"]},
"metadata": ...}
Example 2: Minimum and maximum legal values of the operating_hours field.
Request URL: https://bpd-api.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://bpd-api.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 |
|---|---|
|
Characteristic Method |
Value POST |
|
Characteristic URL |
Value |
|
Characteristic Description |
Value Returns the number of buildings matching the specified filters. |
Parameters
|
Property |
Type |
Optional |
Description |
|---|---|---|---|
|
Property filters |
Type JSON object |
Optional True |
Description Filters defining the set of buildings to be included (see Filters section above). Defaults to including all buildings. |
Response
|
Property |
Type |
Description |
|---|---|---|
|
Property totals |
Type JSON object |
Description Number of buildings matching the filters (see below). |
|
Property modified |
Type boolean |
Description True if fewer than 10 buildings match the filters. If True, totals are set to zero. Only returned if True. |
|
Property metadata |
Type JSON object |
Description General information about the request (see Metadata section above). |
Response: totals
|
Property |
Type |
Description |
|---|---|---|
|
Property number_of_matching_buildings |
Type integer |
Description Number of buildings matching the filters. |
|
Property number_of_buildings_in_bpd |
Type integer |
Description Total number of buildings in the BPD. |
|
Property number_of_matching_building_years |
Type integer |
Description Number of building-years matching the filters. |
|
Property number_of_building_years_in_bpd |
Type integer |
Description Total number of building-years 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 |
|---|---|
|
Characteristic Method |
Value POST |
|
Characteristic URL |
Value |
|
Characteristic Description |
Value Returns a histogram with bins defined by the specified field. |
Parameters
|
Property |
Type |
Optional |
Description |
|---|---|---|---|
|
Property group_by |
Type list of fields |
Optional False |
Description Fields used to define the histogram bins. |
|
Property filters |
Type JSON object |
Optional True |
Description Filters defining the set of buildings to be included (see Filters section above). Defaults to including all buildings. |
|
Property resolution |
Type string |
Optional True |
Description 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. |
|
Property include_all_years |
Type boolean |
Optional True |
Description 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 |
|---|---|---|
|
Property groups |
Type list of JSON objects |
Description Groups defining the histogram bins. |
|
Property counts |
Type list of integers |
Description Number of buildings in each of the bins. |
|
Property counts_modified_mask |
Type list of integers |
Description 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. |
|
Property mean |
Type float |
Description Mean of the counts. |
|
Property standard_deviation |
Type float |
Description Standard deviation of the counts. |
|
Property quartiles |
Type list of floats |
Description 0th, 25th, 50th, 75th, and 100th percentiles of the counts (where the 0th percentile is the minimum and the 100th percentile is the maximum). |
|
Property totals |
Type JSON object |
Description Number of buildings matching the filters and summary statistics of the group_by field (see below). |
|
Property metadata |
Type JSON object |
Description General information about the request (see Metadata section above). |
Response: totals
|
Property |
Type |
Description |
|---|---|---|
|
Property number_of_matching_buildings |
Type integer |
Description Number of buildings matching the filters, and having data for the group_by field. |
|
Property number_of_buildings_in_bpd |
Type integer |
Description Total number of buildings in the BPD. |
|
Property number_of_matching_building_years |
Type integer |
Description Number of building-years matching the filters, and having data for the group_by field. |
|
Property number_of_building_years_in_bpd |
Type integer |
Description Total number of building-years in the BPD. |
|
Property percentile_0 |
Type float |
Description Minimum value of the group_by field. False if group_by is categorical. |
|
Property percentile_25 |
Type float |
Description 25th percentile of the group_by field. False if group_by is categorical. |
|
Property percentile_50 |
Type float |
Description 50th percentile of the group_by field. False if group_by is categorical. |
|
Property percentile_75 |
Type float |
Description 75th percentile of the group_by field. False if group_by is categorical. |
|
Property percentile_100 |
Type float |
Description Maximum value of the group_by field. False if group_by is categorical. |
|
Property mean |
Type float |
Description Mean of the group_by field. False if group_by is categorical. |
|
Property standard_deviation |
Type float |
Description 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": "0-10 kBtu/sqft/yr",
"min": 0.0,
"max": 10.0}},
{"field": "fuel_eui",
"type": "numerical",
"name": "10-20 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 |
|---|---|
|
Characteristic Method |
Value POST |
|
Characteristic URL |
Value |
|
Characteristic Description |
Value Returns summary statistics of a specified numerical variable for each group of buildings, as defined by a specified field. |
Parameters
|
Property |
Type |
Optional |
Description |
|---|---|---|---|
|
Property analyze_by |
Type numerical field |
Optional False |
Description Numerical field to compute the summary statistics on. |
|
Property group_by |
Type list of fields |
Optional False |
Description Fields used to define the table groups. |
|
Property filters |
Type JSON object |
Optional True |
Description Filters defining the set of buildings to be included (see Filters section above). Defaults to including all buildings. |
|
Property resolution |
Type string |
Optional True |
Description 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. |
|
Property include_all_years |
Type boolean |
Optional True |
Description 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 |
|---|---|---|
|
Property table |
Type list of JSON objects |
Description Summary statistics of the analyze_by field for the buildings in each group (see below). |
|
Property summary |
Type JSON object |
Description Summary statistics of the analyze_by field for the buildings in all groups. |
|
Property totals |
Type JSON object |
Description Number of buildings matching the filters (see below). |
|
Property metadata |
Type JSON object |
Description General information about the request (see Metadata section above). |
Response: table
|
Property |
Type |
Description |
|---|---|---|
|
Property group |
Type JSON object |
Description Definition of the group. |
|
Property modified |
Type boolean |
Description 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. |
|
Property count |
Type integer |
Description Number of buildings in the group. Zero if no buildings in group or group has been modified. |
|
Property percentile_0 |
Type float |
Description Minimum value of the analyze_by field for buildings in the group. Null if no buildings in group or group has been modified. |
|
Property percentile_25 |
Type float |
Description 25th percentile of the analyze_by field for buildings in the group. Null if no buildings in group or group has been modified. |
|
Property percentile_50 |
Type float |
Description 50th percentile of the analyze_by field for buildings in the group. Null if no buildings in group or group has been modified. |
|
Property percentile_75 |
Type float |
Description 75th percentile of the analyze_by field for buildings in the group. Null if no buildings in group or group has been modified. |
|
Property percentile_100 |
Type float |
Description Maximum value of the analyze_by field within the group. Null if no buildings in group or group has been modified. |
|
Property mean |
Type float |
Description Mean of the analyze_by field for buildings in the group. Null if no buildings in group or group has been modified. |
|
Property standard_deviation |
Type float |
Description 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 |
|---|---|---|
|
Property number_of_matching_buildings |
Type integer |
Description Number of buildings matching the filters, and having data for the analyze_by and group_by fields. |
|
Property number_of_buildings_in_bpd |
Type integer |
Description Total number of buildings in the BPD. |
|
Property number_of_matching_building_years |
Type integer |
Description Number of building-years matching the filters, and having data for the analyze_by and group_by fields. |
|
Property number_of_building_years_in_bpd |
Type integer |
Description Total number of building-years 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 |
|---|---|
|
Characteristic Method |
Value POST |
|
Characteristic URL |
Value |
|
Characteristic Description |
Value Returns a random sample of up to 3 fields for up to 1000 buildings. |
Parameters
|
Property |
Type |
Optional |
Description |
|---|---|---|---|
|
Property x-axis |
Type field |
Optional False |
Description First field to include in sample. |
|
Property y-axis |
Type field |
Optional True |
Description Second field to include in sample. Defaults to nothing. |
|
Property additional_fields |
Type list of fields |
Optional True |
Description Additional fields to include in sample. Defaults to empty list. |
|
Property filters |
Type JSON object |
Optional True |
Description Filters defining the set of buildings to be included (see Filters section above). Defaults to including all buildings. |
|
Property limit |
Type integer |
Optional True |
Description Maximum number of buildings to return samples for. Maximum value is 1000. Defaults to 1000. |
|
Property include_all_years |
Type boolean |
Optional True |
Description 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 |
|---|---|---|
|
Property scatterplot |
Type list of lists |
Description Sampled values of each field for each building. |
|
Property totals |
Type JSON object |
Description Number of buildings matching the filters and summary statistics of the sampled fields (see below). |
|
Property metadata |
Type JSON object |
Description General information about the request (see Metadata section above). |
Response: totals
|
Property |
Type |
Description |
|---|---|---|
|
Property number_of_matching_buildings |
Type integer |
Description Number of buildings matching the filters, and having data for the x-axis, y-axis, and additional_fields fields. |
|
Property number_of_buildings_in_bpd |
Type integer |
Description Total number of buildings in the BPD. |
|
Property number_of_matching_building_years |
Type integer |
Description Number of building-years matching the filters, and having data for the x-axis, y-axis, and additional_fields fields. |
|
Property number_of_building_years_in_bpd |
Type integer |
Description Total number of building-years in the BPD. |
|
Property percentile_0 |
Type list of floats |
Description Minimum value of each of the sampled fields. False if field is categorical. |
|
Property percentile_25 |
Type list of floats |
Description 25th percentile of each of the sampled fields. False if field is categorical. |
|
Property percentile_50 |
Type list of floats |
Description 50th percentile of each of the sampled fields. False if field is categorical. |
|
Property percentile_75 |
Type list of floats |
Description 75th percentile of each of the sampled fields. False if field is categorical. |
|
Property percentile_100 |
Type list of floats |
Description Maximum value of each of the sampled fields. False if field is categorical. |
|
Property mean |
Type list of floats |
Description Mean of each of the sampled fields. False if field is categorical. |
|
Property standard_deviation |
Type list of floats |
Description 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"]},
"x-axis": "floor_area",
"y-axis": "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 |
|---|---|
|
Characteristic Method |
Value POST |
|
Characteristic URL |
Value |
|
Characteristic Parameter |
Value method = "actuarial" |
|
Characteristic Description |
Value 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 |
|---|---|---|---|
|
Property analyze_by |
Type numerical field |
Optional False |
Description Numerical field to compute differences for. |
|
Property base |
Type JSON object |
Optional False |
Description Filters defining the set of buildings to be included in both the "from" and "to" groups (see Filters section above). |
|
Property from |
Type JSON object |
Optional False |
Description 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. |
|
Property to |
Type JSON object |
Optional False |
Description 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. |
|
Property method |
Type string |
Optional True |
Description Method used to compute the differences. Either "actuarial" or "regression". Defaults to "actuarial". |
|
Property include_all_years |
Type boolean |
Optional True |
Description 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 |
|---|---|---|
|
Property groups |
Type list of JSON objects |
Description Groups defining the histogram bins. |
|
Property counts |
Type list of integers |
Description Number of buildings in each of the bins. |
|
Property statistics |
Type JSON object |
Description Summary statistics of the computed differences (see below). |
|
Property totals |
Type JSON object |
Description Number of buildings matching the filters (see below). |
|
Property metadata |
Type JSON object |
Description General information about the request (see Metadata section above). |
Response: statistics
|
Property |
Type |
Description |
|---|---|---|
|
Property percentile_0 |
Type float |
Description Minimum value of the differences. |
|
Property percentile_25 |
Type float |
Description 25th percentile of the differences. |
|
Property percentile_50 |
Type float |
Description 50th percentile of the differences. |
|
Property percentile_75 |
Type float |
Description 75th percentile of the differences. |
|
Property percentile_100 |
Type float |
Description Maximum value of the differences. |
|
Property mean |
Type float |
Description Mean of the differences. |
|
Property standard_deviation |
Type float |
Description Standard deviation of the differences. |
Response: totals
|
Property |
Type |
Description |
|---|---|---|
|
Property number_of_matching_buildings |
Type integer |
Description Number of buildings matching the "base" filters and either the "from" or "to" filters, and having data for the analyze_by field. |
|
Property number_of_buildings_in_bpd |
Type integer |
Description Total number of buildings in the BPD. |
|
Property number_of_pre_matching_buildings |
Type integer |
Description Number of buildings matching the "base" and "from" filters, and having data for the analyze_by field. |
|
Property number_of_post_matching_buildings |
Type integer |
Description Number of buildings matching the "base" and "to" filters, and having data for the analyze_by field. |
|
Property number_of_matching_building_years |
Type integer |
Description Number of building-years matching the "base" filters and either the "from" or "to" filters, and having data for the analyze_by field. |
|
Property number_of_building_years_in_bpd |
Type integer |
Description Total number of building-years in the BPD. |
|
Property number_of_pre_matching_building_years |
Type integer |
Description Number of building-years matching the "base" and "from" filters, and having data for the analyze_by field. |
|
Property number_of_post_matching_building_years |
Type integer |
Description Number of building-years 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 |
|---|---|
|
Characteristic Method |
Value POST |
|
Characteristic URL |
Value |
|
Characteristic Parameter |
Value method = "regression" |
|
Characteristic Description |
Value 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 |
|---|---|---|---|
|
Property analyze_by |
Type numerical field |
Optional False |
Description Numerical field to compute differences for. Either "electric_eui", "fuel_eui", "site_eui", "source_eui", or "ghg_emissions_int". |
|
Property base |
Type JSON object |
Optional False |
Description 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). |
|
Property from |
Type JSON object |
Optional False |
Description 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). |
|
Property to |
Type JSON object |
Optional False |
Description 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). |
|
Property method |
Type string |
Optional True |
Description Method used to compute the differences. Either "actuarial" or "regression". Defaults to "actuarial". |
|
Property include_all_years |
Type boolean |
Optional True |
Description 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 |
|---|---|---|
|
Property groups |
Type list of JSON objects |
Description Groups defining the histogram bins. |
|
Property counts |
Type list of integers |
Description Number of buildings in each of the bins. |
|
Property statistics |
Type JSON object |
Description Summary statistics of the computed differences (see below). |
|
Property totals |
Type JSON object |
Description Number of buildings matching the filters (see below). |
|
Property metadata |
Type JSON object |
Description General information about the request (see Metadata section above). |
Response: statistics
|
Property |
Type |
Description |
|---|---|---|
|
Property percentile_0 |
Type float |
Description Minimum value of the differences. |
|
Property percentile_25 |
Type float |
Description 25th percentile of the differences. |
|
Property percentile_50 |
Type float |
Description 50th percentile of the differences. |
|
Property percentile_75 |
Type float |
Description 75th percentile of the differences. |
|
Property percentile_100 |
Type float |
Description Maximum value of the differences. |
|
Property mean |
Type float |
Description Mean of the differences. |
|
Property standard_deviation |
Type float |
Description Standard deviation of the differences. |
Response: totals
|
Property |
Type |
Description |
|---|---|---|
|
Property number_of_matching_buildings |
Type integer |
Description Number of buildings matching the "base" filters, and having data for the analyze_by field. |
|
Property number_of_buildings_in_bpd |
Type integer |
Description Total number of buildings in the BPD. |
|
Property number_of_pre_matching_buildings |
Type integer |
Description Number of buildings matching the "base" and "from" filters, and having data for the analyze_by field. |
|
Property number_of_post_matching_buildings |
Type integer |
Description Number of buildings matching the "base" and "to" filters, and having data for the analyze_by field. |
|
Property number_of_matching_building_years |
Type integer |
Description Number of building-years matching the "base" filters, and having data for the analyze_by field. |
|
Property number_of_building_years_in_bpd |
Type integer |
Description Total number of building-years in the BPD. |
|
Property number_of_pre_matching_building_years |
Type integer |
Description Number of building-years matching the "base" and "from" filters, and having data for the analyze_by field. |
|
Property number_of_post_matching_building_years |
Type integer |
Description Number of building-years 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 |
|---|---|
|
Characteristic Method |
Value POST |
|
Characteristic URL |
Value |
|
Characteristic Description |
Value Returns coefficients and fit statistics for a linear regression model fit using the specified dependent and independent variables. |
Parameters
|
Property |
Type |
Optional |
Description |
|---|---|---|---|
|
Property x-fields |
Type list of Field Strings |
Optional False |
Description 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. |
|
Property y-field |
Type Field String |
Optional False |
Description Numerical field to be used as the dependent variable in the model. |
|
Property filters |
Type JSON object |
Optional True |
Description Filters defining the set of buildings to be included (see Filters section above). Defaults to including all buildings. |
|
Property log_fields |
Type list of Field Strings |
Optional True |
Description Numerical fields (dependent or independent) that should be transformed by the natural logarithm before fitting the model. Defaults to not transforming any fields. |
|
Property include_all_years |
Type boolean |
Optional True |
Description 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 |
|---|---|---|
|
Property coefficients |
Type JSON object |
Description 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. |
|
Property statistics |
Type JSON object |
Description Summary statistics related to the coefficients and the model fit (see below). |
|
Property totals |
Type JSON object |
Description Number of buildings matching the filters (see below). |
|
Property metadata |
Type JSON object |
Description General information about the request (see Metadata section above). |
Response: statistics
|
Property |
Type |
Description |
|---|---|---|
|
Property aic |
Type float |
Description Akaike information criterion value of the model. |
|
Property df_resid |
Type integer |
Description Residual degrees of freedom of the model. |
|
Property f_pvalue |
Type float |
Description p-value of the F-statistic of the model. |
|
Property fvalue |
Type float |
Description F-statistic of the model. |
|
Property log-likelihood |
Type float |
Description Log-likelihood of the model. |
|
Property nobs |
Type integer |
Description Number of observations used to fit the model. Buildings with missing data for numerical variables are excluded when fitting the model. |
|
Property p_values |
Type JSON Object |
Description p-value corresponding to the t-value associated with each of the model coefficients. |
|
Property residual |
Type float |
Description Sum of the squared residuals. |
|
Property rsquared |
Type float |
Description Coefficient of determination. |
|
Property std_errors |
Type JSON Object |
Description Standard error associated with each of the model coefficients. |
|
Property t_values |
Type JSON Object |
Description t-value associated with each of the model coefficients. |
Response: totals
|
Property |
Type |
Description |
|---|---|---|
|
Property number_of_matching_buildings |
Type integer |
Description Number of buildings matching the filters. |
|
Property number_of_buildings_in_bpd |
Type integer |
Description Total number of buildings in the BPD. |
|
Property number_of_matching_building_years |
Type integer |
Description Number of building-years matching the filters. |
|
Property number_of_building_years_in_bpd |
Type integer |
Description Total number of building-years 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"]},
"x-fields": ["energy_star_rating", "climate"],
"y-field": "site_eui"}
Response: {"coefficients": {"climate": {"2B Hot - Dry (Phoenix-AZ)": -3.863999035566146,
...,
"5B Cool - Dry (Boise-ID)": null},
"energy_star_rating": -1.639027103422914,
"intercept": 178.89859848709875},
"statistics": {"aic": 56463.974026323776,
"df_resid": 5314.0,
"f_pvalue": 0.0,
"fvalue": 393.84467577217305,
"log-likelihood": -28224.987013161888,
"nobs": 5321.0,
"p_values": {"climate": {"2B Hot - Dry (Phoenix-AZ)": 0.8600352637941979,
...,
"5B Cool - Dry (Boise-ID)": null},
"energy_star_rating": 0.0,
"intercept": 5.098189412681182e-38},
"residual": 12615574.585443843,
"rsquared": 0.30780866312718813,
"std_errors": {"climate": {"2B Hot - Dry (Phoenix-AZ)": 21.912479319381085,
...,
"5B Cool - Dry (Boise-ID)": null},
"energy_star_rating": 0.033838066179026564,
"intercept": 13.76943743371712},
"t_values": {"climate": {"2B Hot - Dry (Phoenix-AZ)": -0.17633782919984448,
...,
"5B Cool - Dry (Boise-ID)": 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"]},
"x-fields": ["city", "operating_hours", "floor_area"],
"y-field": "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 |
|---|---|
|
Characteristic Method |
Value POST |
|
Characteristic URL |
Value |
|
Characteristic Description |
Value 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 |
|---|---|---|---|
|
Property data_fields |
Type list of fields |
Optional False |
Description Fields to include in the sample. Must include "year" and 1 or 2 additional fields. |
|
Property filters |
Type JSON object |
Optional True |
Description Filters defining the set of buildings to be included (see Filters section above). Defaults to including all buildings. |
|
Property limit |
Type integer |
Optional True |
Description Maximum number of buildings to return samples for. Maximum value is 1000. Defaults to 1000. |
|
Property min_data_years |
Type integer |
Optional True |
Description Number of years of data a building must have to be included in the results. |
Response
|
Property |
Type |
Description |
|---|---|---|
|
Property multiyear |
Type list of lists of lists |
Description Sampled values for each field, for each building, and for each year. |
|
Property statistics |
Type JSON object |
Description Summary statistics of the sampled fields for each year (see below). |
|
Property totals |
Type JSON object |
Description Number of buildings matching the filters and summary statistics of the sampled fields (see below). |
|
Property metadata |
Type JSON object |
Description General information about the request (see Metadata section above). |
Response: statistics
|
Property |
Type |
Description |
|---|---|---|
|
Property year |
Type list of floats |
Description Years the statistics correspond to. |
|
Property count |
Type list of floats |
Description Number of buildings with data in each year. |
|
Property mean |
Type list of lists of floats |
Description Mean of each data field in each year. |
|
Property standard_deviation |
Type list of lists of floats |
Description Standard deviation of each data field in each year. |
|
Property percentile_0 |
Type list of lists of floats |
Description Minimum value of each data field in each year. |
|
Property percentile_25 |
Type list of lists of floats |
Description 25th percentile of each data field in each year. |
|
Property percentile_50 |
Type list of lists of floats |
Description 50th percentile of each data field in each year. |
|
Property percentile_75 |
Type list of lists of floats |
Description 75th percentile of each data field in each year. |
|
Property percentile_100 |
Type list of lists of floats |
Description Maximum value of each data field in each year. |
Response: totals
|
Property |
Type |
Description |
|---|---|---|
|
Property number_of_matching_buildings |
Type integer |
Description Number of buildings matching the filters, and having data for the data_fields fields. |
|
Property number_of_buildings_in_bpd |
Type integer |
Description Total number of buildings in the BPD. |
|
Property number_of_matching_building_years |
Type integer |
Description Number of building-years matching the filters, and having data for the data_fields fields. |
|
Property number_of_building_years_in_bpd |
Type integer |
Description Total number of building-years in the BPD. |
|
Property percentile_0 |
Type list of floats |
Description Minimum value of each of the sampled fields. False if field is categorical. |
|
Property percentile_25 |
Type list of floats |
Description 25th percentile of each of the sampled fields. False if field is categorical. |
|
Property percentile_50 |
Type list of floats |
Description 50th percentile of each of the sampled fields. False if field is categorical. |
|
Property percentile_75 |
Type list of floats |
Description 75th percentile of each of the sampled fields. False if field is categorical. |
|
Property percentile_100 |
Type list of floats |
Description Maximum value of each of the sampled fields. False if field is categorical. |
|
Property mean |
Type list of floats |
Description Mean of each of the sampled fields. False if field is categorical. |
|
Property standard_deviation |
Type list of floats |
Description 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": ...}