API Version:

kelvin API (v3)

Download OpenAPI specification:

Bienvenue dans la documentation de l'API kelvin. Cette API est conçue pour évaluer et améliorer la performance énergétique des propriétés.

API Logo

Aperçu de l'API

L'API kelvin vous permet de créer des simulations pour évaluer la performance énergétique d'un bien immobilier. Elle vous aide également à proposer des plans de travaux personnalisés pour optimiser l'efficacité énergétique de ces biens.

Objectifs Principaux

  • Création de simulations : Lancez des simulations pour obtenir la performance énergétique actuelle d'une propriété.
  • Propositions de travaux : Génération de recommandations de travaux spécifiques pour améliorer l'efficacité énergétique, basées sur les résultats de la simulation.
  • Gestion des DPE : Recherchez et gérez les Diagnostics de Performance Énergétique.

Utilisation de l'iframe de sélection de polygone

Pour créer une simulation, il faut déterminer la latitude, la longitude et l'identifiant d'interopérabilité (ban_id) de la propriété. Une carte interactive est disponible pour faciliter cette tâche: L'iframe de sélection de polygone. Cette carte permet aux utilisateurs de sélectionner visuellement leur propriété sur une carte. Vous pouvez intégrer ce composant dans vos applications en suivant la documentation de l'iframe de sélection de polygone.

Utilisez cette documentation pour explorer les endpoints disponibles, comprendre les paramètres requis, et découvrir comment intégrer efficacement l'API dans votre système.

Changelog v2 → v3

⚠️ Breaking changes

Tous les endpoints ont été migrés de /api/v2/ vers /api/v3/.

Renommage des champs de performance énergétique

dpe_class est renommé energy_rating dans l'état initial et l'état projeté. Trois nouveaux champs obligatoires sont ajoutés :

Avant Après
dpe_class energy_rating
(absent) energy_consumption (kWh/m²/an)
(absent) carbon_rating (lettre GES A–G)
(absent) carbon_emissions (kg CO₂/m²/an)

Champs d'isolation restructurés

Les champs walls_insulation_level, windows_insulation_level, high_floor_insulation_level, low_floor_insulation_level (chaînes de caractères) sont remplacés par des objets contenant un level et une u_value numérique (W/m²K) :

"walls_insulation": { "level": "partially_insulated", "u_value": 0.35 }

Aides financières restructurées

subsidies (montant total unique) est remplacé par un objet financial_support détaillé, disponible à la fois sur chaque plan de rénovation et sur chaque poste de travaux :

"financial_support": { "mpr": 4000.0, "cee": 800.0, "ecoptz": 1200.0, "local": { "Aide région Île-de-France": 1500.0 } }

Structure du plan de rénovation modifiée

Chaque catégorie de travaux dans renovation_plan est désormais un tableau d'items (au lieu d'un objet unique). Chaque item remplace id/simplified_id/label par technical_id et name.

Valeurs d'enum mises à jour

Plusieurs champs ont des valeurs d'enum entièrement révisées pour correspondre au référentiel DPE/ADEME :

  • generator_type / secondary_generator_type : 4 valeurs génériques → 26 valeurs précises (ex. condensing_gas_boiler, air_to_water_heat_pump, pellet_stove) + unknown pour les cas non identifiés
  • hot_water_type : 5 valeurs → 24 valeurs précises (ex. electric_hot_water_tank, thermodynamic_water_tank) + unknown pour les cas non identifiés
  • generator_energy / hot_water_energy / secondary_generator_energy : urban_heating_or_biomassdistrict_heating + biomass_wood + others + unknown
  • wall_material : 5 valeurs → 9 valeurs (ex. lightweight_concrete, hollow_or_perforated_bricks, rammed_or_cob_earth)
  • vents_type : codes renommés (ex. vmc_sf_hygro_bsf_hygro_b_vmc)

windows renommé en doors_windows dans renovation_plan

La catégorie windows couvre désormais fenêtres, portes, portes-fenêtres et fenêtres de toit (18 valeurs de technical_id).

Champs supprimés

  • recently_renovated — supprimé de l'état initial et de l'endpoint de mise à jour du logement
  • has_vents — supprimé (remplacé par le champ vents_type)
  • subsidies — remplacé par l'objet financial_support

✨ Nouveautés

Nouvel endpoint de qualification

PUT /api/v3/simulations/{id}/qualification — Enregistre le profil de qualification de l'utilisateur (statut propriétaire/locataire, taille du foyer, tranche de revenus, département fiscal, maturité du projet). Cet appel doit être effectué avant POST /run.

Nouveaux champs dans l'état initial

  • epc_id — numéro du DPE attaché à la simulation, le cas échéant
  • secondary_generator_type / secondary_generator_energy — système de chauffage secondaire
  • collective_heating / collective_hot_water — indicateurs de systèmes collectifs
  • high_floor_surface, low_floor_surface, windows_surface — surfaces en m²
  • high_floor_kinds / low_floor_kinds — tableaux remplaçant les anciens high_floor_type / low_floor_type
  • sources — indique pour chaque champ si la valeur provient de ai, user ou dpe

Nouvelles catégories de travaux dans renovation_plan

En plus de ventilation, walls, doors_windows, low_floor, high_floor, les catégories suivantes sont désormais retournées : heating, hot_water, renewable_energy, summer_comfort, winter_comfort, thermal_bridge_treatment, lighting, sobriety

Nouveau bloc KPI

Chaque plan de rénovation inclut désormais un objet kpi avec property_value_increase (valorisation immobilière estimée exprimée en pourcentage, en €/m² et en perte de surface m²).

Simulateur

Endpoints disponibles dans l'offre Simulateur

Créer une simulation

Endpoint pour créer une simulation à partir d'un ban_id et des coordonnées GPS.

Authorizations:
bearerAuth
Request Body schema: application/json
latitude
required
number
longitude
required
number
ban_id
string

Responses

Request samples

Content type
application/json
{
  • "latitude": 43.53718,
  • "longitude": 1.337797,
  • "ban_id": "31157_0790_00009"
}

Response samples

Content type
application/json
{
  • "simulation_id": "hjjcm1qp28"
}

Récupérer les informations de la propriété

Les informations de la propriété.

Authorizations:
bearerAuth
path Parameters
simulation_id
required
string
Example: hjjcm1qp28

L'identifiant de simulation renvoyé par l'appel au endpoint créer

Responses

Response samples

Content type
application/json
{
  • "status": "completed",
  • "housing": {
    },
  • "address": {
    }
}

Mettre à jour les informations de la propriété

Endpoint pour mettre à jour les informations de la propriété

Authorizations:
bearerAuth
path Parameters
simulation_id
required
string
Example: hjjcm1qp28

L'identifiant de simulation renvoyé par l'appel au endpoint créer

Request Body schema: application/json
epc_id
string

Le numéro unique du DPE.

housing_type
string
Enum: "house" "apartment"

Le type de propriété.

surface
integer

La surface de la propriété en m2. Obligatoire si le housing_type est apartment.

floor_level
string
Enum: "ground" "intermediate" "last"

La position da le propriété dans l'immeuble. Obligatoire si le housing_type est apartment.

number_of_exterior_wall
integer

Le nombre de murs donnant sur l'extérieur. Obligatoire si le housing_type est apartment.

Responses

Request samples

Content type
application/json
{
  • "epc_id": "2331E2555868X",
  • "housing_type": "apartment",
  • "surface": 100,
  • "floor_level": "ground",
  • "number_of_exterior_wall": 1
}

Response samples

Content type
application/json
{
  • "error": "Housing type is missing or invalid"
}

Qualifier le profil de l'utilisateur

Enregistre les informations de qualification du profil utilisateur.

Authorizations:
bearerAuth
path Parameters
simulation_id
required
string
Example: hjjcm1qp28

L'identifiant de simulation

Request Body schema: application/json
required
profile
required
string
Enum: "owner_resident" "owner_non_resident" "renter" "lessor"

Le profil de l'utilisateur.

primary_residence
boolean

Indique si c'est une résidence principale.

household_size
required
number

Nombre de personnes dans le foyer.

tax_residence_department
string

Département de résidence fiscale.

income_range
required
string
Enum: "very_modest" "modest" "intermediate" "superior"

La tranche de revenus du foyer.

project_maturity
string
Enum: "curious" "searching" "estimated" "signed"

Maturité du projet.

Responses

Request samples

Content type
application/json
{
  • "profile": "owner_resident",
  • "primary_residence": true,
  • "household_size": 4,
  • "tax_residence_department": "75",
  • "income_range": "modest",
  • "project_maturity": "curious"
}

Response samples

Content type
application/json
{
  • "error": "Invalid request parameters"
}

Lancer la simulation

Endpoint pour lancer la simulation.

Authorizations:
bearerAuth
path Parameters
simulation_id
required
string
Example: hjjcm1qp28

L'identifiant de simulation renvoyé par l'appel au endpoint créer

Responses

Response samples

Content type
application/json
{
  • "error": "Unauthorized"
}

Récupérer l'état projeté

Les informations de l'état projeté.

Authorizations:
bearerAuth
path Parameters
simulation_id
required
string
Example: hjjcm1qp28

L'identifiant de simulation renvoyé par l'appel au endpoint créer

Responses

Response samples

Content type
application/json
{
  • "status": "completed",
  • "projected_state": {
    }
}

Qualification

Endpoints disponibles dans l'offre Qualification

Rechercher des DPE par clé d'interopérabilité ou par numéro DPE.

Cet endpoint permet de rechercher des DPE par clé d'interopérabilité ou par numéro de DPE.

Fonctionnalités : Il est obligatoire de fournir au moins un des deux paramètres "ban_id" ou "dpe_id".

  • Recherche par clé d'interopérabilité : Il est possible de rechercher les DPE par la clé d'interopérabilité (ban_id) d'une adresse. Par exemple "31157_0790_00009".
  • Recherche par Numéro de DPE : Il est également possible de rechercher un DPE en utilisant son numéro unique. Cela permet de récupérer rapidement les informations d'un DPE spécifique, par exemple "2331E2555868X".

Filtres : En plus des paramètres principaux, cet endpoint permet d'appliquer des filtres supplémentaires :

  • Surface : Filtrer les DPE en fonction de la surface du bien à 10% près.
  • Date du du diagnostic : Filtrer les DPE selon la date à laquelle ils ont été établis.
  • Classe Énergétique : Filtrer par la classe énergétique du DPE.

Réponse : En cas de succès, l'endpoint retourne une liste de DPE correspondant aux critères de recherche spécifiés.

Authorizations:
bearerAuth
query Parameters
dpe_id
string
Example: dpe_id=2331E2555868X
building_type
string
Enum: "apartment" "house" "building" "unknown"
Example: building_type=house

Le type de bâtiment:

  • apartment
  • house
  • building
  • unknown
ban_id
string
Example: ban_id=31157_0790_00009
surface
number
Example: surface=100
report_date
string
Example: report_date=2024-01-01
energy_class
string
Example: energy_class=E

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Récupérer l'état initial

Les informations de l'état initial.

Authorizations:
bearerAuth
path Parameters
simulation_id
required
string
Example: hjjcm1qp28

L'identifiant de simulation renvoyé par l'appel au endpoint créer

Responses

Response samples

Content type
application/json
{
  • "status": "completed",
  • "initial_state": {
    }
}

Mettre à jour l'état initial

Endpoint pour mettre à jour les informations de l'état initial

Authorizations:
bearerAuth
path Parameters
simulation_id
required
string
Example: hjjcm1qp28

L'identifiant de simulation renvoyé par l'appel au endpoint créer

Request Body schema: application/json
housing_type
string
Enum: "house" "apartment"

Type de logement.

close_to_historical_monument
boolean

Proximité d'un monument historique.

floor_level
string
Enum: "ground" "intermediate" "last"

Niveau de l'étage (rez-de-chaussée, intermédiaire, dernier étage).

living_area
number

La surface habitable en mètres carrés.

number_of_exterior_wall
integer

Nombre de murs extérieurs.

house_number_of_levels
integer

Le nombre de niveaux dans la maison.

shared_walls
boolean

Présence de murs mitoyens.

object

L'année de construction du bâtiment.

wall_material
string
Enum: "lightweight_concrete" "insulating_concrete" "stone" "brick" "hollow_or_perforated_bricks" "wood" "wood_with_insulating_infill" "rammed_or_cob_earth" "traditional_old_material" "others"

Le matériau principal des murs.

high_floor_kinds
Array of strings
Items Enum: "apartment" "converted_attic" "lost_attic" "not_heated_space" "office" "roof_terrace" "unknown"

Les types de plancher haut.

low_floor_kinds
Array of strings
Items Enum: "apartment" "crawl_space" "not_heated_space" "office" "slab_on_grade" "underground_garage" "unknown"

Les types de plancher bas.

windows
string
Enum: "high_class" "middle_class" "low_class"

Le type de fenêtre.

number_of_windows
integer

Le nombre total de fenêtres.

generator_energy
string
Enum: "electricity" "fuel" "gas" "biomass_wood" "district_heating" "others"

Le type d'énergie utilisé par le générateur de chauffage.

generator_type
string
Enum: "air_to_air_heat_pump" "air_to_water_heat_pump" "classic_gas_boiler" "closed_fireplace_insert" "coal_boiler" "condensing_gas_boiler" "electric_boiler_or_underfloor_heating" "electric_convector_heater" "electric_radiator" "fossil_fueled_district_heating_network" "fuel_boiler" "fuel_stove" "geothermal_heat_pump" "hybrid_heat_pump" "insulated_district_heating_network" "lpg_propane_butane_boiler_with_external_tank" "low_temperature_gas_boiler" "misc_system" "other_gas_generators" "pellet_boiler" "pellet_stove" "radiant_panel_heater" "standard_gas_boiler" "uninsulated_district_heating_network" "wood_boiler" "wood_stove"

Le type de générateur de chauffage.

secondary_generator_energy
string
Enum: "electricity" "fuel" "gas" "biomass_wood" "district_heating" "others"

Le type d'énergie utilisé par le chauffage secondaire.

secondary_generator_type
string
Enum: "air_to_air_heat_pump" "air_to_water_heat_pump" "classic_gas_boiler" "closed_fireplace_insert" "coal_boiler" "condensing_gas_boiler" "electric_boiler_or_underfloor_heating" "electric_convector_heater" "electric_radiator" "fossil_fueled_district_heating_network" "fuel_boiler" "fuel_stove" "geothermal_heat_pump" "hybrid_heat_pump" "insulated_district_heating_network" "lpg_propane_butane_boiler_with_external_tank" "low_temperature_gas_boiler" "misc_system" "other_gas_generators" "pellet_boiler" "pellet_stove" "radiant_panel_heater" "standard_gas_boiler" "uninsulated_district_heating_network" "wood_boiler" "wood_stove"

Le type de générateur de chauffage secondaire.

hot_water_energy
string
Enum: "electricity" "fuel" "gas" "biomass_wood" "district_heating" "others"

Le type d'énergie utilisé pour l'eau chaude sanitaire.

hot_water_type
string
Enum: "air_to_water_heat_pump" "classic_gas_boiler" "coal_boiler" "condensing_gas_boiler" "electric_boiler" "electric_hot_water_tank" "electric_water_heater" "fossil_fueled_district_heating_network" "fuel_boiler" "gas_water_tank" "geothermal_heat_pump" "hybrid_heat_pump" "insulated_district_heating_network" "instant_gas_water_heater" "instant_lpg_propane_butane_water_heater" "lpg_propane_butane_boiler_external_tank" "lpg_propane_butane_storage_hot_water_tank" "low_temperature_gas_boiler" "other_gas_generators" "pellet_boiler" "standard_gas_boiler" "thermodynamic_water_tank" "uninsulated_district_heating_network" "wood_boiler"

Le type de système de production d'eau chaude sanitaire.

vents_type
string
Enum: "window_opening_ventilation" "high_low_air_inlet_ventilation" "natural_ventilation_duct" "mechanical_ventilation_existing_duct" "sf_self_regulating_vmc" "sf_hygro_a_vmc" "sf_hygro_b_vmc" "sf_gas_vmc" "low_pressure_vmc" "hybrid_ventilation" "individual_df_vmc" "collective_df_vmc" "climatic_well"

Le type de ventilation.

garage
boolean

Présence d'un garage.

collective_heating
boolean

Chauffage collectif.

collective_hot_water
boolean

Eau chaude sanitaire collective.

walls_insulation_level
string
Enum: "no_insulation" "partially_insulated" "moderately_insulated" "well_insulated"

Le niveau d'isolation des murs.

high_floor_insulation_level
string
Enum: "no_insulation" "partially_insulated" "moderately_insulated" "well_insulated"

Le niveau d'isolation du plancher haut.

low_floor_insulation_level
string
Enum: "no_insulation" "partially_insulated" "moderately_insulated" "well_insulated"

Le niveau d'isolation du plancher bas.

high_floor_surface
integer

La surface du plancher haut en mètres carrés.

low_floor_surface
integer

La surface du plancher bas en mètres carrés.

exterior_walls_surface
integer

La surface extérieure des murs en mètres carrés.

windows_surface
integer

La surface totale des fenêtres en mètres carrés.

Responses

Request samples

Content type
application/json
{
  • "housing_type": "apartment",
  • "close_to_historical_monument": true,
  • "floor_level": "ground",
  • "living_area": 120,
  • "number_of_exterior_wall": 3,
  • "house_number_of_levels": 1,
  • "shared_walls": true,
  • "construction_year": {
    },
  • "wall_material": "brick",
  • "high_floor_kinds": [
    ],
  • "low_floor_kinds": [
    ],
  • "windows": "middle_class",
  • "number_of_windows": 8,
  • "generator_energy": "gas",
  • "generator_type": "condensing_gas_boiler",
  • "secondary_generator_energy": "gas",
  • "secondary_generator_type": "condensing_gas_boiler",
  • "hot_water_energy": "electricity",
  • "hot_water_type": "electric_hot_water_tank",
  • "vents_type": "sf_self_regulating_vmc",
  • "garage": false,
  • "collective_heating": false,
  • "collective_hot_water": false,
  • "walls_insulation_level": "partially_insulated",
  • "high_floor_insulation_level": "partially_insulated",
  • "low_floor_insulation_level": "partially_insulated",
  • "high_floor_surface": 60,
  • "low_floor_surface": 60,
  • "exterior_walls_surface": 85,
  • "windows_surface": 10
}

Response samples

Content type
application/json
{
  • "error": "Generator type n'est pas valide"
}

Créer un plan de rénovation personnalisé

Crée un plan de rénovation basé sur une sélection spécifique de gestes. L'opération est asynchrone : l'API retourne immédiatement une réponse confirmant la création, mais le plan complet n'est pas disponible dans l'instant. Pour consulter le plan généré une fois le traitement terminé, utilisez le endpoint 'Récupérer le plan de rénovation personnalisé'.

Authorizations:
bearerAuth
path Parameters
simulation_id
required
string
Example: hjjcm1qp28

L'identifiant de simulation renvoyé par l'appel au endpoint créer

Request Body schema: application/json
required
name
string

Le nom du plan de rénovation personnalisé.

required
object

Responses

Request samples

Content type
application/json
{
  • "name": "Mon plan personnalisé",
  • "renovation_plan": {
    }
}

Response samples

Content type
application/json
{
  • "renovation_plan_id": "hjjcm1qp28"
}

Récupérer le plan de rénovation personnalisé

Les informations du plan de rénovation personnalisé.

Authorizations:
bearerAuth
path Parameters
simulation_id
required
string
Example: hjjcm1qp28

L'identifiant de simulation renvoyé par l'appel au endpoint créer

renovation_plan_id
required
string
Example: hjjcm1qp28

L'identifiant du plan de rénovation personnalisé.

Responses

Response samples

Content type
application/json
{
  • "status": "completed",
  • "id": "hjjcm1qp28",
  • "name": "Mon plan personnalisé",
  • "type": "customized",
  • "energy_rating": "B",
  • "energy_consumption": 201,
  • "carbon_rating": "C",
  • "carbon_emissions": 40,
  • "yearly_energy_savings": 600,
  • "yearly_energy_cost": 12000,
  • "budget": 400,
  • "financial_support": {
    },
  • "kpi": {
    },
  • "renovation_plan": {
    }
}

Lancer la génération du rapport PDF

Endpoint pour démarrer la génération asynchrone du rapport PDF de la simulation. Le rapport peut optionnellement inclure les informations du client.

Authorizations:
bearerAuth
path Parameters
simulation_id
required
string
Example: hjjcm1qp28

L'identifiant de simulation renvoyé par l'appel au endpoint créer

Request Body schema: application/json
object

Les informations du client (nom, prénom, email, téléphone)

Responses

Request samples

Content type
application/json
{
  • "client": {
    }
}

Response samples

Content type
application/json
{
  • "error": "Unauthorized"
}

Récupérer le statut du rapport PDF

Le statut de la génération du rapport PDF et l'URL de téléchargement.

Authorizations:
bearerAuth
path Parameters
simulation_id
required
string
Example: hjjcm1qp28

L'identifiant de simulation renvoyé par l'appel au endpoint créer

Responses

Response samples

Content type
application/json

Lister les simulations

Endpoint pour lister les simulations.

Authorizations:
bearerAuth
query Parameters
status
string
Value: "with_contact_details"
Example: status=with_contact_details

Filtrer les simulations avec des informations de contact:

  • with_contact_details
page
integer
Example: page=1

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}