Suggested Renovations API

curl --request POST \
  --url https://public-api.setle.app/v1/calculation-jobs/suggested-renovation-trajectory-calculation \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "year_built": 2,
  "estate_format": "SEMI_OPEN",
  "habitable_space_m2": 2,
  "zip_code": "<string>",
  "country": "BE",
  "roof_type": "INCLINED",
  "inclined_roof_pane_surface": 2,
  "flat_roof_pane_surface": 2,
  "inclined_roof_insulation_type": "NONE",
  "flat_roof_insulation_type": "NONE",
  "attic_usage": "STORAGE",
  "heating_type": "ELECTRIC",
  "heating_device": "DIRECT_ACCUMULATION",
  "sanitary_heating_device": "GAS_BOILER",
  "installation_age": "ZERO_TO_FIVE_YEARS_OLD",
  "has_solar_panels": true,
  "has_solar_boiler": true,
  "ground_floor_surface": 2,
  "basement_type": "NONE",
  "basement_ceiling_surface": 2,
  "basement_ceiling_height": "HIGHER_THAN_120_CM",
  "solid_ground_floor_insulation_type": "NONE",
  "floor_above_basement_insulation_type": "NONE",
  "outer_wall_insulation_type": "NONE",
  "has_cavity_wall": true,
  "cavity_wall_width": "EQUAL_OR_MORE_THAN_5_CM",
  "has_cavity_wall_insulation": true,
  "window_glazing_type": "SINGLE_GLAZING",
  "window_glazing_surface": 2,
  "building_width": 2,
  "building_depth": 2,
  "cornice_height": 2,
  "energy_efficiency_score": 123,
  "street": "<string>",
  "house_number": "<string>",
  "house_number_extra": "<string>",
  "place": "<string>",
  "price": 2,
  "title": "<string>",
  "description": "<string>",
  "epc_url": "<string>",
  "external_id": "<string>",
  "webhook_url": "<string>"
}
'

{
  "id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "external_id": "<string>",
  "deactivated_at": "2023-11-07T05:31:56Z",
  "calculation_job_type": "EPC_DOCUMENT_PROCESSING",
  "calculation_job_status": "NOT_STARTED",
  "metadata": {},
  "estate_id": "<string>",
  "name": "<string>",
  "description": "<string>",
  "expires_at": "2023-11-07T05:31:56Z",
  "published_at": "2023-11-07T05:31:56Z"
}

​

1. Introduction

Unlock smarter renovation planning with our API. It automatically transforms EPC certificates and property data into actionable renovation roadmaps. By processing uploaded EPC documents, enriching gaps with trusted external data, and calculating optimal step-by-step renovation sequences, the API helps you:

• Maximize energy efficiency gains
• Optimize cost vs. benefit
• Leverage available subsidies

Deliver clear, EPC-driven renovation plans that empower property owners, advisors, and financial institutions to make confident, sustainable decisions while improving their property’s energy performance rating.

---

​

2. Process Overview

The API follows these EPC-centric steps:

1. EPC Document Processing: Extracts comprehensive property information from uploaded EPC certificates, capturing:
   • Current EPC rating
   • Energy consumption breakdown (heating, cooling, hot water)
   • Building characteristics (construction year, type, dimensions)
   • Insulation levels (walls, roof, floor, windows)
   • Heating system efficiency and fuel type
   • Ventilation system
2. Data Enrichment: Enhances property data with:
   • LiDAR Integration: Provides accurate property measurements using LiDAR datasets for building dimensions, roof surface, and facade areas
   • VEKA Provider: Calculates energy efficiency indicators and validates renovation impact on EPC scores
   • Missing Value Prediction: ML model fills gaps in property attributes when direct data is unavailable
3. EPC-Driven Renovation Selection: Determines optimal renovation components based on:
   • Current EPC score and improvement potential
   • EPC impact per euro invested (energy efficiency ROI)
   • Regulatory compliance with local EPC standards
   • Subsidy eligibility for EPC improvements
4. Supporting Works: Automatically includes essential costs:
   • Scaffolding for facade renovations
   • Architecture Costs for structural changes
5. Trajectory optimization: The API sequences renovations for maximum efficiency and compliance by prioritizing:
   • EPC improvement per euro invested
   • Logical execution order (e.g., insulation before heating upgrades)
   • Regulatory compliance with local building codes
   • Budget optimization including subsidies and incentives

Budget optimization including subsidies and incentives

---

​

3. Business Logic & Data Enrichment

​

3.1 EPC Document Processing

The API’s core functionality revolves around intelligent EPC (Energy Performance Certificate) document processing. When an EPC document is uploaded, the system performs comprehensive analysis to extract critical property information and identify renovation opportunities.

​

3.1.1 Document Analysis Pipeline

The EPC processing follows a multi-stage pipeline:

1. Document Validation & Parsing
   • Validates EPC document format and completeness
   • Extracts structured data using OCR and NLP techniques
   • Identifies document type (residential, commercial, mixed-use)
   • Verifies document authenticity and recency
2. Property Data Extraction
   • Building Characteristics: Construction year, building type, total floor area
   • Energy Performance: Current EPC score, energy consumption indicators
   • Insulation Levels: Wall, roof, floor, and window insulation values
   • Heating Systems: Type, efficiency rating, fuel source
   • Ventilation: Current ventilation system type and efficiency
   • Renewable Energy: Existing solar panels, heat pumps, etc.
3. Data Quality Assessment
   • Flags missing or incomplete data points
   • Identifies potential data inconsistencies
   • Assigns confidence scores to extracted values
   • Determines which external data sources are needed for enrichment

​

3.1.2 EPC Score Analysis

The system performs deep analysis of the EPC score to understand improvement potential:

• Current EPC Classification: Maps to energy efficiency scale (A++ to G)
• Energy Consumption Breakdown: Analyzes heating, cooling, hot water, lighting consumption
• Improvement Potential: Calculates theoretical maximum EPC improvement
• Priority Areas: Identifies which building components offer the highest ROI for EPC improvement

​

3.1.3 Property Component Mapping

EPC data is mapped to renovation components:

​

3.1.4 Missing Data Prediction

When EPC documents lack specific measurements, the system uses ML models to predict missing values:

• Surface Areas: Predicts facade, roof, and floor areas based on building dimensions
• U-values: Estimates insulation levels based on construction year and building type
• System Efficiency: Predicts heating system efficiency based on age and type
• Energy Consumption: Estimates consumption patterns based on building characteristics

​

3.2 LiDAR Data Enrichment

The API integrates with LiDAR data sources to provide accurate property measurements. If certain data points are missing (e.g., roof area, building width, depth), the API queries LiDAR datasets to retrieve them.

​

3.3 Machine Learning Predictions

A trained ML model refines missing values and predicts energy efficiency scores. The confidence_score in the response indicates how much of the final result is based on direct data vs. predictions.

​

3.3.1 Confidence Score & Pricing Accuracy

The confidence_score parameter helps users assess the accuracy of the returned results:

• If LiDAR data is available, the expected confidence score is ~78%.
• Lower scores indicate the API made more assumptions due to missing data.

​

3.4 Renovation Step Selection Criteria

The suggested renovation trajectory follows a priority-based approach:

1. Maximizing EPC improvement
2. Choosing cost-effective solutions when impact is equal
3. Selecting actions based on subsidy availability

---

​

4. Implementation Considerations

​

4.1 Authentication

• The API requires an OAuth2 Bearer Token.
• Use the Create new Access Token endpoint to obtain an access token.

​

4.2 Polling Mechanism

Since calculations are asynchronous, clients should poll the status endpoint periodically until the job status changes to FINISHED.

---

​

5. Frequently Asked Questions (FAQs)

​

What if the EPC score seems incorrect?

• Check the confidence_score. A low value indicates the model had to rely heavily on predictions instead of actual EPC data.
• Verify that the uploaded EPC document is complete and recent.
• Consider providing additional property measurements for more accurate EPC calculations.

​

How accurate are the EPC score improvements?

• EPC score improvements are calculated using VEKA provider validation and LiDAR data for maximum accuracy.
• The energy_efficiency_indication field shows the final EPC score after all renovations.
• High confidence scores (>0.80) indicate very reliable EPC predictions.

​

Can I get EPC-specific subsidies?

• Yes! The API automatically identifies EPC-related subsidies and incentives available for each renovation component.
• Subsidy amounts are calculated based on current EPC score and proposed improvements.

---

​

Final Notes

• This EPC-powered API is particularly useful for real estate developers and homeowners looking for automated, EPC-optimized renovation trajectories.
• LiDAR data and ML predictions are integrated to deliver optimal EPC improvement recommendations, maximizing energy efficiency gains from all available data.
• Users are encouraged to cross-check low-confidence EPC results with additional manual data input to improve accuracy and ensure regulatory compliance.