The energy label API
The energy label API lets you create energy labels for products sold in Great Britain.
You can use the API to create energy labels in your own applications from your product data. You can create any of the types of label that are available on this service, as well as efficiency class arrow images for websites and other distance selling.
The energy label API is free to use and you don't need to register, but you can sign up to receive email updates.
Endpoints
Use the 'Endpoints' section of the menu on the left at the top of this page to see what endpoints are available and how to use them.
The endpoints are also listed in the energy label API OpenAPI 3 document.
Rate limits
Requests to the energy label API are rate limited to 10 requests every 30 seconds per IP address.
Each response will include an X-Rate-Limit-Remaining header which will tell you how many more requests you can make within that 30 seconds timeframe.
You should store the labels you generate in your application, rather than making repeated requests for the same product's label. This will help you avoid being rate limited.
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 30 seconds.
The response will include an X-Rate-Limit-Retry-After-Seconds header which will tell you how many seconds you have left until you can make another successful request.
Testing
The energy label API doesn't require authentication and doesn't store the labels you create, so there is no sandbox environment for testing. You can use the live API URL for development, testing and production.
You can import the energy label API OpenAPI 3 document into API testing tools like Postman to test all of our API endpoints.
Request validation
These endpoints return data in PDF format for energy labels, PNG or JPEG for arrow images and JSON for errors.
You can import the energy label API OpenAPI 3 document into API testing tools like Postman to test all of our API endpoints.
The values you send will be validated. If there are any validation errors, the response body will be a JSON object
containing a validationErrors array. For example:
{
"timestamp": "2022-02-18T15:28:11.877Z",
"status": 400,
"error": "Bad request",
"message": "There were validation errors",
"validationErrors": [
{
"propertyName": "modelName",
"errorMessage": "Enter a supplier model identification code"
},
{
"propertyName": "supplierName",
"errorMessage": "Enter a supplier name or trade mark"
}
],
"path": "/api/v1/path/to/endpoint"
}
Versioning
The current version of the energy label API is v1.1.
We'll only change the major 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
- removing endpoints
We will not change the major version number of the API for changes that:
- add new endpoints
- fix bugs, unless the fix could break existing applications
If you sign up to receive emails from us we'll email you to let you know when we make changes to the API or release a new version. We'll also add a notice to this page.
After we've released a new major version of the API, the previous major version will keep working for at least 6 months. This will give you time to update your application to use the new major version. When we announce a new major version, we'll tell you when the old major version will stop working.
When we release a new major version of the API, all of our endpoint paths will change to include the new major version number. You'll need to update the endpoint URLs your application uses to access the API. You'll need to test that your application still works with the new major version. You should read the release notes for the current major version to see what's changed and update your application if necessary.
Cross-origin requests
Cross-origin requests are not supported by the API, so you can't make API requests directly from client side JavaScript code in a web browser.
If you want to integrate the API with a web application, please route requests through a back-end service.
Availability
We aim to make the energy label API available 24 hours a day, 7 days a week. However, availability of the API is not guaranteed and there may be unexpected downtime or performance degradation at any time. Your application should be resilient to the energy label 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
You should store the labels you generate in your application, rather than making repeated requests for the same product's label. This will limit the impact of any downtime on your application.
If you sign up to receive emails from us we'll email you before any planned downtime, or to update you on any unplanned downtime.
Support
If you've found a bug or you have issues accessing the energy label API, suggestions for new features or any other feedback, please contact efficientproducts@beis.gov.uk
Email updates
You can sign up to receive email updates about the energy label API. We'll notify you about any downtime and let you know when we make important changes.
You don't have to sign up for email updates to use the API, but we encourage you to sign up if you're using the API in production. If you don't, you may not find out about downtime or changes that affect your application.
Version history and release notes
v1.1
In addition to PDF, energy labels can now be generated in PNG and JPEG formats.
v1
This is the first version of the energy label API.