Using the ETL API
The ETL API lets you add the ability to find energy efficient, ETL-listed products to your own websites and applications. All of the data available on the ETL product search service is available via the ETL API, including product features and images and the ability to search and filter products.
The ETL API is a REST API which returns data in JSON format. It’s free to use.
Register to use the ETL API
You must register for a free API key to use the ETL API. After you've registered we'll send your API key to you by email immediately.
If you lose your ETL API key, you can fill in the form again and we’ll re-send you the same API key.
All requests to the ETL API must be authenticated. To authenticate your request, include your API key
If you do not include the
X-API-Key header, or if the API key isn’t valid, your request will receive a
response with the
401 Unauthorized HTTP status code.
Endpoints and models
The API reference documentation lists all of the ETL endpoints, along with their parameters and response formats.
Keeping your API key secure
Your API key is private. You must make sure that it’s not made public, for example:
- in source code shared on GitHub or other code-sharing sites
- in unsecured HTTP requests (the ETL API only works over HTTPS)
implement a proxy in your server-side code which takes requests from your client-side code, passes them
on to the ETL API with the
X-API-Key header added, then returns the result
from the ETL API back to the client.
If you think your API key has been made public, please contact us.
Requests to the ETL API are rate limited 5 requests per second per API key. If we change the limit in the future, we’ll let you know by email.
If you exceed the rate limit, you’ll receive a response with the
429 Too Many Requests HTTP status code.
You can retry your request in 1 second.
ETL API responses include a
Cache-Control: max-age=<seconds> header. If
possible, you should cache the API response for the number of seconds specified. Data returned by the ETL API
is updated once a day at most, so caching responses will help your application to run faster without risking
showing users out-of-date data.
The ETL API is read-only, so there is no sandbox environment for testing. You can use the live API URL for testing.
You can download the ETL API OpenAPI 3 document. You can import this document into API testing tools like Postman to generate request templates for all of our API endpoints.
The current version of the ETL API is v1. The current API URL is
We’ll only change the version number of the API if we make changes that might break applications using the API. These changes include:
- changing the intended behaviour of any existing endpoints (other than adding new properties to responses)
- removing properties from endpoints
- removing endpoints
We will not change the version number of the API for changes that:
- add new endpoints
- add new properties to existing endpoints
- fix bugs, unless the fix could break existing applications
You should make sure that your application doesn’t break if we add new properties to existing endpoints. For example, you should not rely on the properties in a response being in a particular position or order, because we might add new properties that change the position of other properties.
We’ll email you to let you know when we make changes to the API or release a new version. After we’ve released a new version of the API, the previous version will keep working for at least 6 months. This will give you time to update your application to use the new version. When we announce a new version, we’ll tell you when the old version will stop working.
When we release a new version of the API you’ll need to update the URL your application uses to access the
API. The current API URL is
https://api.etl.energysecurity.gov.uk. You’ll need to test that your application still works
with the new version. You should read the
release notes for the current version to see what’s
changed and update your application if necessary.
We aim to make the ETL API available 24 hours a day, 7 days a week. However, availability of the API is not guaranteed and unexpected downtime or performance degradation may occur at any time. Your application should be resilient to the ETL API not being available, for example:
- taking a long time to send a response
- timing out before sending a response
- returning responses with HTTP status codes other than
200 OK, including
5xxserver error status codes
If you’ve found a bug or you have issues accessing the ETL API, suggestions for new features or any other feedback, please contact firstname.lastname@example.org
Version history and release notes
This is the first version of the ETL API.