How to run a SAP 10 calculation
This post uses an API to run a Standard Assessment Procedure 10.2 (SAP 10) calculation.
What is an API?
An API is an Application Programming Interface. In this case this simply means that there is a software programme hosted on a web server. We can send this programme some data and then the programme will run some calculations on the data and send back the result.
The API we are using here is this one.
What is SAP 10?
The Standard Assessment Procedure is a method to calcule the energy consumption of UK dwellings. SAP version 10 is published by the Building Research Establishment (see here). SAP 10.2 is the latest version and is used by the UK government in the building regulations for the design of new dwellings. SAP is also the calculation engine for domestic energy performance certificates.
How to run a SAP calculation?
To run a SAP calculation using the API, we need to:
- Create a SAP input data file
- Send the SAP input data file over the internet to the API
- Let the API run the SAP calculation
- Receive the calculation results from the API
Creating the SAP input data file
SAP10 uses XML as the format for its input files. SAP XML files follow a schema (a set of rules), and the schema used by the API is the SAP-Schema-19.1.0. This XML Schema sets out the names of the XML elements and the attributes and text values they can hold.
Here we will use a SAP XML file (detached_house.xml) which has already been created. It's available here and looks like this:
<?xml version='1.0' encoding='UTF-8'?>
<SAP-Report xmlns="https://epbr.digital.communities.gov.uk/xsd/sap">
<Schema-Version-Original>SAP-Schema-19.1.0</Schema-Version-Original>
<SAP-Version>10.2</SAP-Version>
<SAP10-Data>
<Data-Type>1</Data-Type>
<SAP-Property-Details>
<Cold-Water-Source>1</Cold-Water-Source>
<Living-Area>30</Living-Area>
<Windows-Overshading>2</Windows-Overshading>
<SAP-Building-Parts>
<SAP-Building-Part>
<Building-Part-Number>1</Building-Part-Number>
<SAP-Floor-Dimensions>
<SAP-Floor-Dimension>
<Floor-Type>2</Floor-Type>
<Storey>0</Storey>
<Total-Floor-Area>100</Total-Floor-Area>
<Storey-Height>3</Storey-Height>
<Heat-Loss-Area>100</Heat-Loss-Area>
<U-Value>0.5</U-Value>
</SAP-Floor-Dimension>
</SAP-Floor-Dimensions>
<SAP-Walls>
<SAP-Wall>
<Wall-Type>2</Wall-Type>
<Total-Wall-Area>120</Total-Wall-Area>
<U-Value>0.5</U-Value>
<Name>sap_wall_1_1</Name>
</SAP-Wall>
</SAP-Walls>
<SAP-Roofs>
<SAP-Roof>
<Total-Roof-Area>100</Total-Roof-Area>
<U-Value>0.5</U-Value>
<Roof-Type>2</Roof-Type>
<Name>sap_roof_1_1</Name>
</SAP-Roof>
</SAP-Roofs>
<SAP-Openings>
<SAP-Opening>
<Type>sap_opening_type_1</Type>
<Height>1.5</Height>
<Width>5</Width>
<Location>sap_wall_1_1</Location>
<Orientation>5</Orientation>
</SAP-Opening>
</SAP-Openings>
<SAP-Thermal-Bridges>
<Thermal-Bridge-Code>1</Thermal-Bridge-Code>
</SAP-Thermal-Bridges>
</SAP-Building-Part>
</SAP-Building-Parts>
<SAP-Opening-Types>
<SAP-Opening-Type>
<Name>sap_opening_type_1</Name>
<Type>4</Type>
<Data-Source>2</Data-Source>
<U-Value>1.5</U-Value>
<Glazing-Type>3</Glazing-Type>
</SAP-Opening-Type>
</SAP-Opening-Types>
<SAP-Heating>
<Has-Hot-Water-Cylinder>0</Has-Hot-Water-Cylinder>
<Thermal-Store>1</Thermal-Store>
<Secondary-Heating-Category>1</Secondary-Heating-Category>
<Water-Heating-Code>901</Water-Heating-Code>
<Main-Heating-Details>
<Main-Heating>
<Main-Heating-Number>1</Main-Heating-Number>
<Main-Fuel-Type>1</Main-Fuel-Type>
<Main-Heating-Category>2</Main-Heating-Category>
<Main-Heating-Data-Source>3</Main-Heating-Data-Source>
<Main-Heating-Code>104</Main-Heating-Code>
<Is-Central-Heating-Pump-In-Heated-Space>1</Is-Central-Heating-Pump-In-Heated-Space>
<Main-Heating-Fraction>1</Main-Heating-Fraction>
<Heat-Emitter-Type>1</Heat-Emitter-Type>
<Main-Heating-Control>2106</Main-Heating-Control>
<Has-Separate-Delayed-Start>0</Has-Separate-Delayed-Start>
<Is-Interlocked-System>0</Is-Interlocked-System>
</Main-Heating>
</Main-Heating-Details>
</SAP-Heating>
<SAP-Ventilation>
<Open-Chimneys-Count>0</Open-Chimneys-Count>
<Open-Flues-Count>0</Open-Flues-Count>
<Closed-Flues-Count>0</Closed-Flues-Count>
<Boilers-Flues-Count>0</Boilers-Flues-Count>
<Other-Flues-Count>0</Other-Flues-Count>
<Blocked-Chimneys-Count>0</Blocked-Chimneys-Count>
<Extract-Fans-Count>0</Extract-Fans-Count>
<PSV-Count>0</PSV-Count>
<Flueless-Gas-Fires-Count>0</Flueless-Gas-Fires-Count>
<Pressure-Test>2</Pressure-Test>
<Air-Permeability>3.5</Air-Permeability>
<Sheltered-Sides-Count>2</Sheltered-Sides-Count>
<Ventilation-Type>1</Ventilation-Type>
</SAP-Ventilation>
</SAP-Property-Details>
</SAP10-Data>
</SAP-Report>
This XML file is describing a detached house with a single south-facing window and a gas boiler. This is around the minimum amount of information needed to run a full SAP calculation.
The XML file can be difficult to read. Some parts can make sense, such as the line <Total-Floor-Area>100</Total-Floor-Area> which means that the total floor area is 100m2. Other lines, such as <Floor-Type>2</Floor-Type> cannot be easily understood. This is because the SAP schema uses codes for many variables. The code '2' for floor type is referring to a 'ground floor'.
Send the SAP input data file over the internet to the API
One way to send the data to the SAP API is to use the curl programme, which is a command line tool normally already installed on most PCs.
The steps are:
- Open up the Command Prompt programme (i.e. Windows Start Button -> Command Prompt)
- Change the Command Prompt directory to the location where the "detached_house.xml" file is located (this is done used the Command Prompt
cdcommand) - Run the following command in the Command Prompt:
curl --form file="@detached_house.xml" https://netzeroapis.com/calc/sap10
If this has worked, you should see a stream of data now being printed in the Command Prompt. This is the results of the SAP calculation.
This is how this process looks on my PC:
In practice, most developers would use a programming language such as Python to call an API. This automates the process and allows for easier analysis of the results.
Here is how the same process can be done in Python:
import requests
with open('detached_house.xml', 'rb') as input_file:
result = requests.post(
url = 'https://netzeroapis.com/calc/sap10',
files = {'file': input_file},
headers = {'Authorization': None}
)
output_dict = result['sap_calculation_output_dict']
print(output_dict['value_258'], output_dict['sap_band'])
# >>> 75, 'C'The detached house is calculated to have a SAP rating of 75 and to be in the SAP band 'C'.
There is also a Python package available to do this as described here.
Summary
This post has shown how to run a SAP10 calculation. This used a SAP XML input file which was sent a remote API using two methods: i) the Command Prompt and curl; and ii) Python.
The most challenging part of this process is probably creating the SAP input data file in the first place. How to do this is discussed in a separate blog post.
The output of the SAP calculation also contains hundreds of individual results. How to analysis this is also discussed in a separate blog post.