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 :

{
  "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, 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/<identifiant>?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/<identifiant>?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
`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
`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 :

<link rel="alternate" type="application/json" href="…?format=json">

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. Ils ne remplacent pas une étude sur place.