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 bpd-info.lbl.gov. To access the BPD Graphical User Interface (GUI), visit bpd.lbl.gov.
Getting Started
Access
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 [email protected].
For Python users, the bpd_api library provides functions for each of the API endpoints.
Fields
Categorical Fields
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 |
Filters
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"]}
Metadata
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
Root
Characteristic | Value |
|---|---|
| Method | GET |
| URL | https://bpd-api.lbl.gov/ |
| 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://bpd-api.lbl.gov/
Response: {"message": {"url": "https://bpd-api-docs.lbl.gov",
"version": "2.4.0",
"ip": "172.33.59.46"},
"metadata": ...}
Fields
Characteristic | Value |
|---|---|
| Method | GET |
| URL | https://bpd-api.lbl.gov/api/v2/introspection/fields |
| 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://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": ...}
Field Info
Characteristic | Value |
|---|---|
| Method | GET |
| URL | https://bpd-api.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 of the values of building_class (see Fields above). Can only be used with field_name = "facility_type". Specified in URL (see example below). |
| building_sector | string | True | The sector of buildings to return building categories for. Either of the values of building_sector (see Fields above). Can only be used with field_name = "building_category". Specified in URL (see example below). |
| building_category | string | True | The category of buildings to return building types for. Either of the values of building_category (see Fields above). Can only be used with field_name = "building_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://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": ...}
Count
Characteristic | Value |
|---|---|
| Method | POST |
| URL | https://bpd-api.lbl.gov/api/v2/analyze/count |
| 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 building-years matching the filters. |
| number_of_building_years_in_bpd | integer | 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": ...}
Histogram
Characteristic | Value |
|---|---|
| Method | POST |
| URL | https://bpd-api.lbl.gov/api/v2/analyze/histogram |
| 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 building-years matching the filters, and having data for the group_by field. |
| number_of_building_years_in_bpd | integer | Total number of building-years in the BPD. |
| percentile_0 | float | Minimum value of the group_by field. False if group_by is categorical. |
| percentile_25 | float | 25th 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 | 75th 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": "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": ...}
Table
Characteristic | Value |
|---|---|
| Method | POST |
| URL | https://bpd-api.lbl.gov/api/v2/analyze/table |
| 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 building-years matching the filters, and having data for the analyze_by and group_by fields. |
| number_of_building_years_in_bpd | integer | 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": ...}
Scatterplot
Characteristic | Value |
|---|---|
| Method | POST |
| URL | https://bpd-api.lbl.gov/api/v2/analyze/scatterplot |
| Description | Returns a random sample of up to 3 fields for up to 1000 buildings. |
Parameters
Property | Type | Optional | Description |
|---|---|---|---|
| x-axis | field | False | First field to include in sample. |
| y-axis | 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 x-axis, y-axis, 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 building-years matching the filters, and having data for the x-axis, y-axis, and additional_fields fields. |
| number_of_building_years_in_bpd | integer | Total number of building-years 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 | 25th 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 | 75th 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"]},
"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": ...}
Compare - Actuarial
Characteristic | Value |
|---|---|
| Method | POST |
| URL | https://bpd-api.lbl.gov/api/v2/analyze/compare/peer-group |
| 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 building-years 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 building-years in the BPD. |
| number_of_pre_matching_building_years | integer | Number of building-years matching the "base" and "from" filters, and having data for the analyze_by field. |
| number_of_post_matching_building_years | integer | 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": ...}
Compare - Regression
Characteristic | Value |
|---|---|
| Method | POST |
| URL | https://bpd-api.lbl.gov/api/v2/analyze/compare/peer-group |
| 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 building-years matching the "base" filters, and having data for the analyze_by field. |
| number_of_building_years_in_bpd | integer | Total number of building-years in the BPD. |
| number_of_pre_matching_building_years | integer | Number of building-years matching the "base" and "from" filters, and having data for the analyze_by field. |
| number_of_post_matching_building_years | integer | 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": ...}
Linear Regression
Characteristic | Value |
|---|---|
| Method | POST |
| URL | https://bpd-api.lbl.gov/api/v2/analyze/linear |
| Description | Returns coefficients and fit statistics for a linear regression model fit using the specified dependent and independent variables. |
Parameters
Property | Type | Optional | Description |
|---|---|---|---|
| x-fields | 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. |
| y-field | 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 | p-value of the F-statistic of the model. |
| fvalue | float | F-statistic of the model. |
| log-likelihood | float | Log-likelihood 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 | p-value corresponding to the t-value 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 | t-value 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 building-years matching the filters. |
| number_of_building_years_in_bpd | integer | 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" ...}
Multiyear
Characteristic | Value |
|---|---|
| Method | POST |
| URL | https://bpd-api.lbl.gov/api/v2/analyze/multiyear |
| 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 building-years matching the filters, and having data for the data_fields fields. |
| number_of_building_years_in_bpd | integer | Total number of building-years 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 | 25th 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 | 75th 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": ...}
Treemap
Characteristic | Value |
|---|---|
| Method | POST |
| URL | https://bpd-api.lbl.gov/api/v2/analyze/treemap |
| Description | Returns summary statistics (count, total floor area, and mean of a specified numerical variable) for each building sector, category, and type. |
Parameters
Property | Type | Optional | Description |
|---|---|---|---|
| analyze_by | numerical field | False | Numerical field to compute the mean on. |
| filters | JSON object | True | Filters defining the set of buildings to be included (see Filters section above). Defaults to including all buildings. |
| 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 |
|---|---|---|
| treemap | list of JSON objects | Summary statistics for each building sector, category, and type of the buildings matching the filters (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: treemap
Property | Type | Description |
|---|---|---|
| name | string | Name of the group, i.e., ALL, corresponding to all buildings matching the filters. |
| count | integer | Number of buildings in the group. Zero if group has been modified. |
| area | float | Sum of the floor_area field for buildings in the group. Null if group has been modified. |
| mean | float | Mean of the analyze_by field for buildings in the group. Null if group has been modified. |
| modified | boolean | True if less than 10 buildings in group. If True, area and mean fields are set to null. Only returned if True. |
| building_sector | list of JSON objects | Summary statistics for each building sector (see below). Sectors with no buildings are not included. |
Response: treemap: building_sector
Property | Type | Description |
|---|---|---|
| name | string | Name of the group, i.e., the building sector, corresponding to all buildings in the building sector and matching the filters. |
| count | integer | Number of buildings in the group. Zero if group has been modified. |
| area | float | Sum of the floor_area field for buildings in the group. Null if group has been modified. |
| mean | float | Mean of the analyze_by field for buildings in the group. Null if group has been modified. |
| modified | boolean | True if less than 10 buildings in group. If True, area and mean fields are set to null. Only returned if True. |
| building_category | list of JSON objects | Summary statistics for each building category (see below). Categories with no buildings are not included. |
Response: treemap: building_sector: building_category
Property | Type | Description |
|---|---|---|
| name | string | Name of the group, i.e., the building category, corresponding to all buildings in the building category and matching the filters. |
| count | integer | Number of buildings in the group. Zero if group has been modified. |
| area | float | Sum of the floor_area field for buildings in the group. Null if group has been modified. |
| mean | float | Mean of the analyze_by field for buildings in the group. Null if group has been modified. |
| modified | boolean | True if less than 10 buildings in group. If True, area and mean fields are set to null. Only returned if True. |
| building_category | list of JSON objects | Summary statistics for each building type (see below). Types with no buildings are not included. |
Response: treemap: building_sector: building_category: building_type
Property | Type | Description |
|---|---|---|
| name | string | Name of the group, i.e., the building type, corresponding to all buildings in the building type and matching the filters. |
| count | integer | Number of buildings in the group. Zero if group has been modified. |
| area | float | Sum of the floor_area field for buildings in the group. Null if group has been modified. |
| mean | float | Mean of the analyze_by field for buildings in the group. Null if group has been modified. |
| modified | boolean | True if less than 10 buildings in group. If True, area and mean fields are set to null. Only returned if True. |
Response: totals
Property | Type | Description |
|---|---|---|
| number_of_matching_buildings | integer | Number of buildings matching the filters, and having data for the analyze_by field. |
| number_of_buildings_in_bpd | integer | Total number of buildings in the BPD. |
| number_of_matching_building_years | integer | Number of building-years matching the filters, and having data for the analyze_by field. |
| number_of_building_years_in_bpd | integer | Total number of building-years in the BPD. |
Examples
Example 1: Summary statistics of site_eui for each building sector, category, and type for buildings in San Francisco, CA.
Request parameters: {"filters": {"state": ["CA"], "city": ["San Francisco"]},
"analyze_by": "site_eui"}
Response: {"treemap": {
"name": "ALL",
"count": 4313,
"area": 929026799.0,
"mean": 49.8087627853341,
"building_sector": [
{"name": "Commercial",
"count": 2505,
"area": 655098316.0,
"mean": 56.306141651153254,
"building_category": [
{"name": "Education",
"count": 226,
"area": 37876588.0,
"mean": 41.434389598066375,
"building_type": [
{"name": "College/University",
"count": 58,
"area": 16245308.0,
"mean": 56.281152914953445},
{"name": "Pre-school/Daycare",
"count": 0,
"area": null,
"mean": null,
"modified": True},
{...},
{...}]},
{"name": "Healthcare",
"count": 97,
"area": 18759037.0,
"mean": 104.67367608155979,
"building_type": [...]},
{...},
{...}]},
{"name": "Mixed Use",
"count": 1017,
"area": 143423896.0,
"mean": 42.48123953065831,
"building_category": [...]}]}},
"totals": ...,
"metadata": ...}