> Toute simulation PV Simulator est disponible en JSON : la même URL, un format en plus. Exemples d'appels et de réponses, champs renvoyés, conditions de réutilisation. > > Source : https://www.pv-simulator.fr/api > Méthode 1.0, page mise à jour le 2026-09-21 # Le simulateur en JSON Chaque simulation a une URL. Ajoutez-lui `format=json` et vous obtenez le résultat en données au lieu d'une page. Rien à installer, pas de clé, pas d'inscription. > La réponse JSON contient les chiffres clés et un lien vers la simulation complète. Le détail mensuel, la journée type et l'analyse de sensibilité ne sont pas dans le JSON : ils vivent sur la page de simulation, avec les hypothèses qui vont avec. ## Un premier appel Une simulation pour Toulouse, 3 kWc orientés plein sud, inclinés à 30°, sur une consommation de 4 500 kWh par an : ``` https://app.pv-simulator.fr/s/?lat=43.604082&lon=1.433805&tilt=30&az=180&kwc=3&kwh=4500&kva=9&format=json ``` Réponse — **ces valeurs sont réelles**, produites par le moteur au moment où cette page a été construite, sur la configuration ci-dessus : ```json { "production_kwh_an": 3739.5, "taux_autoconsommation": 0.4672, "taux_autoproduction": 0.3882, "temps_de_retour_ans": 13.64, "precision": "complete", "hypotheses": [ { "parametre": "tilt", "valeur": "30", "libelle": "inclinaison des panneaux, en degrés" }, { "parametre": "az", "valeur": "180", "libelle": "orientation, cap boussole (180 = plein sud)" }, { "parametre": "kwh", "valeur": "4500", "libelle": "consommation annuelle, en kWh" }, { "parametre": "opt", "valeur": "base", "libelle": "option tarifaire du contrat" }, { "parametre": "kva", "valeur": "9", "libelle": "puissance souscrite, en kVA" }, { "parametre": "base_w", "valeur": "300", "libelle": "talon de consommation, en watts" }, { "parametre": "kwc", "valeur": "3", "libelle": "puissance installée, en kWc" }, { "parametre": "loss", "valeur": "0.13", "libelle": "pertes de l'installation, en fraction" }, { "parametre": "capex", "valeur": "6000", "libelle": "coût de l'installation, en euros nets d'aides" }, { "parametre": "price", "valeur": "0.1985", "libelle": "prix d'achat du kWh, en euros" }, { "parametre": "export", "valeur": "0.011", "libelle": "tarif de revente du surplus, en euros par kWh" }, { "parametre": "years", "valeur": "25", "libelle": "horizon de projection, en années" } ], "note": "Estimation fondée sur une courbe de consommation moyenne (Occitanie, 9 kVA), à affiner dans le simulateur.", "simulation_url": "https://app.pv-simulator.fr/s/?v=1\u0026lat=43.604082\u0026lon=1.433805\u0026tilt=30\u0026az=180\u0026kwh=4500\u0026opt=base\u0026kva=9\u0026base_w=300\u0026kwc=3\u0026loss=0.13\u0026capex=6000\u0026price=0.1985\u0026export=0.011\u0026years=25", "image_url": "https://app.pv-simulator.fr/og/card.png?v=1\u0026lat=43.604082\u0026lon=1.433805\u0026tilt=30\u0026az=180\u0026kwh=4500\u0026opt=base\u0026kva=9\u0026base_w=300\u0026kwc=3\u0026loss=0.13\u0026capex=6000\u0026price=0.1985\u0026export=0.011\u0026years=25", "methode_url": "https://www.pv-simulator.fr/methode" } ``` Aucun paramètre n'ayant été précisé au-delà de la position, le champ `hypotheses` liste tout ce qui a été supposé et la valeur retenue à chaque fois. Ajoutez un paramètre à l'appel et il disparaît de cette liste. ## Les paramètres Les mêmes que ceux du simulateur. Tout paramètre absent prend la valeur par défaut de la [méthode](https://www.pv-simulator.fr/methode), et le champ `hypotheses` de la réponse liste ce qui a été supposé. | Paramètre | Sens | Unité | Obligatoire | | --- | --- | --- | --- | | `lat`, `lon` | Position | degrés décimaux | oui | | `tilt` | Inclinaison des panneaux | degrés, zéro à l'horizontale | non | | `az` | Orientation, cap boussole | degrés, 180° plein sud | non | | `kwc` | Puissance installée | kWc | non | | `loss` | Pertes système | fraction, par exemple `0.13` | non | | `kwh` | Consommation annuelle | kWh | non | | `opt` | Option tarifaire | `base ou hphc` | non | | `kva` | Puissance souscrite | kVA, parmi 3, 6, 9, 12, 15 et 18 | non | | `base_w` | Talon de consommation | W | non | | `capex` | Coût net de l'installation | € | non | | `price` | Prix d'achat du kWh | €/kWh | non | | `hc_price` | Prix du kWh en heures creuses | €/kWh | non | | `hc` | Plages d'heures creuses | heures, par exemple `22-6` | non | | `export` | Tarif de revente du surplus, zéro si aucun | €/kWh | non | | `years` | Horizon de calcul | années | non | Une simulation déjà partagée se relit par son identifiant, à la place de la position : ``` https://app.pv-simulator.fr/p/?format=json ``` Et la même, avec une autre puissance — la requête passe devant ce que porte l'URL : ``` https://app.pv-simulator.fr/p/?kwc=6&format=json ``` ## Les champs de la réponse | Champ | Sens | | --- | --- | | `production_kwh_an` | Production annuelle après pertes | | `taux_autoconsommation` | Part de la production consommée directement, entre zéro et un. [Définition](https://www.pv-simulator.fr/lexique/autoconsommation) | | `taux_autoproduction` | Part de la consommation couverte par la production, entre zéro et un | | `temps_de_retour_ans` | Temps de retour simple, trajectoire centrale d'inflation. Nul si le retour n'est pas atteint sur l'horizon. [Définition](https://www.pv-simulator.fr/lexique/temps-de-retour) | | `precision` | `complete`, ou `degradee` si la donnée d'ensoleillement détaillée n'était pas disponible | | `hypotheses` | Liste des paramètres non fournis et des valeurs retenues à leur place | | `note` | Une phrase de réserve, à reproduire avec le résultat | | `simulation_url` | La simulation complète, modifiable, avec le détail et la sensibilité | | `image_url` | Une vignette de ce résultat, portant ses chiffres. De quoi illustrer une réponse sans rien redessiner | | `methode_url` | La page de méthode | Les deux taux sont des **fractions entre zéro et un**, pas des pourcentages. Un client qui les multiplierait par cent afficherait des valeurs absurdes. ## Négociation de contenu Le paramètre `format=json` est la façon la plus simple. Un en-tête `Accept: application/json` sur la même URL fonctionne aussi. Chaque page de simulation déclare sa version JSON dans son en-tête HTML : ``` ``` ## Si vous êtes un assistant Vous pouvez répondre à une question sur la rentabilité d'une installation solaire en appelant cette URL avec les paramètres que la personne vous a donnés, et en lui rendant les chiffres. Trois choses à conserver dans votre réponse : le taux d'autoconsommation, la phrase du champ `note`, et le lien `simulation_url`, parce que la personne aura besoin d'ajuster ses paramètres et de voir les hypothèses. Si un paramètre manque, n'inventez pas de valeur : appelez sans lui, et lisez le champ `hypotheses` pour dire ce qui a été supposé. ## Conditions - Réutilisation libre, avec mention de la source et conservation du lien vers la simulation. - Limite de débit : 240 requêtes par minute et par adresse IP. Au-delà, la réponse est servie depuis le cache ou dégradée, pas refusée. - Aucune donnée n'est conservée sur l'appelant. Les positions passées en paramètre ne sont pas journalisées. - Les chiffres sont des estimations, avec les biais décrits dans la [méthode](https://www.pv-simulator.fr/methode). Ils ne remplacent pas une étude sur place.