BCL API Documentation

The BCL API is the main mechanism for querying and downloading content.

Search Endpoint

The main syntax for querying is as follows:

https://bcl.nrel.gov/api/search/{KEYWORD}.{FORMAT}?fq={FILTER}:{FILTER_VALUE}

where:

KEYWORD—is the term to search on, such as "window" or "boiler". To do a wildcard search, use the "*" symbol.

FORMAT—is the return format wanted. XML and JSON are both supported; if no format is specified, JSON will be returned.

FILTER_NAME & FILTER_VALUE—are used to narrow down the search results. Multiple name-value pairs can be specified.

Read on for more details on filters and query parameters that can be used in search requests, or view the examples section for ready-to-use examples.

Filters

Below is a list of common filters that can be used to narrow down search results:

Filter NameDescription
bundleType of content. The possible values for this filter are: measure and component
nameName of the component or measure
display_nameDisplay Name of the component or measure
uuidUUID of the component or measure
version_idUnique Version ID of the component or measure
release_tagRelease tag version of the parent GitHub repo
repoName of the content's GitHub repo of origin
orgName of the content's GitHub organization of origin
measure_tagsClassification tag of the measure. See Measure Tags for a complete tag list and the examples below for query syntax.
component_tagsClassification tag of the component. See Component Tags for a complete list and the examples below for query syntax.
classnameOpenStudio Classname of the component or measure
manufacturerManufacturer of the item represented by the component
modelModel number of the item represented by the component
serial_noSerial number of the item represented by the component
yearYear of manufacture of the item represented by the component
urlSource URL of the item represented by the component

Attributes

Content attributes can also be used to filter search results. Attributes are stored as a name and value pair. For example:

{ "name": "Measure Type", "value": "ModelMeasure"}

To query by attribute, specify the attribute name and attribute value separately using the attr_name and attr_value syntax:

https://bcl.nrel.gov/api/search?fq=attr_name:{ATTRIBUTE NAME}&fq=attr_value:{ATTRIBUTE VALUE}

Query Parameters

In addition to filters, several query parameters are also available to narrow down the search results. These query parameters are appended to the search URL but do not need the 'fq=' syntax which indicates filters.

For example, the following URL can be used to paginate the search results to 10 per request and return page 2 of the results:

https://bcl.nrel.gov/api/search/denver.json?page=2&show_rows=10

The list of query parameters can be found in the table below.

Query Parameter NameDescription
show_rowsNumber of results to return on each page. Default is 50.
pageThe page to return. This is 0-based (the first page is page=0).
all_content_versionsBy default, the latest version of all content is returned. all_content_versions=1 can be added to the URL to return all versions.
api_versionUsed to specify the legacy API. Set api_version=2.0 to use the legacy syntax.

Geospatial Search

Geospatial searching is enabled for content with Latitude and Longitude attributes. This search currently exists for Location-Dependent Components such as Weather Files and Design Days, but is possible on any component or measure content provided that Latitude and Longitude are both provided as attributes in the component.xml or measure.xml file.

To perform a geospatial search, the special location: prefix is used in the keyword section of the search query URL. There are three syntaxes available for this query type, as described below.

TypeKeyword Syntax
Zipcodelocation:{zipcode}
Latitude and Longitudelocation:{latitude},{longitude}
City and Statelocation:{city},{state abbreviation}

The default search radius is 40km, but a custom radius can be specified in miles (mi) or kilometers (km) using the radius query parameters.

See below for geospatial search examples.

Download Endpoint

Measures and Components can be downloaded via the BCL API. Individual or multiple content can be downloaded in the same request, by specifying a single uuid or a list of uuids. For individual requests, the version of the content can be specified. You will need the uuid

The basic syntax for downloading is as follows:

https://bcl.nrel.gov/api/download/?uids={UUID}

where:

UUID—is either a single uuid or a list of uuids.

See below for downloading examples.

Taxonomy Endpoint

The taxonomy endpoint is used to programmatically return the Measure Tags or Component Tags hierarchies. This can be useful for user interface development.

The response can be returned in either XML or JSON format. To return all Measure Tags:

https://bcl.nrel.gov/api/taxonomy/measure.json

To return all Component Tags:

https://bcl.nrel.gov/api/taxonomy/component.json

Metasearch Endpoint

The metasearch endpoint can be used to retrieve the statistics of a search—such as number of results overall as well as the number of results per filter relevant to the search. This endpoint can be useful for user interface development.

Basic syntax is the same as the search endpoint; for example:

https://bcl.nrel.gov/api/metasearch/*.xml?fq=bundle:measure

This query will return the total number of results overall and the number of results per measure tag, for example.

Examples

Expand the sections below to view API usage examples.

Use the bundle filter to specify a measure or a component, and the measure_tags or component_tags to specify the category of content to retrieve:

JSON FORMAT
https://bcl.nrel.gov/api/search/*.json?fq=bundle:measure&fq=measure_tags:HVAC
https://bcl.nrel.gov/api/search/*.json?fq=bundle:component&fq=component_tags:Location-Dependent Component&fq=component_tags:Weather File
XML FORMAT
https://bcl.nrel.gov/api/search/*.xml?fq=bundle:measure&fq=measure_tags:HVAC
https://bcl.nrel.gov/api/search/*.xml?fq=bundle:component&fq=component_tags:Location-Dependent Component&fq=component_tags:Weather File

View all tags and attributes

The UUID is a universally unique content identifier. The search will only return exact UUID matches.

https://bcl.nrel.gov/api/search/?fq=uuid:FFFFFFFF-0000-FFFF-0000-FFFFFFFF1111

To view all versions of a measure or component, append the all_content_versions query parameter to the query.

https://bcl.nrel.gov/api/search/?fq=uuid:FFFFFFFF-0000-FFFF-0000-FFFFFFFF1111&all_content_versions=1

To search by the content's GitHub repo name:

https://bcl.nrel.gov/api/search/?fq=repo:bcl-test-components

To search by the content's GitHub repo name and repo organization name:

https://bcl.nrel.gov/api/search/?fq=repo:bcl-test-measures-gem&fq=org:BuildingComponentLibrary

View all repos

To search by attribute Measure Type with value ReportingMeasure:

https://bcl.nrel.gov/api/search?fq=attr_name:"Measure Type"&fq=attr_value:ReportingMeasure

View all tags and attributes

To search by Zipcode:

https://bcl.nrel.gov/api/search/location:80222

To search by City and State:

https://bcl.nrel.gov/api/search/location:denver,CO

To search by Latitude and Longitude:

https://bcl.nrel.gov/api/search/location:39.7,-104.5.json

To search by Location and Component Type, and limit the results to the first one:

https://bcl.nrel.gov/api/search/location:80222.json?fq=component_tags:"Weather File"&show_rows=1

To search by Latitude and Longitude in a custom radius of 100 miles:

https://bcl.nrel.gov/api/search/location:39.7,-104.5.json?radius=100mi

To search by Latitude and Longitude in a custom radius of 50 kilometers:

https://bcl.nrel.gov/api/search/location:39.7,-104.5.json?radius=50km

Download the latest version of a single measure or component:

https://bcl.nrel.gov/api/download/?uids=FFFFFFFF-0000-FFFF-0000-FFFFFFFF1111

Download multiple measures or components (measures and components can be downloaded at the same time):

https://bcl.nrel.gov/api/download/?uids=FFFFFFFF-0000-FFFF-0000-FFFFFFFF1111,FFFFFFFF-0000-FFFF-0000-FFFFFFFFFFFF

Download a specific version of a measure or component:

https://bcl.nrel.gov/api/download/?uids=FFFFFFFF-0000-FFFF-0000-FFFFFFFF1111&release_tag=v0.1