--- title: "Calculate estimate" method: POST path: "/v1/estimates" tags: ["Estimates"] --- # Calculate estimate `POST /v1/estimates` ## Request - Base URL: `https://api.spruce.eco` - URL: `https://api.spruce.eco/v1/estimates` - Auth: HTTP bearer Calculate a heat loss estimate for a property. This endpoint is part of the Spruce extended API. ## Request body - object - `altitude_m` number: 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_m2` number, 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_bathrooms` integer: Number of bathrooms - `num_bedrooms` integer, required: Number of bedrooms - `num_storeys` integer: Number of storeys - `postcode` string, required: UK postcode or Irish Eircode - `property_type` 'house' | 'flat' | 'bungalow', required: Property type - `room_height_m` number: 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_value` number: 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_value` number: 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_value` number: 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_value` number: 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_lng` number[]: 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). ## Response `200` Successfully calculated estimate - object - `estimates` object[], required: Array of estimate options. Currently returns one estimate based on best-fit equipment from inventory; will support multiple estimate configurations in future. - `annual_heat_energy_demand_w` number, required: Annual heat energy demand in watts (space heating + hot water) - `average_heat_pump_efficiency` number, required: Average heat pump efficiency including hot water (lower than sCOP) - `co2_saved_kg` number, required: Annual CO2 savings in kg compared to current heating system - `commutes_saved_petrol_car` number, required: CO2 savings expressed as an equivalent number of 12-mile round trip petrol car commutes - `efficiency_baseline` number, required: Current heating system efficiency (e.g., 0.87 for oil boiler) - `electricity_tariff_baseline_annual_bill_gbp` number, required: Estimated annual heating bill with current system in GBP (excluding standing charge) - `electricity_tariff_baseline_pence_per_kwh` number, required: Current fuel tariff in pence per kWh - `electricity_tariff_baseline_price_cap_pence_per_kwh` number, required: Standard electricity price cap in pence per kWh - `electricity_tariff_heat_pump_annual_bill_gbp` number, required: Estimated annual heating bill with heat pump on dedicated tariff in GBP - `electricity_tariff_heat_pump_annual_bill_price_cap_gbp` number, required: Estimated annual heating bill with heat pump on price cap tariff in GBP - `electricity_tariff_heat_pump_based_on` string, required: Description of electricity tariff used - `electricity_tariff_heat_pump_pence_per_kwh` number, required: Electricity tariff in pence per kWh (heat pump tariff) - `flights_to_spain_saved` number, required: CO2 savings expressed as an equivalent number of flights from the UK to Spain - `flow_temp_c` number: Heat pump flow temperature in °C - `fuel_name_baseline` string, required: Current fuel type name - `heat_pumps` object[], required: Heat pumps selected for this estimate. Empty if no heat pump large enough is available at these design conditions. - `calculated_capacity_w` number, required: Capacity in watts at the design specified outdoor and flow temperatures - `calculated_scop` number, required: Seasonal Coefficient of Performance - `inventory_heat_pump_name` string, required: Heat pump model name - `hot_water_cylinders` object[], required: Hot water cylinders selected for this estimate. Empty if no hot water cylinder large enough is available at these design conditions. - `capacity_l` number, required: Cylinder capacity in litres - `inventory_hot_water_cylinder_name` string, required: Hot water cylinder model name - `internal_temp_c` number, required: Design internal temperature in °C - `outdoor_temp_c` number, required: Design outdoor temperature in °C for the location - `overall_scop` number: Overall Seasonal Coefficient of Performance for space heating - `price_cap_description` string, required: Description of price cap used - `total_heat_loss_w` number, required: Total peak heat loss in watts for all heat pumps - `total_price_excluding_grants_pence` number, required: Total installation quote price in pence before any grant deductions (including VAT where applicable) - `total_price_including_grants_pence` number, required: Total installation quote price in pence after grant deductions (including VAT where applicable) - `url` string, uri: Link to the estimate if it exists on Spruce ## Other responses - `400`: Validation error - `401`: Unauthorized - missing or invalid token - `403`: Forbidden - insufficient permissions - `422`: Unprocessable entity --- [API](https://skmtc.dev/spruce/apis/spruce-external-api.md) - [All operations](https://skmtc.dev/spruce/apis/spruce-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/spruce/apis/spruce-external-api/revisions/ffdfaf1a73d9?raw)