API · Kuma Data Core

Des données d'énergie éditorialisées localement

Une API REST qui expose une vingtaine de grandeurs énergétiques et climatiques pour les six communes pilotes guinéennes (2021-2025). Substrat NASA POWER + cross-check PVGIS-SARAH-3 + dérivés Kuma selon les normes IEC/WMO. Irradiation, température, productibles photovoltaïques, degrés-jours. Chaque donnée tracée, datée, versionnée.

Requête

GET /v1/series?localite=gin_kindia&grandeur=ghi Authorization: Bearer <cle>
Réponse 200
{
"items": [
{
"code": "gin_kindia_ghi_nasa_power_2021_2025", "libelle": "GHI journalier Kindia 2021-2025 (NASA
      POWER)", "grandeur_code": "ghi", "grandeur_unit": "kWh/m²/jour", "source_label": "NASA POWER", "periode_debut":
      "2021-01-01", "periode_fin": "2025-12-31"
}
], "total": 1
}

· Pourquoi cette API

Une seule référence pour toutes les séries

L'API Kuma Data Core est le socle qui alimente l'ensemble de l'écosystème : le média éditorial qui publie articles et fiches, les outils logiciels comme Solar Bridge qui dimensionnent les projets, et les intégrations tierces des bureaux d'études partenaires. Une seule API, un seul contrat, une seule référence pour toutes les séries.

Elle agrège deux sources publiques de référence (NASA POWER, substrat primaire satellite/réanalyse, et PVGIS-SARAH-3, cross-check mensuel GHI) et les éditorialise selon une doctrine de qualité rigoureuse : trois couches de sources A/B/C, trois niveaux de confiance, cinq statuts éditoriaux, des conventions méthodologiques internationales (IEC, WMO) appliquées. La calibration terrain (stations ANM Guinée pour la future couche A) est un objectif de feuille de route, pas un acquis. La donnée du substrat reste accessible ; la donnée éditorialisée est documentée.

Chaque série pointe vers sa source originelle, porte son niveau de confiance, et vit dans le temps de façon non destructive. Les corrections de méthode ne réécrivent pas le passé : elles créent de nouvelles versions avec leur période de validité. La traçabilité est intégrée à la conception de l'API.

· Le catalogue des grandeurs

Une vingtaine de grandeurs, quatre familles

Chaque grandeur est soit brute (ingérée d'une source publique), soit calculée par Kuma selon une méthode documentée. Les codes courts (ghi, kt, hep…) sont stables et servent à filtrer le catalogue.

· Famille 01

Grandeurs brutes

Données importées telles quelles depuis NASA POWER. Mesurées par modèles satellitaires, stockées au pas journalier. Aucune transformation Kuma : la donnée brute reste accessible pour traçabilité.

Code Libellé Unité Source · Méthode amont
ghi Irradiation globale horizontale kWh/m²/jour NASA POWER · CERES SYN1deg + FLASHFlux
dni Irradiation normale directe kWh/m²/jour NASA POWER · CERES SYN1deg
dhi Irradiation diffuse horizontale kWh/m²/jour NASA POWER · CERES SYN1deg + FLASHFlux
t2m Température à 2 m °C NASA POWER · MERRA-2 GMAO
rh2m Humidité relative à 2 m % NASA POWER · MERRA-2 GMAO
kt Indice de clarté sans dimension NASA POWER · CERES SYN1deg + FLASHFlux

· Famille 02

Grandeurs calculées par Kuma

Grandeurs dérivées des données brutes selon des conventions méthodologiques documentées. Persistées en base, publiables, citables. Chaque formule est versionnée : toute évolution crée une nouvelle version avec sa période de validité.

Code Libellé Unité Méthode de calcul
hep Heures équivalentes pleines h équivalentes Agrégation cumulative de GHI (1 kWh/m²/j ↔ 1 h_eq à 1 kW/m² STC)
fraction_diffuse Fraction diffuse sans dimension Σ DHI / Σ GHI sur la période
humidex Indice de confort Humidex °C apparents Masterton & Richardson 1979 (T2M + RH2M)
productible_specifique_theorique Productible spécifique théorique kWh/kWc HEP × PR théorique (0,8 conservateur)
variabilite_journaliere Coefficient de variation journalier sans dimension σ(GHI_jour) / μ(GHI_jour) annuel
indicateur_qualite_donnees Score qualité de série 1 à 5 0,5 · complétude + 0,3 · confiance + 0,2 · fiabilité source

· Famille 03

Grandeurs référentielles

Positionnent une série par rapport à des référentiels temporels (climatologie 30 ans) ou spatiaux (les six villes pilotes du programme). Calculées à la volée pour rester synchronisées avec l'état courant du catalogue.

Code Libellé Méthode
ecart_relatif_referentiel Écart relatif à un référentiel Écart d'une série mensuelle à SARAH-3 2021-2023 ou à la climatologie 1991-2020 par mois
rang_referentiel_temporel Rang dans la climatologie 1991-2020 Percentile d'une valeur mensuelle dans la distribution 30 ans du même mois
rang_referentiel_spatial Rang spatial 1 à 6 Position dans le pool des six villes pilotes pour le même mois

· Famille 04

Grandeurs paramétrables

Calculées en temps réel selon les paramètres fournis (inclinaison, orientation, albédo, coefficients thermiques, etc.) sur des modèles physiques de référence. C'est la couche la plus souple de l'API : un utilisateur peut simuler son installation sans réécrire les équations.

Code Libellé Unité Modèle physique de référence
poa_parametrable Irradiation dans le plan des modules kWh/m²/jour Perez 1990, fallback Liu-Jordan / Erbs 1982
productible_correction_thermique Productible avec correction thermique kWh/kWc/jour NOCT (Ross 1980)
productible_pr_fourni Productible avec PR fourni kWh/kWc/jour PR (Marion 2005) ou PR_T (Dierauf 2013)
energie_utile_ecs Énergie utile eau chaude solaire kWh/m²/jour Hottel-Whillier-Bliss 1958
degre_jour_climatisation Degrés-jours de climatisation °C·j ISO 15927-6

Exemple d'usage paramétrable : calcul de l'irradiation dans le plan des modules sur une série existante avec inclinaison 20° plein sud.

Requête

GET /v1/grandeurs/poa_parametrable ?code_serie_source=gin_conakry_ghi_nasa_power_2021_2025
        &periode_debut=2024-01-01&periode_fin=2024-12-31
        &inclinaison_deg=20&orientation_deg=180&albedo_sol=0.2 Authorization: Bearer <cle>

· La doctrine de qualité

Chaque donnée porte sa confiance

Quatre disciplines structurent l'éditorialisation de la donnée chez Kuma. Elles sont stables, documentées, et appliquées à chaque série au moment de sa publication.

01

Trois couches de sources

  • A

    Calibration terrain · roadmap

    Mesures sol locales (ANM Guinée). Objectif de feuille de route, aucune série en couche A aujourd'hui. Affirmer la couche vide est volontaire, c'est ce qui rend la doctrine crédible.

  • B

    Substrat modélisé + cross-check

    Sources satellite/réanalyse opérationnelles : NASA POWER (substrat primaire) et PVGIS-SARAH-3 (cross-check mensuel GHI).

  • C

    Post-traitement éditorial

    Dérivés Kuma et conventions méthodologiques internationales (IEC 61724-1, WMO-No.8) appliquées par Kuma sur la donnée du substrat. Couche transformée, documentée, versionnée.

02

Trois niveaux de confiance

Attribués à chaque mesure individuellement, indépendamment de la couche source. Un niveau effectif est calculé pour chaque série. Phase 1 : niveaux B (substrat) ou C (dérivé).

  • A

    Haute confiance · réservée mesure terrain

    Réservée à la mesure directe (couche A terrain). Aucune mesure n'est en confiance A aujourd'hui. Le niveau remontera à l'arrivée d'une calibration terrain effective.

  • B

    Confiance moyenne · niveau dominant

    Substrat modélisé satellite/réanalyse (NASA POWER, PVGIS-SARAH-3).

  • C

    Confiance basse

    Calcul dérivé ou source de fiabilité moyenne.

03

Cinq statuts éditoriaux

Workflow de validation appliqué à chaque série, de l'ingestion à la publication ou la dépréciation.

  1. brut : ingestion initiale, non validé
  2. valide_auto : checks automatiques passés
  3. valide_humain : relu et signé éditorialement
  4. publie : exposé publiquement via l'API
  5. deprecie : remplacé par une nouvelle version, conservé pour historique

04

Versioning temporel

Aucune mise à jour destructive. Toute évolution d'une série, d'une mesure ou d'une formule de calcul crée une nouvelle version dotée de sa période de validité (valide_du / valide_au). Les anciennes versions restent accessibles pour la traçabilité scientifique. Les formules de calcul sont elles-mêmes versionnées indépendamment des séries : une correction de méthode ne réécrit jamais le passé.

· Les sources

Des sources documentées et tracées

Chaque série pointe vers exactement une source identifiée. Les acknowledgements officiels (NASA POWER, CM SAF / EUMETSAT) sont respectés dans la documentation et dans les exports. La calibration terrain (ANM Guinée) est l'objectif de roadmap, pas un acquis.

Sources opérationnelles · Couche B

NASA POWER

Couche B

NASA Langley Research Center

Source primaire du substrat physique (satellite/réanalyse). Modèles CERES SYN1deg / FLASHFlux pour l'irradiation, MERRA-2 GMAO pour la météorologie de surface. Pas journalier.

PVGIS-SARAH-3

Couche B

CM SAF · EUMETSAT (via PVGIS · JRC)

Cross-check mensuel GHI. Alimente le calcul d'ecart_relatif_referentiel et les validations long terme. Plage ICDR publiée 2021-2023.

Post-traitement éditorial · Couche C

Dérivés Kuma

Couche C

Kuma Science · source synthétique interne

Grandeurs calculées depuis le substrat selon les normes IEC/WMO : HEP, fraction diffuse, productible spécifique théorique, indicateur qualité, indices référentiels. Toutes les séries methode_collecte='calcul_derive' y pointent.

Normes méthodologiques · Couche C

IEC 61724-1:2021

International Electrotechnical Commission

Mesure de performance des systèmes photovoltaïques. Définit les conventions de performance ratio, de productible spécifique et de productivité utilisées dans la Famille 02.

WMO-No.8 · CIMO Guide

World Meteorological Organization

Guide des instruments et méthodes d'observation météorologique. Définit les conventions de mesure et d'unités utilisées dans toute la couche météorologique.

Sources envisagées · Feuille de route

ANM Guinée

Roadmap · Couche A

Agence Nationale de la Météorologie · Guinée

Objectif d'intégration future. Calibration terrain (mesures sol locales) destinée à alimenter la couche A — accès officiel à convenir avec l'ANM. Aucune série opérationnelle aujourd'hui.

ECMWF ERA5

Roadmap · Couche B

ECMWF · Copernicus C3S

Référencée doctrinairement pour un cross-check inter-modèle solaire + climat élargi. Pas d'ingestion active aujourd'hui ; l'usage hydro futur est rattaché à la phase 2.

Un vecteur hydraulique (sources WMO Global Runoff Data Centre, HydroSHEDS, normes IEC pour la petite hydraulique) est structuré pour une phase ultérieure.

· La couverture

Six communes pilotes en Guinée

La phase pilote couvre six communes guinéennes sur le substrat physique (solaire et climat). Les chiffres ci-dessous donnent l'ordre de grandeur du catalogue à mai 2026. L'extension géographique visera l'Afrique francophone, d'abord les voisins guinéens (Côte d'Ivoire, Mali, Sénégal, Burkina Faso), puis au-delà.

6

Communes pilotes

Conakry-Kaloum · Kankan · Kindia · Labé · Mamou · Nzérékoré

5

Années journalières

Couverture continue 2021 à 2025

30

Climatologie mensuelle

Référence 1991 à 2020

~100

Séries au catalogue

Combinaisons localité × grandeur × source

~20

Grandeurs

Brutes · calculées · référentielles · paramétrables

· Référence technique

Pour les développeurs intégrateurs

Le détail du contrat d'API, pour qui veut intégrer Kuma Data Core. Replié par défaut. Cliquez sur chaque section pour la déplier.

01 Authentification

L'API utilise un header Authorization de type Bearer. Les clés sont attribuées sur demande, individuellement, après validation du cas d'usage.

En-tête HTTP requis

Authorization: Bearer <cle>

En cas d'authentification invalide, l'API retourne un code 401 avec une enveloppe d'erreur structurée. Les codes utilisés sont :

  • AUTH_HEADER_MANQUANT : le header Authorization est absent
  • AUTH_FORMAT_INVALIDE : le format du header n'est pas conforme (manque Bearer)
  • AUTH_CLE_INVALIDE : la clé n'est pas reconnue ou a été révoquée
02 Endpoints

L'API expose 13 endpoints sous le préfixe /v1. Tous les endpoints sauf /v1/health exigent un en-tête d'authentification.

Santé

GET /v1/health État de l'API (public, sans auth)
GET /v1/health/db État de l'infrastructure (auth)

Séries

GET /v1/series Catalogue des séries. Filtres : localite, grandeur, source, actif. Pagination offset.
GET /v1/series/{code_serie} Détail d'une série et ses mesures. Filtres temporels from / to, format json ou csv, pagination.

Localités

GET /v1/localites Référentiel géographique. Filtres : pays_iso3, type_localite, parent_code.
GET /v1/localites/{code} Détail d'une localité (coordonnées, hiérarchie)

Grandeurs paramétrables

GET /v1/grandeurs/poa_parametrable Irradiation dans le plan des modules (Perez)
GET /v1/grandeurs/productible_correction_thermique Productible avec correction thermique (NOCT)
GET /v1/grandeurs/productible_pr_fourni Productible avec PR fourni (Marion / Dierauf)
GET /v1/grandeurs/energie_utile_ecs Énergie utile ECS (Hottel-Whillier-Bliss)
GET /v1/grandeurs/degre_jour_climatisation Degrés-jours de climatisation (ISO 15927-6)

Horaire · passe-plat

GET /v1/horaire/{localite}/{grandeur} Passe-plat horaire vers NASA POWER
GET /v1/horaire/{localite}/{grandeur}/disponibilite Plage temporelle disponible côté source
03 Format des réponses

JSON par défaut, CSV optionnel sur les endpoints de séries et de grandeurs paramétrables (paramètre format=csv). Pagination offset-based avec total, limit (maximum 1000), offset.

Les erreurs sont retournées dans une enveloppe normalisée :

Enveloppe d'erreur
{
"erreur": {
"code": "VALIDATION_PARAMETRE_INVALIDE", "message": "Le paramètre `inclinaison_deg` doit être
        entre 0 et 90.", "details": {
"parametre": "inclinaison_deg", "valeur_fournie": 110, "bornes": [0, 90]
}}}

Exemple de réponse détaillée d'une série incluant niveau_effectif et statut au niveau de chaque mesure :

Réponse 200 · /v1/series/{code_serie}
{
"code": "gin_kindia_ghi_nasa_power_2021_2025", "libelle": "GHI journalier Kindia 2021-2025 (NASA
        POWER)", "grandeur": {
"code": "ghi", "libelle": "Irradiation globale horizontale", "unit": "kWh/m²/jour"
}, "source": {
"code": "nasa_power", "label": "NASA POWER", "couche": "A"
}, "periode_debut": "2021-01-01", "periode_fin": "2025-12-31", "statut": "publie",
        "version": 3, "valide_du": "2026-01-15T00:00:00Z", "valide_au": null, "mesures": [
{
"date": "2024-06-15", "valeur": 5.21, "niveau_effectif": "A", "statut": "publie"
}
], "pagination": {
"total": 1826, "limit": 1000, "offset": 0
}}
04 Convention de nommage

Les codes de série suivent un format stable, prévisible et auto-descriptif :

Format des codes de série

<prefixe_localite>_<grandeur>_<source>_<plage_annees>

Exemple : gin_conakry_ghi_nasa_power_2021_2025 désigne la série d'irradiation globale horizontale pour Conakry, fournie par NASA POWER, sur la plage 2021-2025.

Les codes de localité utilisent la norme ISO 3166-1 alpha-3 pour le pays (gin = Guinée), suivi d'un slug pour les entités infranationales (gin_conakry, gin_kankan, etc.).

05 Codes d'erreur

Le contrat des codes d'erreur est stable. Les codes sont préfixés par famille pour faciliter le routage côté intégrateur.

AUTH_* Erreurs d'authentification (HTTP 401)
VALIDATION_* Paramètres de requête invalides (HTTP 400)
RESSOURCE_* Ressource non trouvée (HTTP 404)
INCOMPATIBILITE_SOURCE_GRANDEUR Combinaison source × grandeur non supportée
PLAGE_TEMPORELLE_NON_DISPONIBLE Plage demandée hors couverture de la série
PASSE_PLAT_INDISPONIBLE Service amont (NASA POWER) momentanément indisponible
INFRASTRUCTURE_* Erreurs côté infrastructure Kuma (HTTP 503)
SERVEUR_ERREUR_INTERNE Erreur générique non catégorisée (HTTP 500)

· Demander l'accès

Bêta privée · accès sur demande

L'API est documentée publiquement mais reste en bêta privée. Pour intégrer Kuma Data Core dans vos travaux, vos outils ou votre recherche, demandez une clé d'accès. Les usages couverts : bureaux d'études d'ingénierie, développeurs de projets, bailleurs internationaux, équipes de recherche académique.

Demander l'accès Lire nos travaux