> ## Documentation Index
> Fetch the complete documentation index at: https://developer.setle.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Suggested Renovations API

> Creates a new calculation job for suggested renovation trajectory calculations.

## **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:

| EPC Data Point         | EPC Score Impact | Priority Level |
| ---------------------- | ---------------- | -------------- |
| **Wall(s) U-value**    | **High**         | 🔥 Critical    |
| **Roof(s) U-value**    | **High**         | 🔥 Critical    |
| **Floor(s) U-value**   | **Medium**       | ⚡ Important    |
| **Window(s) U-value**  | **Medium**       | ⚡ Important    |
| **Heating efficiency** | **Very High**    | 🚀 Highest     |
| **Ventilation type**   | **Medium**       | ⚡ Important    |

#### **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:

| Confidence Score | Expected Price Error (avg) | Standard Deviation | Notes                                               |
| ---------------- | -------------------------- | ------------------ | --------------------------------------------------- |
| `< 0.60`         | **>20%**                   | **>30%**           | High error margin, model relied on many assumptions |
| `0.60 - 0.70`    | **\~15%**                  | **\~13%**          | Moderate accuracy, reasonable estimates             |
| `0.70 - 0.80`    | **\~14%**                  | **\~13%**          | Good accuracy, confidence in most cases             |
| `> 0.80`         | **\~5%**                   | **\~8%**           | Very high accuracy, minimal deviations              |

* 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**](/api-reference/authentication/create) to obtain an access token.

### **4.2 Polling Mechanism**

Since calculations are **asynchronous**, clients should [**poll the status endpoint**](/api-reference/calculation/get-calculation-job) 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.


## OpenAPI

````yaml POST /v1/calculation-jobs/suggested-renovation-trajectory-calculation
openapi: 3.0.0
info:
  title: Setle API
  description: ''
  version: '1.0'
  contact: {}
servers:
  - url: https://public-api.setle.app
security: []
tags: []
paths:
  /v1/calculation-jobs/suggested-renovation-trajectory-calculation:
    post:
      tags:
        - Calculation Job
      description: >-
        Creates a new calculation job for suggested renovation trajectory
        calculations.
      operationId: >-
        PublicCalculationJobsApiController_postSuggestedRenovationTrajectoryCalculationCalculationJob
      parameters: []
      requestBody:
        required: true
        description: Body with required input data.
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/PostSuggestedRenovationTrajectoryCalculationCalculationJobDto
      responses:
        '200':
          description: Successfully processed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCalculationJobDetailDto'
        '401':
          description: >-
            Request failed because of missing authorization. An access token
            should be provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedHttpException'
        '403':
          description: >-
            Request failed because of missing permissions on the given access
            token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenHttpException'
        '406':
          description: >-
            Request failed because of per-property violations of the API
            specification.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotAcceptableHttpException'
        '422':
          description: >-
            Request failed because the request body contains data that is
            inconsistent with business logic requirements.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityHttpException'
        '500':
          description: Request failed because of internal server error(s).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorHttpException'
      security:
        - bearer: []
components:
  schemas:
    PostSuggestedRenovationTrajectoryCalculationCalculationJobDto:
      type: object
      properties:
        year_built:
          type: number
          minimum: 1
        estate_format:
          type: string
          enum:
            - SEMI_OPEN
            - OPEN
            - CLOSED
        habitable_space_m2:
          type: number
          minimum: 1
        roof_type:
          type: string
          enum:
            - INCLINED
            - FLAT
            - MIXED
        inclined_roof_pane_surface:
          type: number
          minimum: 1
        flat_roof_pane_surface:
          type: number
          minimum: 1
        inclined_roof_insulation_type:
          enum:
            - NONE
            - LIGHT
            - MODERATE
            - STRONG
          type: string
        flat_roof_insulation_type:
          enum:
            - NONE
            - LIGHT
            - MODERATE
            - STRONG
          type: string
        attic_usage:
          enum:
            - STORAGE
            - LIVING_SPACE
            - NOT_USED
          type: string
        heating_type:
          enum:
            - ELECTRIC
            - FUEL_OIL
            - GAS
            - HEAT_PUMP
            - PELLET_FUEL
            - WOOD
            - NONE
          type: string
        heating_device:
          type: string
          enum:
            - DIRECT_ACCUMULATION
            - CONDENSING_BOILER
            - NON_CONDENSING_BOILER
            - STOVE
            - AIR_AIR_HEAT_PUMP
            - AIR_WATER_HEAT_PUMP
            - GEOTHERMAL_HEAT_PUMP
        sanitary_heating_device:
          enum:
            - GAS_BOILER
            - FUEL_OIL_BOILER
            - ELECTRIC_BOILER
            - HEAT_PUMP_BOILER
            - NOT_SEPARATED
            - NONE
          type: string
        installation_age:
          enum:
            - ZERO_TO_FIVE_YEARS_OLD
            - FIVE_TO_TEN_YEARS_OLD
            - OLDER_THAN_TEN_YEARS
          type: string
        has_solar_panels:
          type: boolean
        has_solar_boiler:
          type: boolean
        ground_floor_surface:
          type: number
          minimum: 1
        basement_type:
          type: string
          enum:
            - NONE
            - FULL
            - PARTIAL
            - UNSPECIFIED
        basement_ceiling_surface:
          type: number
          minimum: 1
        basement_ceiling_height:
          enum:
            - HIGHER_THAN_120_CM
            - LOWER_THAN_120_CM
          type: string
        solid_ground_floor_insulation_type:
          enum:
            - NONE
            - LIGHT
            - MODERATE
            - STRONG
          type: string
        floor_above_basement_insulation_type:
          enum:
            - NONE
            - MODERATE
            - STRONG
          type: string
        outer_wall_insulation_type:
          enum:
            - NONE
            - LIGHT
            - MODERATE
            - STRONG
          type: string
        has_cavity_wall:
          type: boolean
        cavity_wall_width:
          enum:
            - EQUAL_OR_MORE_THAN_5_CM
            - LESS_THAN_5_CM
          type: string
        has_cavity_wall_insulation:
          type: boolean
        window_glazing_type:
          enum:
            - SINGLE_GLAZING
            - DOUBLE_GLAZING
            - HR
            - TRIPLE_GLAZING
          type: string
        window_glazing_surface:
          type: number
          minimum: 1
        building_width:
          type: number
          minimum: 1
        building_depth:
          type: number
          minimum: 1
        cornice_height:
          type: number
          minimum: 1
        energy_efficiency_score:
          type: number
        street:
          type: string
        house_number:
          type: string
        house_number_extra:
          type: string
        place:
          type: string
        zip_code:
          type: string
        country:
          type: string
          enum:
            - BE
            - NL
        price:
          type: number
          minimum: 1
        title:
          type: string
        description:
          type: string
        epc_url:
          type: string
        external_id:
          type: string
        webhook_url:
          type: string
      required:
        - year_built
        - estate_format
        - habitable_space_m2
        - zip_code
        - country
    GetCalculationJobDetailDto:
      type: object
      properties:
        id:
          type: string
        created_at:
          format: date-time
          type: string
        updated_at:
          format: date-time
          type: string
        external_id:
          type: string
        deactivated_at:
          format: date-time
          type: string
        calculation_job_type:
          enum:
            - EPC_DOCUMENT_PROCESSING
            - ENERGY_EFFICIENCY_INDICATION
            - SUGGESTED_RENOVATION_TRAJECTORY_CALCULATION
          type: string
        calculation_job_status:
          enum:
            - NOT_STARTED
            - RUNNING
            - FINISHED
            - FAILED
            - STOPPED
          type: string
        metadata:
          type: object
        estate_id:
          type: string
        name:
          type: string
        description:
          type: string
        expires_at:
          format: date-time
          type: string
        published_at:
          format: date-time
          type: string
      required:
        - id
        - created_at
        - updated_at
        - external_id
        - deactivated_at
        - calculation_job_type
        - calculation_job_status
        - metadata
        - estate_id
        - name
        - description
        - expires_at
        - published_at
    UnauthorizedHttpException:
      type: object
      properties:
        statusCode:
          type: number
          example: 401
        error:
          type: string
          example: Unauthorized
      required:
        - statusCode
        - error
    ForbiddenHttpException:
      type: object
      properties:
        statusCode:
          type: number
          example: 403
        error:
          type: string
          example: Forbidden
      required:
        - statusCode
        - error
    NotAcceptableHttpException:
      type: object
      properties:
        statusCode:
          type: number
          example: 406
        message:
          type: object
          example:
            - Name should not be empty.
            - Password must contain at least 1 uppercase character.
        error:
          type: string
          example: Not Acceptable
      required:
        - statusCode
        - message
        - error
    UnprocessableEntityHttpException:
      type: object
      properties:
        statusCode:
          type: number
          example: 422
        message:
          type: object
          example:
            - Roof type FLAT cannot be combined with inclined_roof_pane_surface.
            - Incompatible heating device value for heating type FUEL_OIL.
        error:
          type: string
          example: Unprocessable Entity
      required:
        - statusCode
        - message
        - error
    InternalServerErrorHttpException:
      type: object
      properties:
        statusCode:
          type: number
          example: 500
        error:
          type: string
          example: Internal Server Error
      required:
        - statusCode
        - error
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http

````