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
Request URL
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
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
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
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
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 |
Hybrid Unitary HVAC | hybrdn |
Refrigerated Cases | rfrgrt |
Examples
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:
Initialize the client:
Login:
Get a token and assign it:
client.access_token = token
Posting a Product
The steps to post a new product are as follows.
Assemble a hash of your product data:
manufacturer: ,
certified: ,
tags: ,
model_no: data,
brand: ,
product_line: ,
femp: ,
upc: ,
energy_star_no:
}
Build a product object out of the hash:
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.
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:
Build the file into an object the client understands:
Post the file object and save the response:
Save the fid for use when posting the performance node later:
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:
- DHP Indoor Units
- DHP Outdoor Units
- Gas-Fired Unit Heaters
- Hot-Water Boilers
- Heat Pump Water Heaters
- Hybrid Unitary HVAC
- Inverters
- Lamp Ballasts
- Low-Voltage Dry Type Distribution Transformers
- Mini-Split Systems
- Non-SSL Lamps
- Non-SSL Luminaires
- Positive Displacement Refrigeration Compressors
- PV Modules
- Refrigerated Cases
- Rooftop Units
- Rotodynamic Pumps
- SSL Luminaires
- SSL Replacement Lamps
- Steam Boilers
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 Rooftop Unit Heat Pump Performance Map Rooftop Unit Gas or Electric Heating Performance Map |
Mini-Split Systems |
Mini-Split System Cooling Performance Map Mini-Split System Heating Performance Map |
Hybrid Unitary HVAC |
Hybrid Unitary Performance Map Hybrid Unitary Nominal Performance Information |
Build a performance node object out of your hash:
Post the performance node. The perf_response variable will hold all the return values from the call.
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:
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: