Create new Suggested Renovation Trajectory Calculation Job

Creates a new calculation job for suggested renovation trajectory calculations.

1. Introduction

The Suggested Renovation Trajectory Calculation API enables users to generate a renovation plan for properties, especially when limited details are available. This API enriches the provided data using external sources and predictive models to return a comprehensive renovation trajectory.

---

2. Process Overview

The API follows these steps:

1. Data Enrichment: Enhances incoming property data with additional information from external platforms like Belmap, which provides detailed property measurements using LiDAR datasets.

2. Prediction Modeling: Utilizes a machine learning model to predict missing property attributes and assess energy performance.

3. Renovation Trajectory Generation: Generates a suggested renovation plan based on enriched data and model predictions, prioritizing actions that maximize energy efficiency improvements.

---

3. Business Logic & Data Enrichment

3.1 Belmap Data Enrichment

The API integrates with Belmap, a platform that provides accurate property measurements using LiDAR datasets. If certain data points are missing (e.g., roof area, building width, depth), the API queries Belmap to retrieve them.

3.2 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.2.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 Belmap data is available, the expected confidence score is ~78%.
• Lower scores indicate the API made more assumptions due to missing data.

3.3 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

For example:

• If both roof insulation and full roof renovation yield the same EPC gain, the system chooses insulation since it is cheaper.

---

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.

Response Example (Completed Calculation)

{
    "id": "008135aa-448f-48bc-8c31-9bf23601488b",
    "created_at": "2025-02-27T13:51:50.299Z",
    "updated_at": "2025-02-27T13:52:48.751Z",
    "external_id": null,
    "calculation_job_type": "SUGGESTED_RENOVATION_TRAJECTORY_CALCULATION",
    "calculation_job_status": "FINISHED",
    "metadata": {
        "output": {
            "steps": [
                {
                    "type": "ROOF",
                    "items": [
                        {
                            "renovation_component_type": "ROOF_INSULATION",
                            "estimated_cost": 7950,
                            "subsidy_amount": 3976,
                            "estimated_vat_cost": 477,
                            "calculation_attributes": {
                                "ROOF_PANE_SURFACE": {
                                    "value": 158.99586
                                }
                            },
                            "energy_efficiency_indication": {
                                "score": 424,
                                "label": "E"
                            }
                        }
                    ],
                    "priority": 1
                },
                {
                    "type": "OUTSIDE_WALLS",
                    "items": [
                        {
                            "renovation_component_type": "CAVITY_WALL_REFILL",
                            "estimated_cost": 2150,
                            "subsidy_amount": 1075,
                            "estimated_vat_cost": 129,
                            "calculation_attributes": {
                                "FACADE_WIDTH": { "value": 7.22 },
                                "CORNICE_HEIGHT": { "value": 3.18 },
                                "CONSTRUCTION_DEPTH": { "value": 19.34 }
                            },
                            "energy_efficiency_indication": {
                                "score": 210,
                                "label": "C"
                            }
                        }
                    ],
                    "priority": 2
                },
                {
                    "type": "FLOOR",
                    "items": [
                        {
                            "renovation_component_type": "GROUND_FLOOR_INSULATION",
                            "estimated_cost": 5942,
                            "subsidy_amount": 1500,
                            "estimated_vat_cost": 357,
                            "calculation_attributes": {
                                "GROUND_FLOOR_SURFACE": { "value": 139.81 }
                            },
                            "energy_efficiency_indication": {
                                "score": 185,
                                "label": "B"
                            }
                        }
                    ],
                    "priority": 3
                },
                {
                    "type": "OUTSIDE_JOINERY",
                    "items": [
                        {
                            "renovation_component_type": "GLASS_REPLACEMENT",
                            "estimated_cost": 4200,
                            "subsidy_amount": 2100,
                            "estimated_vat_cost": 252,
                            "calculation_attributes": {
                                "SURFACE": { "value": 30 }
                            },
                            "energy_efficiency_indication": {
                                "score": 161,
                                "label": "B"
                            }
                        }
                    ],
                    "priority": 4
                },
                {
                    "type": "TECHNICAL_INSTALLATIONS",
                    "items": [
                        {
                            "renovation_component_type": "HEATING_SANITARY_FULL_ECO",
                            "estimated_cost": 22577,
                            "subsidy_amount": 3250,
                            "estimated_vat_cost": 1354,
                            "calculation_attributes": {
                                "HEATING_TYPE": { "value": "FUEL_OIL" },
                                "GROUND_FLOOR_SURFACE": { "value": 139.81 },
                                "RENOVATION_COMPONENT_TYPE": { "value": "HEATING_SANITARY_FULL_ECO" }
                            },
                            "energy_efficiency_indication": {
                                "score": 107,
                                "label": "B"
                            }
                        }
                    ],
                    "priority": 5
                }
            ],
            "summary": {
                "step_count": 5,
                "estimated_cost": 42819,
                "subsidy_amount": 11901,
                "confidence_score": 0.788,
                "estimated_vat_cost": 2569,
                "energy_efficiency_indication": {
                    "score": 107,
                    "label": "B"
                }
            }
        }
    }
}

---

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 data.

Can I speed up the calculation process?

• No, the processing time depends on background jobs and external data sources.

---

Final Notes

• This API is particularly useful for real estate developers and homeowners looking for an automated, data-enriched renovation trajectory.
• The integration of LiDAR (Belmap) and ML predictions ensures optimal recommendations based on available data.
• Users are encouraged to cross-check low-confidence results with additional manual data input to improve accuracy.

Assistant

Responses are generated using AI and may contain mistakes.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Body with required input data.

The body is of type object.

Response

200

application/json

Successfully processed request.

The response is of type object.