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
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.
Download by UUID
Once you have the uuid of the component or measure that you would like to download, you can use the following resource to download it:
https://bcl.nrel.gov/api/component/download?uids=[the_uuid]
You can also download multiple components or measures at a time by listing uuids:
https://bcl.nrel.gov/api/component/download?uids=[uuid1],[uuid2],[uuid3]
Schemas
The component and measure schemas for the API version 2.0 are available below: