Developer Resources

The Building Component Library is accessible pragmatically through a RESTful API. The API allows users to query the library.

API Access

In order to gain access to the API, log in to the site and include the session ID returned with the response in any future requests.

The default API when no version is specified is version 1.1. To use the new API, append each query with api_version=2.0. The previous API (version 1.1) supported API keys. If you already have an apikey, you can still use it by appending the key to any API query with oauth_consumer_key=[KEY], replacing [KEY] with the one obtained.

The URL to query the Library for components is:

http://bcl.nrel.gov/api/search/[keyword].[format]?[params]

where [keyword] is the search term, and can be left blank. [format] is the return format, which can be xml, json, or yaml, and will default to xml if left blank. [params] are the query and filter parameters to apply to the search, and are described in more detail below.

API v1.1

The table below describes available query parameters.

Parameter Usage Description
show_rows show_rows=[integer] The maximum number of records the service will return. The default is 10 records.
page page=[integer] If a query has more than 10 results, the page parameter can be used to paginate through the results. Page numbering starts at 0.
filters List which filters to use and the respected values
type:[nrel_component] Filters results by Node Type
sm_component_type:[string] Filters results by Component Type
is_component_fidelity_level:[1-5] Filters results by Fidelity Level
tid:[integer] Filters results by Taxonomy ID (like Component Type filtering)
ss_component_manufacturer:[string] Filters results by Manufacturer
ss_component_model:[string] Filters results by Model
ss_component_author:[string] Filters results by Author
api_version api_version=[string] Specifies the API version to use. The latest version is 2.0 and contains format changes. The previous version is 1.1 and is still supported.

The API also accepts other component attributes as filters.

An example search query is listed below. This query returns the components matching the keyword "Denver" that are of component type "Weather File". 2 results are returned per request and the first page of results is requested. The response is formatted in xml:

http://bcl.nrel.gov/api/search/denver.xml?filters=type:nrel_component%20sm_component_type:"Weather File"&show_rows=2&page=0

API v2.0

A few example queries as well as syntax used by the API v2.0 are shown below.

Search by UUID

https://bcl.nrel.gov/api/search/?fq[]=ss_uuid:[UUID]&api_version=2.0

Search by File Type

There is no filter for file type, but if the file extension can be specified in the part of the search:

https://bcl.nrel.gov/api/search/[file extension]?&api_version=2.0

Search by Attribute Presence

Wildcard searches can be performed to include all possible values of an attribute, and ensure that the content returned contains the specified attribute. For example, to search for all components that have the "TPE UUID" attribute:

https://bcl.nrel.gov/api/search/?fq[]=bundle:nrel_component&fq[]=sm_a_TPE_uuid:[*%20TO%20*]&api_version=2.0

The following table lists several useful attributes available for querying the BCL.

Parameter Type Usage Description
show_rows Query Param show_rows=[integer] The maximum number of records the service will return. The default is 10 records.
page Query Param page=[integer] If a query has more than 10 results, the page parameter can be used to paginate through the results. Page numbering starts at 0.
api_version Query Param api_version=[string] Specifies the API version to use, and is required by API v2.0
UUID Filter Param fq[]=ss_uuid:[uuid] Filter by UUID. Should return a maximum of 1 record
bundle Filter Param fq[]=bundle:[content type] Filter by content type. Options are nrel_component or nrel_measure.
Component Type Filter Param fq[]=sm_vid_Component_Tags:[component type] Filter by Component Type
Measure Type Filter Param fq[]=sm_vid_Measure_Tags:[measure type] Filter by Measure Type
Component Type ID Filter Param fq[]=im_field_component_tags:[tid] Filter by TaxonomyID of the component type
OpenStudio Type Filter Param fq[]=sm_OpenStudio_Type:[openstudio type] Filter by OpenStudio type

Query parameters, such as api_version, page, and show_rows are appended to the URL, use a equal sign ("=") between parameter name and value, and are separated by an ampersand ("&"). For example:

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

Filter parameters are appended to the URL by using the "fq[]=" syntax. They use a color (":") between parameter name and value, and are separated by an ampersand ("&"). Use one "fq[]" per filter parameter. For example:

 https://bcl.nrel.gov/api/search/?fq[]=bundle:nrel_component&fq[]=sm_vid_Component_Tags:Window&api_version=2.0

A full list of attributes supported by the BCL is also available. If you would like to upload content with attributes not listed here, please contact us.

Schemas

The component and measure schemas for the API version 2.0 are available below:

Component 3.0 Schema

Measure 3.0 Schema