BCL API Documentation

Some OpenStudio apps—such as the OpenStudio Application and the SketchUp Plug-in—may prompt you to enter a BCL Auth Key. This key is no longer needed to search for content on the BCL. If you encounter a dialog box prompting you to enter your BCL Auth key, simply enter the following placeholder key or any 32 characters.

BCL auth key:

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

The main syntax for querying is as follows:

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

where:

Search results schemas for measures and components are available.

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.

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

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}

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.

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.

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.

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:

See below for downloading examples.

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

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.