Developers

The Technology Performance Exchange API provides programmatic access to product and performance data.

Data Access

Registered users of the site can query the site via the search resource and download a product and its corresponding performance data with the download resource.

The API is only available to authenticated users. If querying the API in a web browser, for example, you must first login to the site.

Search Resource

The search resource retrieves products from the site across all technology categories. The parameter specifies the keyword to search on. Each result will contain product information as well as an asssociated URI which can then be used to download a product and its data.

Request URL

GET https://<baseurl>/api/search/

Parameters

The following parameter(s) must be passed in the request to specify the output of the query:

Parameter	Required?	Value	Description
keyword	Yes	Type:string	The keyword to search on

Examples

GET https://performance.nrel.gov/api/search/lamp

Download Resource

The download resource allows you to download a product and all of its related performance data in csv format. A product's URI, returned by the search resource, is used to download the data. The Request URL can also be built from the product's unique identifier (UUID)

Request URL

GET https://<baseurl>/api/download/

Parameters

The following parameter(s) must be passed in the request to specify the output of the query:

Parameter	Required?	Value	Description
UUID	Yes	Type:string	The product's unique TPEx identifier

Examples

GET https://performance.nrel.gov/api/download/23b36a82-f78d-4369-8440-4f-52893948f

Fields Resource

The fields resource allows you to retrieve a list of all performance fields associated with a technology category as well as related meta data such as display name and technical description. This can be used to better understand the information returned by the search resource.

Request URL

GET https://<baseurl>/api/fields/<technologyID>

Parameters

The following parameter(s) must be passed in the request to specify the output of the query:

Parameter	Required?	Value	Description
technologyID	Yes	Type:string	The technology category's unique identifier

The following table lists each technology category and its respective identifier:

Technology Category	technologyID
Lamp Ballasts	lmpbls
Non-SSL Lamps	nnslmp
Non-SSL Luminaires	nnslmn
SSL Replacement Lamps	slrplc
SSL Luminaires	slmnrs
Heat Pump Water Heaters	htpmpw
Hot-Water Boilers	htwtrb
Steam Boilers	stmblr
Positive Displacement Refrigeration Compressors	pstvds
Rooftop Units	rftpnt
Rotodynamic Pumps	rtdynm
Indoor Units	ndrnt
Outdoor Units	tdrnt
Mini-Split Systems	mnsplt
Low-Voltage, Dry Type Distribution Transformers	lwvltg
Photovoltaic Modules	phtvlt
Inverters	nvrtr
Gas-Fired Unit Heaters	gsfrdn
Refrigerated Cases	rfrgrt

Examples

GET https://performance.nrel.gov/api/fields/nnslmp

Data Upload

Manufacturer and Brand Owner users can upload product information and associated performance data programmatically via the API. Third-Party Test Laboratory and Contributing Evaluator users can upload performance data associated with an existing product programmatically. A Ruby gem is available to facilitate these tasks. Download the TPEx gem.

Using the TPEx Gem

Installation

You will need Ruby version 1.9.3 installed on your computer as well as the RubyGems package.

Download the TPEx gem. From the command line, navigate to the directory where you downloaded the gem and run the following commands:

gem install tpex
gem install colored
gem install hashie

Using the Gem

The general workflow for uploading data to the TPEx via the API is shown below.

Login to the TPEx site
Set the security token
Post the product (manufacturers only)
Post file (optional)
Post performance data for the product

You can then write a simple Ruby script that uses the gem, as outlined in the following steps:

Initialization

Make sure to include the gem:

require 'tpex'

Initialize the client:

client = TPEX.client(username:"<TPEX_USERNAME>", password:"<TPEX_PASSWORD>", logging:nil, endpoint:'http://performance.nrel.gov/api')

client.login()

Get a token and assign it:

token = client.get_access_token()
client.access_token = token

Posting a Product

The steps to post a new product are as follows.

Assemble a hash of your product data:

product_fields = {
  manufacturer: ,
  certified: ,
  tags: ,
  model_no: data,
  brand: ,
  product_line: ,
  femp: ,
  upc: ,
  energy_star_no:
}

Build a product object out of the hash:

product = client.build_product(product_fields)

Post the product, and wrap it in a rescue statement for helpful feedback. If an error occurs in the process, the product_response variable will have the details of the error.

begin
  product_response = client.post_product(product)
rescue StandardError => e
  print “failure”
else
  print “success”
end

Posting a File

Follow these instructions if you have a file to attach, such as a spec sheet.

The file must fisrt be base64 encoded:

filedata = Base64.strict_encode64(file.read)

Build the file into an object the client understands:

specification_sheet = client.build_file(:file => filedata, :filename => filename, :filesize => filedata.length)

Post the file object and save the response:

specification_sheet_response = client.post_file(specification_sheet)

Save the fid for use when posting the performance node later:

fid = specification_sheet_response.fid

Posting performance data

Posting performance data follows a very similar format to product data.

Prepare a hash of all your performance fields. Each technology category has its own set of field mappings. The following templates have the mappings for the technology categories that can currently be uploaded to the TPEx via the API:

Template file fields ending in "_src" are used to indicate the origin of the associated field's data. The following table contains the list of valid options for the "_src" fields. Please use the "machine name" in the templates.

Machine Name	Description
nonmeasppdc	Non-Measurable Physical Property/Design Criteria
selfmsrfld	Self-Measured, Field
selfmsrlab	Self-Measured, Laboratory
msrotrfld	Measured By Others, Field
msrotrlab	Measured By Others, Laboratory
calcselfmsrfld	Calculated Using Self-Measured Field Data
calcselfmsrlab	Calculated Using Self-Measured Laboratory Data
calcotrmsrfld	Calculated Using Others' Measured Field Data
calcotrmsrlab	Calculated Using Others' Measured Laboratory Data
rptextunk	Reported by External Source, Derivation Unknown
calcextunk	Calculated Using External Data, Derivation Unknown

Template files also contain fields for you to list performance map filenames, where appropriate. Performance map templates, listed below, can be filled out and placed in a directory named "files" in the same directory as your API template file. They will be uploaded when the template file is processed.

Technology Category	Performance Map Templates
Compressors	Compressor Performance Map Rating Coefficient Map
DHP Indoor Units	Indoor Unit Cooling Performance Map Indoor Unit Heating Performance Map
DHP Outdoor Units	Outdoor Unit Cooling Performance Map Outdoor Unit Heating Performance Map Outdoor Unit Defrost Performance Map
Heat Pump Water Heaters	HPWH Performance Map
Hot-Water Boilers	Hot-Water Boiler Performance Map
Steam Boilers	Steam Boiler Performance Map
Inverters	Inverter Performance Map
Pumps	Pump Performance Map
PV Modules	PV Module Performance Map
Rooftop Units	Rooftop Unit Cooling Performance Map.xlsx Rooftop Unit Heat Pump Performance Map.xlsx Rooftop Unit Gas or Electric Heating Performance Map.xlsx
Mini-Split Systems	Mini-Split System Cooling Performance Map Mini-Split System Heating Performance Map

Build a performance node object out of your hash:

perf = client.build_performance_node(performance_fields)

Post the performance node. The perf_response variable will hold all the return values from the call.

begin
  perf_response = client.post_performance_node(perf)
rescue StandardError => e
  print “failure”
else
  print “success”
end

Cleaning up

At the end of your script, logout:

client.logout()

Example Script

The following parser script is an example script that uses the TPEx gem. It can be used as a starting point for using the gem and customized to fit your needs. Download the parser script.

To run the script, pass the content type and template file name as arguments. For example:

ruby parser.rb 'Non-SSL Lamps' 'non_ssl_lamps.csv'