Using this API

You require a registered account to use this API, and all requests to this API must be authenticated to your account using HTTP Basic Auth. To do this we use a Base64-encoded account identifier composed of your email address and api-key.

This token must then be included in the HTTP Authorization header on every API request with the Basic authentication scheme, for example:

Both of these tokens are used to authenticate you, so you should take measures to ensure you do not share them publicly, e.g by avoiding commiting them into public source code repositories, or storing them in the source of a publicly accessible website.

Authorization: Basic <encoded-api-key>

Assuming you have already registered, you should have received an email containing your API key.

This token is generated by Base64-encoding the string : which is the concatenation of your email address with the separator : and your api-key .

You may confirm that this works using a simple cURL request asking for all results as CSV.

$ curl -v -X GET  -H "Accept: text/csv" -H "Authorization: Basic <encoded-api-key>" "https://epc.opendatacommunities.org/api/v1/non-domestic/search"

Unless otherwise stated each of our API's support the following Accept headers:

Non-domestic Search API

This API can be called by making an authenticated HTTP GET request with an appropriate Accept header to the API endpoint:

https://epc.opendatacommunities.org/api/v1/non-domestic/search

Descriptions of all the columns and fields found in the returned data can be found in the glossary.

This search API follows a subtractive search model, where without any additional filter parameters it will return a paginated result set containing all non-domestic certificates.

Pagination

Without any additional query parameters the API will return the first page of of all the non-domestic certificates, with a default page size of 25 results. Additional pages can be requested by changing the pagination offset with the from and sizequery string parameters.

For example we can change the page-size to 1000 and request the second page of results by setting our from parameter to 1000 also:

$ curl -v -H "Accept: text/csv" -H "Authorization: Basic <encoded-api-key>" "https://epc.opendatacommunities.org/api/v1/non-domestic/search?size=1000&from=1000"

Note: The API is only designed to support result sets of up to 10,000 records at a time, with a maximum page size of 5,000. This means you cannot paginate over more than 10,000 results for a single search. If you require more than 10,000 records, make multiple requests and vary your search filters. For example, when searching within a large Local Authority, you might include date ranges, or floor area filters. Alternatively, download the full zip and work offline.

Filtering by address

You can filter certificates by address by appending the address HTTP query-string parameter to the URL string.

For example we can filter for certificates that have the address liverpool:

$ curl -v -H "Accept: text/csv" -H "Authorization: Basic <encoded-api-key>" "https://epc.opendatacommunities.org/api/v1/non-domestic/search?address=liverpool"

The parameter codes supported for this search filter and their meanings are described in the table below:

Filtering by postcode

You can filter certificates by postcode by appending the postcode HTTP query-string parameter to the URL string.

For example we can filter for certificates that have the postcode M1:

$ curl -v -H "Accept: text/csv" -H "Authorization: Basic <encoded-api-key>" "https://epc.opendatacommunities.org/api/v1/non-domestic/search?postcode=M1"

The parameter codes supported for this search filter and their meanings are described in the table below:

Filtering by local authority

You can filter certificates by local authority by appending the local-authority HTTP query-string parameter to the URL string.

For example we can filter for certificates that have the local authority E07000044:

$ curl -v -H "Accept: text/csv" -H "Authorization: Basic <encoded-api-key>" "https://epc.opendatacommunities.org/api/v1/non-domestic/search?local-authority=E07000044"

The parameter codes supported for this search filter and their meanings are described in the table below:

Filtering by constituency

You can filter certificates by constituency by appending the constituency HTTP query-string parameter to the URL string.

For example we can filter for certificates that have the constituency E14000645:

$ curl -v -H "Accept: text/csv" -H "Authorization: Basic <encoded-api-key>" "https://epc.opendatacommunities.org/api/v1/non-domestic/search?constituency=E14000645"

The parameter codes supported for this search filter and their meanings are described in the table below:

Filtering by property type

You can filter certificates by property type by appending the property-type HTTP query-string parameter to the URL string.

You can supply multiple property-typeparameters if you wish to perform a union search, for example we can filter for certificates that have the values a1-a2 or a3-a4-a5:

$ curl -v -H "Accept: text/csv" -H "Authorization: Basic <encoded-api-key>" "https://epc.opendatacommunities.org/api/v1/non-domestic/search?property-type=a1-a2&property-type=a3-a4-a5"

The parameter codes supported for this search filter and their meanings are described in the table below:

Filtering by floor area

You can filter certificates by floor area by appending the floor-area HTTP query-string parameter to the URL string.

You can supply multiple floor-areaparameters if you wish to perform a union search, for example we can filter for certificates that have the values l or m:

$ curl -v -H "Accept: text/csv" -H "Authorization: Basic <encoded-api-key>" "https://epc.opendatacommunities.org/api/v1/non-domestic/search?floor-area=l&floor-area=m"

The parameter codes supported for this search filter and their meanings are described in the table below:

Filtering by energy band

You can filter certificates by energy band by appending the energy-band HTTP query-string parameter to the URL string.

You can supply multiple energy-bandparameters if you wish to perform a union search, for example we can filter for certificates that have the values a+ or a:

$ curl -v -H "Accept: text/csv" -H "Authorization: Basic <encoded-api-key>" "https://epc.opendatacommunities.org/api/v1/non-domestic/search?energy-band=a+&energy-band=a"

The parameter codes supported for this search filter and their meanings are described in the table below:

Filtering by lodgement date

You can filter certificates by lodgement date by appending the appropriate date parameter to the HTTP query-string:

For example we can filter for certificates that were lodged between May 2015 and October 2016 by setting from-month to 5, from-year to 2015 and to-month and to-year to 10 and 2016 respectively.

$ curl -v -H "Accept: text/csv" -H "Authorization: Basic <encoded-api-key>" "https://epc.opendatacommunities.org/api/v1/non-domestic/certificate/89931970062019053113040836250130?from-year=2015&from-month=5&to-year=2016&to-month=10"

Combining Filters

To constrain results any of the above filters can be arbitrarily combined by appending them as HTTP query string parameters. The various filters supported correspond to the faceted search fields on the user interface. Filters are combined as a boolean AND operation. Additionally some filters support multiple values which corresponds to a boolean OR operation.

For example we can search on both address and energy-band by including both filters on the query string:

$ curl -v -H "Accept: text/csv" -H "Authorization: Basic <encoded-api-key>" "https://epc.opendatacommunities.org/api/v1/non-domestic/search?address=liverpool&energy-band=c"

Non-domestic Certificate API

This API can be called by making an authenticated HTTP GET request with an appropriate Accept header to the API endpoint:

https://epc.opendatacommunities.org/api/v1/non-domestic/certificate/:lmk-key

Where :lmk-key is the LMK key of a certificate from a search result or download. For example we can request the certificate with LMK key of 89931970062019053113040836250130 by making a request to the API at the URL:

https://epc.opendatacommunities.org/api/v1/non-domestic/certificate/89931970062019053113040836250130

Note: This API recently changed, to expect an LMK key as the identifier instead of a certificate hash. Read more.

When a supported Accept header is set on the request it will return the specified certificate in the requested format. An example of how to request this certificate in CSV format using cURL is shown below:

$ curl -v -H "Accept: text/csv" -H "Authorization: Basic <encoded-api-key>" "https://epc.opendatacommunities.org/api/v1/non-domestic/certificate/89931970062019053113040836250130"

Descriptions of all the columns and fields found in the returned data can be found in the glossary.

Non-domestic Recommendations API

Not all certificates contain recommendations for the property, but where they do they are available via this API route:

https://epc.opendatacommunities.org/api/v1/non-domestic/recommendations/:lmk-key

If the property has no recommendations a HTTP 404 not found status code will be returned. Note that this api route does not recognise the application/zip mime type.

Recommendations are keyed on the certificates lmk-key, which can be obtained from the certificate's lmk-key field.

$ curl -v -H "Accept: text/csv" -H "Authorization: Basic <encoded-api-key>" "https://epc.opendatacommunities.org/api/v1/non-domestic/recommendations/89931970062019053113040836250130"