Legacy BCL API
The new implementation of the BCL maintains support for the legacy BCL API v2.0, identified by appending &api_version=2.0 to the URL query.
Search Endpoint
The main syntax for querying is as follows:
https://bcl.nrel.gov/api/search/{KEYWORD}.{FORMAT}?fq[]={FILTER}:{FILTER_VALUE}&api_version=2.0where:
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.
api_version=2.0— is appended to the end of the URL request to ensure backward compatibility. The legacy syntax will not work without specifying this api_version.
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 Name | Description |
|---|---|
| bundle | Type of content. The possible values for this filter are: nrel_measure and nrel_component |
| name or label | Name of the component or measure |
| ss_field_display_name | Display Name of the component or measure |
| ss_uuid | UUID of the component or measure |
| ss_vuuid | Unique Version ID of the component or measure |
| ss_description | Content Description |
| ss_modeler_description | Modeler Description for the component or measure |
| ss_field_version_modified | Version Modified date value from the component or measure's XML file |
| sm_vid_measure_tags | Classification tag of the measure. See Measure Tags for a complete tag list and the examples below for query syntax. |
| sm_vid_component_tags | Classification tag of the component. See the Component Tags page for a complete list and the examples below for query syntax. |
| tid | Taxonomy ID of the measure tag or component tag. See Component Tags for a complete list of tags and their respective taxonomy ID and the examples below for query syntax. |
| ss_field_class_name | OpenStudio Classname of the component or measure |
| ss_source_manufacturer | Manufacturer of the item represented by the component |
| ss_source_model | Model number of the item represented by the component |
| ss_source_serial_number | Serial number of the item represented by the component |
| ss_source_year | Year of manufacture of the item represented by the component |
| ss_source_url | Source 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 legacy attribute name and its desired value. The list of legacy attribute names can be found on the Attributes page.
https://bcl.nrel.gov/api/search?fq[]=sm_a_measuretype:ModelMeasure&api_version=2.0Query 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&api_version=2.0The list of query parameters can be found in the table below.
| Query Parameter Name | Description |
|---|---|
| show_rows | Number of results to return on each page. Default is 50. |
| page | The page to return. This is 0-based (the first page is page=0). |
| api_version | Used 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.
| Type | Keyword Syntax |
|---|---|
| Zipcode | location:{zipcode} |
| Latitude and Longitude | location:{latitude},{longitude} |
| City and State | location:{city},{state abbreviation} |
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/component/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.jsonTo return all Component Tags:
https://bcl.nrel.gov/api/taxonomy/component.jsonMetasearch 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&api_version=2.0This query will return the total number of results overall and the number of results per measure tag or taxonomy ID (tid), 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 FORMAThttps://bcl.nrel.gov/api/search/*.json?fq[]=bundle:nrel_measure&fq[]=sm_vid_measure_tags:HVAC&api_version=2.0https://bcl.nrel.gov/api/search/*.json?fq[]=bundle:nrel_component&fq[]=sm_vid_component_tags:Location-Dependent Component.Weather File&api_version=2.0https://bcl.nrel.gov/api/search/*.xml?fq[]=bundle:nrel_measure&fq[]=sm_vid_measure_tags:HVAC&api_version=2.0https://bcl.nrel.gov/api/search/*.xml?fq[]=bundle:nrel_component&fq[]=sm_vid_component_tags:Location-Dependent Component.Weather File&api_version=2.0The UUID is a universally unique content identifier. The search will only return exact UUID matches.
https://bcl.nrel.gov/api/search/?fq[]=uuid:339a2e3a-273c-4494-bb50-bfe586a0647c&api_version=2.0To search by attribute Measure Type with value ReportingMeasure:
https://bcl.nrel.gov/api/search?fq[]sm_a_measuretype:ReportingMeasure&api_version=2.0To search by Zipcode:
https://bcl.nrel.gov/api/search/location:80222.xml?api_version=2.0To search by City and State:
https://bcl.nrel.gov/api/search/location:denver,CO.xml?api_version=2.0To search by Latitude and Longitude:
https://bcl.nrel.gov/api/search/location:39.7,-104.5.json?api_version=2.0To search by Location and Component Type, and limit the results to the first one:
https://bcl.nrel.gov/api/search/location:80222.json?fq[]=sm_vid_component_tags:"Weather File"&show_rows=1&api_version=2.0Download the latest version of a single measure or component:
https://bcl.nrel.gov/api/component/download/?uids=339a2e3a-273c-4494-bb50-bfe586a0647cDownload multiple measures or components (measures and components can be downloaded at the same time):
https://bcl.nrel.gov/api/component/download/?uids=339a2e3a-273c-4494-bb50-bfe586a0647c,03b18912-0ceb-47e9-8f8b-417a3008e189