Quick Start

Première requête en moins de 5 minutes. Score composite, intensité carbone ou historique — tu choisis.

// démo publique — sans compte

3/min · 10/mois par IP 
$ curl -H "X-Api-Key: wm_demo" https://api.wattmind.fr/v1/score

Réponse JSON identique à un vrai appel B2B. Idéal pour vérifier que ça marche avant signup. Au-delà des 10 calls/mois OU pour tester avec tes propres paramètres (?profile=ev-charging, historique CSRD, custom weights) → crée ton compte Starter (gratuit, 10 req/min · 3 000/mois, sans carte bancaire).

🔑

Authentification (en production)

Toutes les requêtes B2B nécessitent le header X-Api-Key avec ta clé personnelle (préfixée wm_).

X-Api-Key: wm_abcdef0123456789abcdef0123456789
1

Obtenir une clé API

Crée un compte (Starter gratuit, pas de CB). Tu retrouveras tes clés dans ton dashboard.

Une clé créée n'est affichée en entier qu'une seule fois : copie-la immédiatement.

2

Première requête

Choisis ton langage. Remplace YOUR_API_KEY par ta vraie clé.

curl

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://api.wattmind.fr/v1/score"

Python

import requests

response = requests.get(
    "https://api.wattmind.fr/v1/score",
    headers={"X-Api-Key": "YOUR_API_KEY"}
)
score = response.json()
print(f"Score: {score['globalScore']}/100 - {score['level']}")

JavaScript / Node

const res = await fetch(
  "https://api.wattmind.fr/v1/score",
  { headers: { "X-Api-Key": "YOUR_API_KEY" } }
);
const score = await res.json();
console.log(`Score: ${score.globalScore}/100 - ${score.level}`);

C# / .NET

var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Api-Key", "YOUR_API_KEY");

var score = await client.GetFromJsonAsync<JsonElement>(
    "https://api.wattmind.fr/v1/score");

Console.WriteLine($"Score: {score.GetProperty("globalScore")}/100");

Autre endpoint populaire : /carbon/intensity

Idéal pour CSRD scope 2 / BEGES — retourne le mix production par filière et le facteur d'émission en gCO₂eq/kWh (facteurs ADEME Base Carbone®, synchronisés, licence Etalab).

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://api.wattmind.fr/v1/carbon/intensity"
3

Comprendre la réponse

Champ Type Description
globalScoreintScore composite 0-100 (plus haut = meilleur moment pour consommer)
levelstringOptimal / Acceptable / Unfavorable
recommendationstringRecommandation en français, prête à afficher
subScoresarrayListe de { dimension, value, detail }. Dimensions : price, carbon, grid, adequacy.
confidenceintIndice de confiance 0-100 (baisse si une source est partiellement indisponible)
statusstringok / degraded / unavailable selon la disponibilité des sources
weightsAppliedobjectPondérations utilisées (variable selon ?profile= ou ?wCarbon=…)
profileAppliedstringProfil métier appliqué (balanced par défaut, eco, cost, …)
computedAtdatetimeTimestamp UTC du calcul

Exemples de réponses complètes

Payloads réels fidèles aux DTOs — deux endpoints phares, deux cas d'usage concrets.

/v1/carbon/intensity — CSRD scope 2

GET /v1/carbon/intensity
X-Api-Key: wm_... 
{
  "timestamp": "2026-04-23T10:30:00Z",
  "totalGenerationMW": 58215,
  "lowCarbonPct": 95.4,
  "renewablePct": 19.2,
  "estimatedGCo2PerKwh": 21,
  "mix": [
    { "productionType": "NUCLEAR",
      "valueMW": 42781, "sharePct": 73.5,
      "isLowCarbon": true },
    { "productionType": "WIND_ONSHORE",
      "valueMW": 3301, "sharePct": 5.7,
      "isLowCarbon": true },
    { "productionType": "FOSSIL_GAS",
      "valueMW": 2296, "sharePct": 3.9,
      "isLowCarbon": false }
  ],
  "methodology": "real_time_generation_weighted",
  "emissionFactorsSource": {
    "source": "ADEME Base Carbone®",
    "license": "Etalab 2.0",
    "mostRecentAdemeModification": "2023-08-23"
  }
}

Facteurs d'émission ADEME Base Carbone® (synchronisés, licence Etalab). Idéal pour reporting scope 2 market-based horaire.

/v1/score — score composite

GET /v1/score
X-Api-Key: wm_... 
{
  "computedAt": "2026-04-23T10:30:00Z",
  "globalScore": 78,
  "level": "Optimal",
  "recommendation": "Moment favorable : mix
    décarboné à 95%, prix spot 42 €/MWh.",
  "subScores": [
    { "dimension": "price",    "value": 72,
      "detail": "Spot 42 €/MWh (médiane 58)" },
    { "dimension": "carbon",   "value": 88,
      "detail": "27 gCO₂eq/kWh, 95% bas-carbone" },
    { "dimension": "grid",     "value": 85,
      "detail": "Ecowatt vert" },
    { "dimension": "adequacy", "value": 70,
      "detail": "Marge 8 GW" }
  ],
  "confidence": 92,
  "status": "ok",
  "weightsApplied": {
    "price": 0.30, "carbon": 0.30,
    "grid": 0.20, "adequacy": 0.20
  },
  "profileApplied": "balanced"
}

4 dimensions pondérées. Pondérations personnalisables via ?profile= ou ?wCarbon=….

4

Rate limits & erreurs

Chaque réponse inclut des headers qui te disent où tu en es :

X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 58
X-RateLimit-Limit-Month: 30000
X-RateLimit-Remaining-Month: 29842

En cas de dépassement minute (tous plans), tu reçois un 429 avec un header Retry-After. Sur les plans Pro et Scale, le dépassement mensuel est facturé en overage metered (pas de 429).

La clé démo publique wm_demo a ses propres limites par IP : 3 req/min · 10 req/mois. Au-delà, le 429 inclut un upgradeUrl vers la page de signup Starter (gratuit, 10 req/min · 3 000/mois).

Format des erreurs

{
  "status": 401,
  "error": "Unauthorized",
  "traceId": "0HN5..."
}

Pour aller plus loin