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

Name

Description

Values

zip_code

5-digit ZIP code in which the building is located.

94720, 94103, 10007, ...

city

City in which the building is located.

Berkeley, San Francisco, New York, ...

state

State in which the building is located.

CA, NY, FL, TX, ...

climate

ASHRAE climate zone in which the building is located.

3C Warm - Marine (San Francisco-CA), ...

building_class

General classification of the building.

Commercial, Residential

facility_type

Primary use type of the building.

Laboratory, Food Sales, Data Center, ...

lighting

Type of lighting system.

LED, Fluorescent - T8, Incandescent, ...

air_flow_control

Whether the HVAC system is VAV or CAV based.

Variable Volume, Constant Volume, ...

heating

Type of heating system.

Furnace, Boiler - Steam, Perimeter Baseboard, ...

heating_fuel

Fuel used for heating.

Natural Gas, District Steam, Electricity, ...

cooling

Type of cooling system.

Split AC System, Evaporative Cooler, ...

wall_type

Type of walls.

Brick, Concrete - Panels, Sheet Metal, ...

roof_ceiling

Type of roof.

Built-up, Shingles, Concrete, ...

window_glass_layers

Numbers of window layers.

Single-pane, Double-pane, ...

window_glass_type

Type of window glass.

Clear, Tinted, Reflective, ...

energy_star_label

Whether or not the building has an ENERGY STAR label.

Labeled, Not Labeled, Unknown

leed_score

Type of LEED certification.

Platinum, Gold, Silver, ...

data_source

Name of the original data source.

Anonymous, Berkeley Benchmarking Ordinance, ...

 

Numerical Fields

Name

Description

Minimum

Maximum

Unit

year

Year in which the data was measured.

1990

previous year

year

electric_eui

Annual electric energy use intensity.

0

1000

kBtu/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 "Commercial" or "Residential". Can only be used with field_name = "facility_type". Specified in URL (see example below).

 

Response

Property

Type

Description

field_info

JSON object

For categorical variables: Field name, type, and list of legal values.

For numerical variables: Field name, type, minimum and maximum legal values, and unit of measure.

metadata

JSON object

General information about the request (see Metadata section above).

 

Examples

Example 1: Legal values of the climate field.

Request URL: https://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": ...}