Skip to main content

We use cookies to collect information about how you use the ETL website. We use this information to make the website work as well as possible and improve our services. Find out more about how we use cookies.

Energy Technology List home
Department for Business, Energy and Industrial Strategy
  1. Home
  2. Products
  3. API

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.

Authentication

All requests to the ETL API must be authenticated. To authenticate your request, include your API key in the X-API-Key header.

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)
  • in source code that’s visible to users, for example in HTML or JavaScript code

To help prevent your API key from being exposed in your client-side JavaScript code, the ETL API does not allow cross-origin resource sharing (CORS). To use the ETL API in client-side JavaScript code, you can 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.

Rate limits

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.

Caching

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.

Testing

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.

Versioning

The current version of the ETL API is v1. The current API URL is https://api.etl.energysecurity.gov.uk

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.

Availability

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 5xx server error status codes

Support

If you’ve found a bug or you have issues accessing the ETL API, suggestions for new features or any other feedback, please contact info@etl.energysecurity.gov.uk

Version history and release notes

v1

This is the first version of the ETL API.