API Kuma Data Core

Les séries énergétiques et climatiques publiées par Kuma Science, par programme : chaque mesure arrive avec sa source, sa méthode, son unité et son niveau de qualification, dans une édition datée que l'on peut citer.

Adresse de base: https://api.kumascience.com/v1
Formats: JSON ; CSV pour les mesures d’une série
Couverture: 2 728 séries, 34 villes de Guinée
Accès: clé gratuite, obtenue en ligne
Édition servie: edition_20260822, 22 août 2026
Licences: données CC BY 4.0, moteur AGPL v3

Obtenir une clé Ouvrir la console

Requête sans clé Essayer

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

Réponse

200 OK
{
  "edition_id": "edition_20260822",
  "date_publication": "2026-08-22",
  "revision_source": "3ae5dd4c9b6f",
  "couverture_resumee": {
    "localites": 81,
    "series": 2728
  }
}

Authentification

Une adresse de contact suffit pour obtenir une clé. Elle est émise tout de suite et affichée une seule fois, car le serveur n'en garde qu'une empreinte. Elle se transmet ensuite dans l'en-tête Authorization de chaque requête.

Chaque clé a droit à 5 000 requêtes par jour.
Une même adresse IP peut obtenir au plus 3 clés en 24 heures.
Le champ prefixe identifie la clé publiquement. Conservez-le pour le support ou pour demander une révocation.

Trois routes répondent sans clé : GET /v1/edition, GET /v1/health et POST /v1/cles.

Obtenir une clé Essayer

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 des séries est paginé : la réponse contient items, total, limit et offset. On peut le filtrer avec les paramètres du tableau ci-dessous. Le détail d'une série renvoie ses mesures, chacune avec son niveau de confiance et son statut.

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

Le champ niveau_effectif de chaque mesure dit d'où elle vient.

Valeur	Sens
`A`	mesure au sol
`B`	donnée satellitaire ou de réanalyse
`C`	valeur dérivée par calcul

Catalogue Essayer

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": 12
}

Détail d'une série Essayer

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 compte 81 entités : le continent, le pays, 8 régions, 33 préfectures et 38 communes. Les mesures sont rattachées à 34 localités de référence : les 33 chefs-lieux de préfecture et Kaloum pour Conakry.

GET /v1/localites liste le référentiel. GET /v1/localites/{code} renvoie une localité.

Détail d'une localité Essayer

GET /v1/localites/gin_boffa

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

Grandeurs

En plus des grandeurs brutes, l'API calcule des grandeurs dérivées, par exemple le productible photovoltaïque, la fraction diffuse ou les P50 et P90 annuels. Les hypothèses de calcul, comme l'inclinaison du plan ou la correction thermique, se passent en paramètres de requête.

La fiche d'incertitude inter-source donne, pour chaque localité, l'écart entre sources satellitaires : NASA POWER contre SARAH-3 pour le GHI, et contre CAMS pour le DNI. Elle signale aussi quand le point partage son pixel source avec une autre localité.

Incertitude inter-source Essayer

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 se demandent par fenêtre de dates, et les instants sont en UTC. GET /v1/horaire/{localite}/{grandeur}/disponibilite donne la plage servie. Une fenêtre qui en sort renvoie l'erreur PLAGE_TEMPORELLE_NON_DISPONIBLE.

Fenêtre horaire Essayer

GET /v1/horaire/gin_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

L'API sert une copie datée de la base de référence, appelée édition. GET /v1/edition renvoie son identifiant, sa date et sa couverture, et le champ edition de GET /v1/health le rappelle. Pour citer les données dans un rapport ou un article, donnez l'identifiant d'édition et le DOI.

Le code du moteur et sa documentation complète sont 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_20260822
(publiée le 2026-08-22), consultée via
api.kumascience.com. DOI 10.5281/zenodo.21117158.
Données sous licence CC-BY 4.0.

Erreurs

Toutes les erreurs ont la même forme : un objet erreur avec un code et un message. Un code publié garde toujours le même sens.

HTTP	Code et sens
401	`AUTH_HEADER_MANQUANT`en-tête Authorization absent
401	`AUTH_CLE_INVALIDE`clé inconnue ou révoquée
404	`RESSOURCE_SERIE_INCONNUE`aucune série à ce code
404	`RESSOURCE_LOCALITE_INCONNUE`aucune localité à ce code
422	`VALIDATION_VALEUR_INVALIDE`paramètre hors bornes ou mal formé
400	`PLAGE_TEMPORELLE_NON_DISPONIBLE`fenêtre hors de la plage servie
429	`CLES_LIMITE_EMISSION_ATTEINTE`limite d'émission par IP atteinte
429	`CLES_QUOTA_JOURNALIER_DEPASSE`quota du jour épuisé

Enveloppe d'erreur

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