API Kuma Data Core

L'API publique de Kuma Data Core sert le substrat climatique et solaire de la Guinée : 34 villes, plus d'un million de mesures journalières, mensuelles et horaires, une vingtaine de grandeurs. Base https://api.kumascience.com, REST, JSON par défaut, CSV sur le détail des séries.

Aucune valeur ne sort seule. Chaque réponse porte la source, la méthode, l'unité, le niveau de confiance (A mesure terrain, B substrat modélisé, C dérivé) et le statut éditorial de la mesure. Les données servies forment une édition datée : ce que vous citez est reproductible.

L'accès est libre : une clé gratuite, émise en self-service, suffit. Seuls GET /v1/edition, GET /v1/health et POST /v1/cles répondent sans clé.

Requête · sans clé

GET https://api.kumascience.com/v1/edition

Réponse

200 OK
{
  "edition_id": "edition_20260702",
  "date_publication": "2026-07-02",
  "revision_source": "534da416dba8",
  "couverture_resumee": {
    "localites": 81,
    "series": 1444
  }
}

Authentification

Une adresse de contact suffit : la clé est émise immédiatement, sans validation humaine, et n'est montrée qu'une seule fois (le serveur n'en conserve qu'une empreinte). Elle se présente ensuite dans l'en-tête Authorization de chaque requête.

Quota : 5 000 requêtes par jour et par clé.
Émission bornée à 3 clés par adresse IP sur 24 heures.
Le prefixe est l'identifiant public de la clé : conservez-le pour le support ou une demande de révocation.

Obtenir une clé

curl -X POST https://api.kumascience.com/v1/cles \
  -H "Content-Type: application/json" \
  -d '{"email": "vous@exemple.org", "usage_prevu": "dimensionnement"}'

Réponse

201 Created
{
  "cle": "kuma_...",  montrée une seule fois
  "prefixe": "kuma_xxxxxxxx",
  "quota_journalier": 5000
}

Usage

Sur chaque requête authentifiée :
Authorization: Bearer kuma_votre_cle

Séries

Le catalogue est paginé (enveloppe items, total, limit, offset) et se filtre par localité, grandeur et source. Le détail d'une série ajoute ses mesures, chacune avec son niveau de confiance effectif et son statut éditorial.

Paramètre	Rôle
`localite`	code localité (ex. `gin_boffa`)
`grandeur`	code grandeur (ex. `ghi`, `dni`, `t2m`)
`source`	code source (ex. `nasa_power`)
`limit` / `offset`	pagination (défaut 100, max 1000)
`format=csv`	sur le détail : mesures en CSV

Catalogue

GET /v1/series?localite=gin_boffa&grandeur=ghi

Réponse

200 OK |extrait
{
  "items": [{
    "code": "gin_boffa_ghi_nasa_power_2021_2025",
    "grandeur_unit": "kWh/m²/jour",
    "source_code": "nasa_power",
    "methode_collecte": "modele_satellitaire",
    "periode_debut": "2021-01-01",
    "periode_fin": "2025-12-31"
  }],
  "total": 5
}

Détail d'une série

GET /v1/series/gin_boffa_ghi_era5_land_2001_2020

200 OK |mesures, extrait
{
  "mesures": [
    { "annee": 2001, "mois": 1, "valeur": 5.7549,
      "niveau_effectif": "B", "statut": "brut" },
    { "annee": 2001, "mois": 2, "valeur": 6.1847,
      "niveau_effectif": "B", "statut": "brut" }
  ]
}

Localités

Le référentiel géographique est hiérarchique : continent, pays, 8 régions, 33 préfectures, 38 communes, soit 81 entités. Les mesures s'accrochent aux 34 villes couvertes (28 communes chef-lieux et les 6 villes pilotes historiques).

GET /v1/localites liste le référentiel, GET /v1/localites/{code} renvoie le détail.

Détail d'une localité

GET /v1/localites/gin_boffa

200 OK |extrait
{
  "code": "gin_boffa",
  "nom": "Boffa",
  "type_localite": "commune",
  "latitude": 10.1667,
  "longitude": -14.0333
}

Grandeurs

Au-delà des grandeurs brutes, l'API expose des grandeurs calculées par Kuma : heures équivalentes pleines, productibles photovoltaïques, fraction diffuse, humidex, P50/P90. Les grandeurs paramétrables (plan incliné, correction thermique) prennent leurs hypothèses en paramètres de requête.

La fiche d'incertitude inter-source dit, pour chaque localité, où les sources satellitaires divergent (écart NASA POWER contre SARAH-3 pour le GHI, contre CAMS pour le DNI) et si le point partage son pixel source avec d'autres localités. C'est l'honnêteté de la donnée, chiffrée.

Incertitude inter-source

GET /v1/grandeurs/incertitude_inter_source/gin_boffa

200 OK |extrait
{
  "fenetre": "2021-2023",
  "ecarts": [
    { "grandeur": "ghi", "paire": "NASA POWER vs PVGIS-SARAH3",
      "ecart_abs_pct": 2.25, "n_mois": 36 },
    { "grandeur": "dni", "paire": "NASA POWER vs CAMS",
      "ecart_abs_pct": 13.48, "n_mois": 36 }
  ],
  "degenerescence": { "n_jumeaux": 1 },
  "niveau_confiance": "B"
}

Horaire

Les séries horaires stockées ont passé un contrôle qualité (statut valide_auto) et se servent par fenêtre temporelle, en UTC. Le profil public ne relaie jamais une source amont en temps réel : une plage non couverte par le stocké répond PLAGE_TEMPORELLE_NON_DISPONIBLE.

Fenêtre horaire

GET /v1/horaire/conakry_kaloum/ghi
    ?periode_debut=2022-06-01&periode_fin=2022-06-01

200 OK |extrait
{
  "resultats": [
    { "instant": "2022-06-01T10:00:00", "valeur": 710.12,
      "unite": "Wh/m²", "statut_editorial": "valide_auto" },
    { "instant": "2022-06-01T11:00:00", "valeur": 695.45,
      "unite": "Wh/m²", "statut_editorial": "valide_auto" }
  ]
}

Édition et citation

Le serveur sert une copie datée de la base de référence, publiée comme une édition. GET /v1/edition donne son identifiant, sa date et sa couverture ; le champ edition de GET /v1/health le rappelle. Dans un rapport ou un article, citez l'identifiant d'édition avec le DOI : la donnée que vous avez lue reste retrouvable.

Données sous licence CC-BY 4.0. Le moteur est un logiciel libre (AGPL) : code, guide et référence complète dans le dépôt. Pour un usage au-delà du quota gratuit, écrivez-nous.

Citation

Pour citer les données consultées :
Kuma Data Core, édition edition_20260702
(publiée le 2026-07-02), consultée via
api.kumascience.com. DOI 10.5281/zenodo.21117158.
Données sous licence CC-BY 4.0.

Erreurs

Toutes les erreurs suivent la même enveloppe, et les codes sont stables : un code publié ne change pas de sens.

Code	HTTP	Sens
`AUTH_CLE_INVALIDE`	401	clé absente du jeu valide ou révoquée
`RESSOURCE_INTROUVABLE`	404	ressource inexistante
`PLAGE_TEMPORELLE_NON_DISPONIBLE`	400	fenêtre hors du stocké
`CLES_LIMITE_EMISSION_ATTEINTE`	429	limite d'émission par IP
`CLES_QUOTA_JOURNALIER_DEPASSE`	429	quota du jour épuisé

Enveloppe d'erreur

401 Unauthorized
{
  "erreur": {
    "code": "AUTH_CLE_INVALIDE",
    "message": "Clé API invalide ou révoquée.",
    "details": {}
  }
}