Display API

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"

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

Response Format Accept Header
CSV text/csv
Excel (pre 2007) application/vnd.ms-excel
Excel (post 2007) application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
JSON application/json
Zip (certificates.csv & recommendations.csv) application/zip

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/:certificate-hash

Where :certificate-hash is the Certificate Hash of a certificate from a search result or download. For example we can request the certificate with Certificate Hash of f162fd44affedc64966419fc7e2642031a9a219fcf559c48f4d6ac6f49cecfce by making a request to the API at the URL:

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

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/f162fd44affedc64966419fc7e2642031a9a219fcf559c48f4d6ac6f49cecfce"

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.

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/12620160722020721"