Using Swagger & OpenAPI

As of December 2023, we started providing OpenAPI v3 schemas for all our APIs. These schemas document all our published API routes and describe the format of the HTTP request parameters we support for querying our API.

In addition to publishing the OpenAPI v3 schemas, we also now provide a Swagger User Interface which can be used to interactively support developers in making requests against the API.

To use this interface to help build and test API requests you will need to first authorise, by clicking the Authorize button in the user interface and providing your Username (your email, printed in the footer when logged in) and Password (your API key: also printed in the footer when logged in).

Note: These OpenAPI schemas do not describe a new API; they simply describe our existing API following the OpenAPI standards. This provides developers with extra tooling support such as our Swagger interface.

If you have any comments on or feedback regarding these additions, please contact us.

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/display/search"

Alternatively, you may want to create a Python script to initiate the request.

import urllib.request
from urllib.parse import urlencode


token = "<encoded-api-key>"

headers = {
    'Accept': 'text/csv',
    'Authorization': f'Basic {token}'
}

with urllib.request.urlopen(urllib.request.Request(
    'https://epc.opendatacommunities.org/api/v1/display/search', headers=headers)) as response:
    response_body = response.read()
    print(response_body.decode())
    

NOTE: You should take care to move the secret/api-key outside of this script and ensure it is securely stored and injected into the script from elsewhere. Safe credential management is your responsibility, the scripts provided here are only intended as an easy starting point.

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

Display 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/display/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 display certificates.

Pagination using search-after (new)

This method of pagination should be preferred over the from pagination method as the total number of records that can be retrieved is not limited to 10,000.

Without any additional query parameters the API will return the first page of of all the display certificates, with a default page size of 25 results. This can be changed by specifying the size query parameter up to a maximum of 5,000.

The search-after query parameter is used to request further pages of results. The search-after value for the next page of results is given in the X-Next-Search-After response header, allowing the full set of results to be enumerated. The full request path for the next page is also given in a Link response header. Note that the next search-after value is not given when there are no results found.

For example, retrieving the first 2,000 results using a size of 1,000 using two requests, where the second request uses the search-after value from the response headers of the first request:

$ curl -v -H "Accept: text/csv" -H "Authorization: Basic <encoded-api-key>" "https://epc.opendatacommunities.org/api/v1/display/search?size=1000"
...
< Link: /api/v1/display/search?size=1000&search-after=0123456789abcdef; rel="next"
< X-Next-Search-After: 0123456789abcdef
...
$ curl -v -H "Accept: text/csv" -H "Authorization: Basic <encoded-api-key>" "https://epc.opendatacommunities.org/api/v1/display/search?size=1000&search-after=0123456789abcdef"

Full search-after example script

Below is a Python script to collect all search results for an example query with more than 5,000 results.

import urllib.request
from urllib.parse import urlencode

# Page size (max 5000)
query_size = 5000
# Output file name
output_file = 'output.csv'

# Base url and example query parameters
base_url = 'https://epc.opendatacommunities.org/api/v1/display/search'
query_params = {'size': query_size}

# Set up authentication
headers = {
	'Accept': 'text/csv',
	'Authorization': 'Basic <encoded-api-key>'
}

# Keep track of whether we have made at least one request for CSV headers and search-after
first_request = True
# Keep track of search-after from previous request
search_after = None

# Loop over entries in query blocks of up to 5000 to write all the data into a file
with open(output_file, 'w') as file:
    # Perform at least one request; if there's no search_after, there are no further results
    while search_after != None or first_request:
        # Only set search-after if this isn't the first request
        if not first_request:
            query_params["search-after"] = search_after

        # Set parameters for this query
        encoded_params = urlencode(query_params)
        full_url = f"{base_url}?{encoded_params}"

        # Now make request and extract the data and next search_after
        with urllib.request.urlopen(urllib.request.Request(full_url, headers=headers)) as response:
            response_body = response.read()
            body = response_body.decode()
            search_after = response.getheader('X-Next-Search-After')

        # For CSV data, only keep the header row from the first response
        if not first_request and body != "":
            body = body.split("\n", 1)[1]

        # Write received data
        file.write(body)

        first_request = False

Pagination using from (deprecated)

Warning: This method of pagination has been deprecated as of December 2023. It is recommended that all users switch to pagination using the search-after method.

Without any additional query parameters the API will return the first page of of all the display certificates, with a default page size of 25 results. This can be changed by specifying the size query parameter up to a maximum of 5,000.

Additional pages can be requested by changing the pagination offset with the from query string parameter.

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/display/search?size=1000&from=1000"

Or in python do:

import urllib.request
from urllib.parse import urlencode


token = "<encoded-api-key>"

headers = {
	'Accept': 'text/csv',
	'Authorization': f'Basic {token}'
}

# Define base URL and query parameters separately
base_url = 'https://epc.opendatacommunities.org/api/v1/display/search'
query_params = { 'size': 1000, 'from': 1000 }

# Encode query parameters
encoded_params = urlencode(query_params)

# Append parameters to the base URL
full_url = f"{base_url}?{encoded_params}"

# Now make request
with urllib.request.urlopen(urllib.request.Request(full_url, headers=headers)) as response:
	response_body = response.read()
	print(response_body.decode())
	

Note: This 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 use this method of pagination to query more than 10,000 results for a single search. If you require more than 10,000 records, please use the search-after pagination method, or alternatively you can also 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/display/search?address=liverpool"

Or in python do:

import urllib.request
from urllib.parse import urlencode


token = "<encoded-api-key>"

headers = {
    'Accept': 'text/csv',
    'Authorization': f'Basic {token}'
}

# Define base URL and query parameters separately
base_url = 'https://epc.opendatacommunities.org/api/v1/display/search'
query_params = {'address':'liverpool'}

# Encode query parameters
encoded_params = urlencode(query_params)

# Append parameters to the base URL
full_url = f"{base_url}?{encoded_params}"

# Now make request
with urllib.request.urlopen(urllib.request.Request(full_url, headers=headers)) as response:
    response_body = response.read()
    print(response_body.decode())

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/display/search?postcode=M1"

Or in python do:

import urllib.request
from urllib.parse import urlencode


token = "<encoded-api-key>"

headers = {
    'Accept': 'text/csv',
    'Authorization': f'Basic {token}'
}

# Define base URL and query parameters separately
base_url = 'https://epc.opendatacommunities.org/api/v1/display/search'
query_params = {'postcode':'M1'}

# Encode query parameters
encoded_params = urlencode(query_params)

# Append parameters to the base URL
full_url = f"{base_url}?{encoded_params}"

# Now make request
with urllib.request.urlopen(urllib.request.Request(full_url, headers=headers)) as response:
    response_body = response.read()
    print(response_body.decode())

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

Filtering by uprn

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

You can supply multiple uprnparameters if you wish to perform a union search, for example we can filter for certificates that have the values 100023336956 or 200001411981:

$ curl -v -H "Accept: text/csv" -H "Authorization: Basic <encoded-api-key>" "https://epc.opendatacommunities.org/api/v1/display/search?uprn=100023336956&uprn=200001411981"

Or in python do:

import urllib.request
from urllib.parse import urlencode


token = "<encoded-api-key>"

headers = {
    'Accept': 'text/csv',
    'Authorization': f'Basic {token}'
}

# Define base URL and query parameters separately
base_url = 'https://epc.opendatacommunities.org/api/v1/display/search'
query_params = {'uprn':'100023336956', 'uprn':'200001411981'}

# Encode query parameters
encoded_params = urlencode(query_params)

# Append parameters to the base URL
full_url = f"{base_url}?{encoded_params}"

# Now make request
with urllib.request.urlopen(urllib.request.Request(full_url, headers=headers)) as response:
    response_body = response.read()
    print(response_body.decode())

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/display/search?local-authority=E07000044"

Or in python do:

import urllib.request
from urllib.parse import urlencode


token = "<encoded-api-key>"

headers = {
    'Accept': 'text/csv',
    'Authorization': f'Basic {token}'
}

# Define base URL and query parameters separately
base_url = 'https://epc.opendatacommunities.org/api/v1/display/search'
query_params = {'local-authority':'E07000044'}

# Encode query parameters
encoded_params = urlencode(query_params)

# Append parameters to the base URL
full_url = f"{base_url}?{encoded_params}"

# Now make request
with urllib.request.urlopen(urllib.request.Request(full_url, headers=headers)) as response:
    response_body = response.read()
    print(response_body.decode())

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/display/search?constituency=E14000645"

Or in python do:

import urllib.request
from urllib.parse import urlencode


token = "<encoded-api-key>"

headers = {
    'Accept': 'text/csv',
    'Authorization': f'Basic {token}'
}

# Define base URL and query parameters separately
base_url = 'https://epc.opendatacommunities.org/api/v1/display/search'
query_params = {'constituency':'E14000645'}

# Encode query parameters
encoded_params = urlencode(query_params)

# Append parameters to the base URL
full_url = f"{base_url}?{encoded_params}"

# Now make request
with urllib.request.urlopen(urllib.request.Request(full_url, headers=headers)) as response:
    response_body = response.read()
    print(response_body.decode())

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/display/search?floor-area=l&floor-area=m"

Or in python do:

import urllib.request
from urllib.parse import urlencode


token = "<encoded-api-key>"

headers = {
    'Accept': 'text/csv',
    'Authorization': f'Basic {token}'
}

# Define base URL and query parameters separately
base_url = 'https://epc.opendatacommunities.org/api/v1/display/search'
query_params = {'floor-area':'l', 'floor-area':'m'}

# Encode query parameters
encoded_params = urlencode(query_params)

# Append parameters to the base URL
full_url = f"{base_url}?{encoded_params}"

# Now make request
with urllib.request.urlopen(urllib.request.Request(full_url, headers=headers)) as response:
    response_body = response.read()
    print(response_body.decode())

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/display/search?energy-band=a+&energy-band=a"

Or in python do:

import urllib.request
from urllib.parse import urlencode


token = "<encoded-api-key>"

headers = {
    'Accept': 'text/csv',
    'Authorization': f'Basic {token}'
}

# Define base URL and query parameters separately
base_url = 'https://epc.opendatacommunities.org/api/v1/display/search'
query_params = {'energy-band':'a+', 'energy-band':'a'}

# Encode query parameters
encoded_params = urlencode(query_params)

# Append parameters to the base URL
full_url = f"{base_url}?{encoded_params}"

# Now make request
with urllib.request.urlopen(urllib.request.Request(full_url, headers=headers)) as response:
    response_body = response.read()
    print(response_body.decode())

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/display/search?from-year=2015&from-month=5&to-year=2016&to-month=10"

Or in python do:

import urllib.request
from urllib.parse import urlencode


token = "<encoded-api-key>"

headers = {
    'Accept': 'text/csv',
    'Authorization': f'Basic {token}'
}

# Define base URL and query parameters separately
base_url = 'https://epc.opendatacommunities.org/api/v1/display/search'
query_params = { 'from-year': 2015, 'from-month': 5, 'to-year':2015, ;'to-month': 10 }

# Encode query parameters
encoded_params = urlencode(query_params)

# Append parameters to the base URL
full_url = f"{base_url}?{encoded_params}"

# Now make request
with urllib.request.urlopen(urllib.request.Request(full_url, headers=headers)) as response:
    response_body = response.read()
    print(response_body.decode())

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/display/search?address=liverpool&energy-band=c"

Display 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/display/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 27649711032019053114460431000094 by making a request to the API at the URL:

https://epc.opendatacommunities.org/api/v1/display/certificate/27649711032019053114460431000094

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/display/certificate/27649711032019053114460431000094"

Or in python do:

import urllib.request
from urllib.parse import urlencode


token = "<encoded-api-key>"

headers = {
    'Accept': 'text/csv',
    'Authorization': f'Basic {token}'
}

# Define base URL and query parameters separately
base_url = 'https://epc.opendatacommunities.org/api/v1/display/certificate/27649711032019053114460431000094'
query_params = ''

# Encode query parameters
encoded_params = urlencode(query_params)

# Append parameters to the base URL
full_url = f"{base_url}?{encoded_params}"

# Now make request
with urllib.request.urlopen(urllib.request.Request(full_url, headers=headers)) as response:
    response_body = response.read()
    print(response_body.decode())

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

Display 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/display/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/display/recommendations/27649711032019053114460431000094"

Or in python do:

import urllib.request
from urllib.parse import urlencode


token = "<encoded-api-key>"

headers = {
    'Accept': 'text/csv',
    'Authorization': f'Basic {token}'
}

# Define base URL and query parameters separately
base_url = 'https://epc.opendatacommunities.org/api/v1/display/recommendations/27649711032019053114460431000094'
query_params = ''

# Encode query parameters
encoded_params = urlencode(query_params)

# Append parameters to the base URL
full_url = f"{base_url}?{encoded_params}"

# Now make request
with urllib.request.urlopen(urllib.request.Request(full_url, headers=headers)) as response:
    response_body = response.read()
    print(response_body.decode())

API access to bulk download files

Access to the files available on the display bulk downloads page is also available using API authentication.

For example, to retrieve all display certificates for 2023 using API authentication:

$ curl -v -H "Authorization: Basic <encoded-api-key>" "https://epc.opendatacommunities.org/api/v1/files/display-2023.zip" -L -o "display-2023.zip"

All available bulk downloads are listed as a JSON object at the following API route:

https://epc.opendatacommunities.org/api/v1/files

For example, to view this data (output has been formatted and truncated):

$ curl -v -H "Accept: application/json" -H "Authorization: Basic <encoded-api-key>" "https://epc.opendatacommunities.org/api/v1/files"
{"files": {
    "all-domestic-certificates.zip": {"size": 6199109043},
    "non-domestic-2023.zip": {"size": 34557428},
    ...
}}