SPspruce
Estimates

Calculate estimate

Calculate a heat loss estimate for a property.

This endpoint is part of the Spruce extended API.

post/v1/estimates

Request

  • Base URL
    https://api.spruce.eco
  • Auth
    HTTP bearer

Request body

altitude_mnumber

Property altitude in meters. Will be derived from the coordinates if not provided.

built_form'detached' | 'semi_detached' | 'mid_terrace' | 'end_terrace' required

Built form of the property

floor_area_m2number required

Total floor area in square meters

fuel_type'mains_gas' | 'oil' | 'lpg' | 'electric' | 'coal' | 'wood' required

Current heating fuel type

loft_insulation'none' | '50mm' | '100mm' | '150mm' | '200mm' | '250+mm' required

Loft insulation thickness

num_bathroomsinteger

Number of bathrooms

num_bedroomsinteger required

Number of bedrooms

num_storeysinteger

Number of storeys

postcodestring required

UK postcode or Irish Eircode

property_type'house' | 'flat' | 'bungalow' required

Property type

room_height_mnumber

Room height in metres

wall_type'cavity_wall_filled' | 'cavity_wall_unfilled' | 'solid_brick_uninsulated' | 'solid_brick_internal_insulation' | 'solid_brick_external_insulation' | 'solid_brick_unknown' | 'solid_stone_uninsulated' | 'solid_stone_internal_insulation' | 'solid_stone_external_insulation' | 'solid_stone_unknown' | 'solid_concrete_uninsulated' | 'solid_concrete_internal_insulation' | 'solid_concrete_external_insulation' | 'solid_concrete_unknown' | 'timber_uninsulated' | 'timber_internal_insulation' | 'timber_external_insulation' | 'timber_unknown' required

Wall construction and insulation type

window_type'single_glazing' | 'double_glazing' | 'high_performance' | 'triple_glazing' required

Window glazing type

floor_u_valuenumber

Floor U-value in W/m²K (optional, if directly measured or from EPC). If provided, overrides the floor U-value used in the heat loss calculation.

roof_u_valuenumber

Roof U-value in W/m²K (optional, if directly measured or from EPC). If provided, overrides the roof U-value used in the heat loss calculation (otherwise derived from loft_insulation).

wall_u_valuenumber

External wall U-value in W/m²K (optional, if directly measured or from EPC). If provided, overrides both the external wall and party wall U-values used in the heat loss calculation (party wall capped at 0.5 W/m²K; otherwise derived from wall_type).

window_u_valuenumber

Window U-value in W/m²K (optional, if directly measured or from EPC). If provided, overrides the window U-value used in the heat loss calculation (otherwise derived from window_type).

lat_lngnumber[]

Latitude and longitude coordinates of the address [lat, lng]. Will be calculated from the postcode if not provided.

ventilation_heat_loss_method'ach' | 'air_permeability'

The method used to calculate heat loss via ventilation ('air_permeability' is the current, BS EN 12831 method, 'ach' is the legacy CIBSE method).

Example request

{
  "altitude_m": 50,
  "built_form": "semi_detached",
  "floor_area_m2": 120,
  "fuel_type": "mains_gas",
  "loft_insulation": "150mm",
  "num_bathrooms": 2,
  "num_bedrooms": 3,
  "num_storeys": 2,
  "postcode": "SW1A 1AA",
  "property_type": "house",
  "room_height_m": 2.4,
  "wall_type": "cavity_wall_filled",
  "window_type": "double_glazing",
  "floor_u_value": 0.18,
  "roof_u_value": 0.11,
  "wall_u_value": 0.18,
  "window_u_value": 1.4,
  "lat_lng": [
    51.5014,
    -0.1419
  ],
  "ventilation_heat_loss_method": "air_permeability"
}

Response

Successfully calculated estimate

urlstring uri

Link to the estimate if it exists on Spruce

Example response

{
  "estimates": [
    {
      "annual_heat_energy_demand_w": 1850000,
      "average_heat_pump_efficiency": 3.32,
      "co2_saved_kg": 4528,
      "commutes_saved_petrol_car": 1258,
      "efficiency_baseline": 0.87,
      "electricity_tariff_baseline_annual_bill_gbp": 1450,
      "electricity_tariff_baseline_pence_per_kwh": 6.24,
      "electricity_tariff_baseline_price_cap_pence_per_kwh": 24.5,
      "electricity_tariff_heat_pump_annual_bill_gbp": 1150,
      "electricity_tariff_heat_pump_annual_bill_price_cap_gbp": 1370,
      "electricity_tariff_heat_pump_based_on": "Octopus Cosy Octopus tariff",
      "electricity_tariff_heat_pump_pence_per_kwh": 20.6,
      "flights_to_spain_saved": 23,
      "flow_temp_c": 45,
      "fuel_name_baseline": "Mains Gas",
      "heat_pumps": [
        {
          "calculated_capacity_w": 720,
          "calculated_scop": 3.6,
          "inventory_heat_pump_name": "Vaillant aroTHERM plus 7kW"
        }
      ],
      "hot_water_cylinders": [
        {
          "capacity_l": 200,
          "inventory_hot_water_cylinder_name": "Joule 200L"
        }
      ],
      "internal_temp_c": 20,
      "outdoor_temp_c": -3.2,
      "overall_scop": 3.6,
      "price_cap_description": "Ofgem Price Cap Q4 2024",
      "total_heat_loss_w": 720,
      "total_price_excluding_grants_pence": 20000,
      "total_price_including_grants_pence": 12500
    }
  ],
  "url": "https://app.spruce.eco/theheatingco/estimate/01234567-89ab-cdef-0123-456789abcdef"
}

Changes

No recorded changes to this operation across all 1 revision of this API.