ECaaS Technical Documentation

Overview

ECaaS (Energy Calculation as a Service) is a calculator service run by MHCLG (Ministry of Housing, Communities, and Local Government) that provides a performant implementation of the Home Energy Model (HEM), a methodology for predicting the energy performance of buildings, for various future statutory purposes including, but not limited to, calculating compliance with the Future Homes Standard (FHS).

The service takes the form of an API that can be used by authorised bodies to build software for statutory purposes that require calculations using the Home Energy Model. The service will become the only valid means to e.g. confirm compliance with Part L of the Building Regulations when making reference to the Future Homes Standard. For other users, the underlying software libraries are open source and can be used in order to conduct calculations for non-statutory purposes. (The Rust library used by ECaaS, developed within MHCLG, can be found on GitHub, and the canonical Python implementation originated by BRE under commission from DESNZ (Department of Energy Security and Net Zero) is published on BRE’s Azure DevOps space.)

A basic web frontend is currently being developed to support stakeholders as they familiarise themselves with the HEM methodology and work out the impact on the types of home that they are building.

Current status of project

The API was initially released for early access to authorised bodies on November 27th 2024, and is being actively updated. It currently reflects version 0.34 of the HEM methodology, which was published on January 31st 2025. There are many known (and likely unknown) behavioural discrepancies between the Rust port of the software that ECaaS uses, and the Python implementation that it is based on. The library will reach 100% equivalence in behaviour long before ECaaS is used for any statutory purpose, but is not in such a state as yet, and therefore should not be used for e.g. work validating the HEM methodology.

The API currently has a beta versioning and, as such, may introduce backwards-compatibility breaks from time to time as the input specifications for FHS and HEM are finalised. The ECaaS project will keep the API documentation up to date and indicate changes to watch for on the changelog. Significant changes, such as migrations to updated versions of HEM/FHS, will be signposted to authorised bodies ahead of time. Once the input specifications for HEM and FHS have been finalised, we expect to remove this beta designation and make a stable endpoint, redirecting calls from the beta endpoint for a month before retiring it.

A list of known caveats is provided as part of this documentation. Headline changes will be reflected in the changelog.

API documentation

This documentation is for developers interested in using the Energy Calculation as a Service (ECaaS) API.

You can use the interactive API documentation to explore the API.

Authentication

The ECaaS API uses an OAuth 2.0 Client Credentials flow.

To make calls to the API you’ll need to obtain an Access Token.

POST /oauth2/token

To obtain an access token you can make a POST request to https://auth.building-energy-calculator-integration.communities.gov.uk/oauth2/token.

To authenticate you’ll need a Client ID and a Client Secret.

The POST request should have the application/x-www-form-urlencoded content type, with the following parameters:

Parameter	Value
grant_type	client_credentials
scope	ecaas-api/home-energy-model
client_id	{your client id}
client_secret	{your client secret}

Example request:

POST /oauth2/token HTTP/1.1
Host: auth.building-energy-calculator-integration.communities.gov.uk
Content-Type: application/x-www-form-urlencoded
Content-Length: 169

grant_type=client_credentials&client_id={XXXXXXXXXXXXXXXXXXXXXXXXXX}&scope=ecaas-api%2Fhome-energy-model&client_secret=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

If your request is successful you will receive a JSON response containing an Access Token.

Example response:

{
    "access_token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX...",
    "expires_in": 3600,
    "token_type": "Bearer"
}

When calling the ECaaS API the Access Token should be provided in an Authorization header, preceeded by Bearer.

The Access Token is set to expire after 15 minutes. Client code that calls the API should make sure to transparently acquire a new Access Token before retrying if any attempted calls respond with a 401 Unauthorized status.

Making a request

Base URL (integration environment)

https://api.building-energy-calculator-integration.communities.gov.uk

GET /

To retrieve information about the API and check that your access token is valid you can call the GET / endpoint.

Example request:

GET / HTTP/1.1
Host: api.building-energy-calculator-integration.communities.gov.uk
Authorization: Bearer XXXXXXX...

Example response:

{
    "links": {
        "describedBy": "https://docs.building-energy-calculator.communities.gov.uk/#ecaas-technical-documentation"
    },
    "title": "Energy Calculation as a Service",
    "version": "0.1.0"
}

Check Future Homes Standard Compliance [Beta]

You can use ECaaS to check compliance with the Future Homes Standard (FHS) based on the energy performance of a building calculated using the Home Energy Model (HEM).

Endpoint

POST /beta/future-homes-standard-compliance

Request structure

POST /beta/future-homes-standard-compliance HTTP/1.1
Host: api.building-energy-calculator-integration.communities.gov.uk
Authorization: Bearer XXXXXXX...
Content-Type: application/json

{
    ...
}

Example request body

See an example request body (opens in new tab). You can also use the interactive API documentation to view the request definition.

Example response

If the request is successful, the response body is JSON with a status code of 200:

{
    "data": {
        "dwelling_emission_rate": 29.85458751264378,
        "target_emission_rate": 31.61130283648656,
        "emission_rate_compliant": true,
        "dwelling_primary_energy_rate": 275.95387516860916,
        "target_primary_energy_rate": 254.87527761542435,
        "primary_energy_rate_compliant": false,
        "dwelling_fabric_energy_efficiency": 40.96297004171527,
        "target_fabric_energy_efficiency": 33.723746175514904,
        "fabric_energy_efficiency_compliant": false,
        "energy_demand": {
            "space_heating": {
                "actual": 17.16356340928921,
                "notional": 25.760607155988687
            },
            "space_cooling": {
                "actual": -64.17328615921666,
                "notional": -56.074844460081685
            }
        },
        "delivered_energy_use": {
            "total": {
                "actual": 175.24604509413854,
                "notional": 139.38990128808544
            },
            "by_system": {
                "mechvent1": {
                    "actual": 0.34781063416353913,
                    "notional": 0.0
                },
                "total": {
                    "actual": 175.24604509413854,
                    "notional": 139.38990128808544
                },
                "lighting": {
                    "actual": 0.004627869797161936,
                    "notional": 0.0021596725720089346
                },
                "Clothes_washing": {
                    "actual": 108.1879413550729,
                    "notional": 108.1879413550729
                },
                "Fridge": {
                    "actual": 2.1862745085161106,
                    "notional": 2.1862745085161106
                },
                "Oven": {
                    "actual": 1.589614115685917,
                    "notional": 1.589614115685917
                },
                "Kettle": {
                    "actual": 1.0357616579409936,
                    "notional": 1.0357616579409936
                },
                "Microwave": {
                    "actual": 0.2989791338236019,
                    "notional": 0.2989791338236019
                },
                "Otherdevices": {
                    "actual": 8.318576377200134,
                    "notional": 8.318576377200134
                },
                "immersion": {
                    "actual": 14.483917676567225,
                    "notional": 0.0
                },
                "main 1": {
                    "actual": 31.70746941267138,
                    "notional": 0.0
                },
                "main 2": {
                    "actual": 1.3349625945025114,
                    "notional": 0.0
                },
                "cooling system 1": {
                    "actual": 0.05116606530398112,
                    "notional": 0.04417504143392989
                },
                "cooling system 2": {
                    "actual": 3.6066535193630824,
                    "notional": 2.1109348259253
                },
                "Hobs": {
                    "actual": 2.09229017353001,
                    "notional": 2.09229017353001
                }
            }
        },
        "energy_use_by_fuel": {
            "total": {
                "actual": 71500.38639840852,
                "notional": 56871.07972553885
            },
            "mains elec": {
                "actual": 70646.73200760827,
                "notional": 56017.425334738604
            },
            "mains gas": {
                "actual": 853.6543908002442,
                "notional": 853.6543908002442
            }
        }
    },
    "meta": {
        "hem_version": "0.30",
        "hem_version_date": "2024-06-25",
        "fhs_version": "0.21",
        "fhs_version_date": "2024-06-25",
        "software_version": "f3303a81d75aaf8fda2d4d42b3eab7ead2b86dfa",
        "ecaas_request_id": "b6e02d18-f919-490e-bd1b-40d85d8ac456"
    }
}

Data

A summary of a successful HEM calculation to determine compliance with the Future Homes Standard (FHS) and includes the following fields (and more):

field	type	unit	description
dwelling_emission_rate	number	kgCO₂e/m²	The calculated DER (Dwelling Emission Rate) of the building.
target_emission_rate	number	kgCO₂e/m²	The determined TER (Target Emission Rate) used for the calculation for this building.
emission_rate_compliant	boolean		Whether this calculation determines that the building with the provided properties complies with the Future Homes Standard for emission rate.
dwelling_primary_energy_rate	number	kWh/m²	The calculated DPER (Dwelling Primary Energy Rate) of the building.
target_primary_energy_rate	number	kWh/m²	The determined TPER (Target Primary Energy Rate) used for the calculation for this building.
primary_energy_rate_compliant	boolean		Whether the calculated Dwelling Primary Energy Rate is compliant with FHS.
dwelling_fabric_energy_efficiency	number	kWh/m²	The calculated DFEE (Dwelling Fabric Energy Efficiency) of the building.
target_fabric_energy_efficiency	number	kWh/m²	The determined TPEE (Target Fabric Energy Efficiency) of the building.
fabric_energy_efficiency_compliant	boolean		Whether the calculated Dwelling Fabric Energy Efficiency is compliant with FHS.

You can use the interactive API documentation to view the full list of fields with description.

Metadata

field	description
hem_version	An identifier representing which version of HEM (the specification) was used, or available to be used, in this calculation.
hem_version_date	The date when the version of the HEM specification being used was published. Format: YYYY-MM-DD.
hem_version	An identifier representing which version of FHS (Future Homes Standard) (the specification) was used, or available to be used, in this calculation.
fhs_version_date	The date when the version of the FHS specification being used was published. Format: YYYY-MM-DD.
software_version	A unique identifier, usually a SHA, for the version of the HEM software library being used for this calculation
ecaas_request_id	A unique identifier for the request that you can use when reporting a problem to us.

Errors

If the request is not successful, the API returns JSON containing the relevant error code. For example:

{
    "errors": [
        {
            "id": "7a1bd4ae-b3c7-44bb-9102-31f5a7d3cb01",
            "status": "422",
            "detail": "Request was considered invalid due to error: missing field `start360` at line 9 column 42"
        }
    ],
    "meta": {
        "hem_version": "0.30",
        "hem_version_date": "2024-06-25",
        "fhs_version": "0.21",
        "fhs_version_date": "2024-06-25",
        "software_version": "f3303a81d75aaf8fda2d4d42b3eab7ead2b86dfa",
        "ecaas_request_id": "b6e02d18-f919-490e-bd1b-40d85d8ac456"
    }
}

status	description	how to fix
`401`	The request was not authorized.	Your access token may have expired.
`422`	The request could not be processed by the calculator.	Check your inputs against the API Documentation
`500`	An error happened at some stage in the ECaaS engine when processing the request.	Check known caveats and get in touch if your case is not covered.
`501`	The request has exercised an area of the HEM engine that has not yet been implemented in the MHCLG project.	Check known caveats and get in touch if your case is not covered.

Known caveats

No FHS calculations will succeed at the current time, because the FHS notional wrapper defines an element of the model that is not compatible with accepted input for the core HEM. This will be corrected in the service as soon as a compliant definition is decided upon in the notional wrapper (without requiring a release/ update of the upstream Python code). This caveat applies to both versions 0.32 and 0.34 of HEM/ FHS.
While the numbers emitted by the API are broadly accurate, there are still a number of inaccuracies in both the core HEM implementation and the FHS wrapper. Our team will be fixing these over the forthcoming period as we build out ever more demanding testing of acceptance criteria.
Numbers produced by the FHS compliance endpoint will differ slightly from the numbers produced by the Python implementation of HEM/FHS, as the model includes a statistical distribution of hot water events that cannot reasonably be seeded precisely the same between different versions of software. However, this statistical distribution is consistent between dwelling and notional calculations, and is therefore generally expected to produce the same compliance results (i.e. whether or not a building is compliant) across different versions of software.
The time taken for successful FHS compliance calculations is currently in the region of 2.5 to 3 seconds. As part of this compliance calculation, four individual HEM simulations are run, which each take in the region of one second. The deployment environment therefore is able to employ some parallelism to achieve this speed, but the parallelism is currently insufficient to run all four calculations directly in parallel. We expect in time to be able to make changes (some architectural) to ensure that we can achieve reliable parallelism, thereby speeding up the FHS compliance calculation by at least a factor of two. (The project has also not exhausted other optimisation opportunities.)
Field descriptions in the API documentation are sometimes incomplete currently - this is because the input schema for the Future Homes Standard has not yet been finalised. With a final schema there will also be canonical descriptions for what the fields represent, and their units of measurement.

Changelog

Some important changes to the ECaaS engine are documented here in reverse chronological order.

2025-04-04

Update of API to 0.34

Additions to API

There are some new possible fields in the root of the FHS input definition:

SmartApplianceControls

Additional fields to existing objects:

Controlmax is a new field on EnergyDiverter

Non-breaking changes to existing fields:

additional value heat_battery now available for ControlLogicType enumeration
StorageTank is no longer a required field for EnergyDiverter
shading_segments is no longer a required field on ExternalConditionsInput
additional possible values for FuelType enumeration: LPG_bottled, LPG_condition_11F, and energy_from_environment
thermostat_position is no longer a required field on the ImmersionHeater or HeatSourceWet variants of HeatSource
new SmartHotWaterTank variant of HotWaterSourceDetails type
advanced_start is added as an optional field on SpaceCoolSystemDetails

Breaking changes

appliances are now indicated by values defined within the ApplianceKey enumeration
general renamings of common properties:
- a_sol → solar_absorption_coeff
- k_m → areal_heat_capacity
- r_c → thermal_resistance_construction
- r_f → thermal_resistance_floor_construction
renamings of building element types:
- BuildingElementAdjacentZTC → BuildingElementAdjacentConditionedSpace
- BuildingElementAdjacentZTU_Simple → BuildingElementAdjacentUnconditionedSpace_Simple
renaming of field on HeatPump variant of HeatSourceWetDetails:
- test_data → test_data_EN14825
most fields of the HeatBattery variant of HeatSourceWetDetails have been fundamentally changed (too many to usefully list here - please refer to the API documentation directly)
new fields ColdWaterSource, Control, and HeatSourceWet for HeatBattery variant of HotWaterSourceDetails

2025-02-28

Update of API to 0.32

Additions to API

There are some new possible fields in the root of the FHS input definition:

temp_internal_air_static_calcs
PreHeatedWaterSource

Additional fields to existing objects:

ApplianceGains and ApplianceLoadShifting now each have an optional priority field
BuildingElementTransparent now has an optional treatment field, taking a WindowTreatment object
OnOffTimeControl now has an optional allow_null field
ChargeControl (former ToUChargeControl) now has external_sensor, full_charge_temp_diff, min_target_charge_factor, temp_charge_cut, and temp_charge_cut_delta fields
There are new control types: CombinationTimeControl, which is a combinator for other controls, and smartappliance
ElectricBattery now has a grid_charging_possible field
EnergySupplyDetails now has optional fields relating to tariff data: tariff, threshold_charges, and threshold_prices
HeatSource objects of types ImmersionHeater, HeatSourceWet and HeatPump_HWOnly have new fields Controlmax and Controlmin; additionally, HeatSource objects of type SolarThermalSystem has a new Controlmax field (but not Controlmin)
HeatSourceWetDetails objects of type HeatBattery now have fields labs_tests_losses, labs_tests_rated_output, and labs_tests_rated_output_enhanced
InfiltrationVentilation has additional fields: Control_VentAdjustMax, Control_VentAdjustMin, ach_max_static_calcs, ach_min_static_calcs, ventilation_zone_base_height, and vent_opening_ratio_init
OnSiteGenerationDetails has additional fields inverted_peak_power_ac and inverted_peak_power_dc, and inverter_type
ElecStorageHeater has additional fields storage_capacity, ESH_max_output, and ESH_min_output; it also drops a number of fields as listed in the “Breaking changes” section below
WetDistribution has additional fields bypass_percentage_recirculated, design_flow_rate, emitters, max_flow_rate, min_flow_rate, variable_flow, wet_emitter_type, and EnergySupply; it also drops the field c (which is defined within the emitters field instead)
ZoneInput has an additional field temp_setpnt_basis
ZoneLighting has an additional, optional field bulbs

Non-breaking changes to existing fields:

energy supplies are now keyed by any non-empty string, not just a set list of energy supply types
the enum ControlLogicType now comprises a few more defined possible values, not just “Manual”
the enum HeatPumpSinkType now has “Glycol25” as a possible value
the enum WaterPipeContentsType now has “glycol25” (sic) as a possible value
the SpaceHeatSystem field under ZoneInput now accepts lists of strings as well as an individual string

Breaking changes

ToUChargeControl is renamed ChargeControl
a minority of the additional fields to existing objects listed above are mandatory in some positions and under some circumstances, and therefore constitute breaking changes
ElecStorageHeater drops the fields A_core, U_ins, c_pcore, c_wall, mass_core, n_wall, rated_power, temp_charge_cut, temp_core_target, temp_dis_safe, thermal_mass, and thermal_mass_wall
WetDistribution drops the field c
the enum TerrainClass now has possible values “OpenWater”, “OpenField”, “Suburban”, and “Urban”, replacing the former values

2024-11-28

First release of the provisional API to integrators!
HEM is implemented to v0.30 (except the module for electric storage heaters) and FHS to v0.21.
Initial provisional FHS compliance response defined.