Data and API

Kuma Data Core API

The energy and climate series published by Kuma Science, programmatically: every measurement comes with its source, method, unit and qualification level, in a dated release you can cite.

Base URL
https://api.kumascience.com/v1
Formats
JSON; CSV for the measurements of a series
Coverage
2,728 series, 34 towns in Guinea
Access
free key, issued online
Release served
edition_20260822, 22 August 2026
Licences
data CC BY 4.0, engine AGPL v3

The API's contract language is French. Field names (edition_id, grandeur_unit), resource paths and error codes are French and stable. This page documents them in English; the payloads are the same whatever your reading language.

Get a key Open the console

Request without a key Try it 
GET https://api.kumascience.com/v1/edition
Response 
200 OK
{
  "edition_id": "edition_20260822",
  "date_publication": "2026-08-22",
  "revision_source": "3ae5dd4c9b6f",
  "couverture_resumee": {
    "localites": 81,
    "series": 2728
  }
}

Authentication

A contact address is enough to get a key. It is issued immediately and shown only once, since the server keeps only a fingerprint of it. It then goes in the Authorization header of every request.

  • Each key allows 5,000 requests per day.
  • One IP address can obtain at most 3 keys in 24 hours.
  • The prefixe field identifies the key publicly. Keep it for support or to request a revocation.

Three routes answer without a key: GET /v1/edition, GET /v1/health and POST /v1/cles.

Get a key Try it 
curl -X POST https://api.kumascience.com/v1/cles \
  -H "Content-Type: application/json" \
  -d '{"email": "vous@exemple.org", "usage_prevu": "dimensionnement"}'
Response 
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

Series

The series catalog is paginated: the response holds items, total, limit and offset. It can be filtered with the parameters in the table below. A series detail returns its measurements, each with its confidence grade and status.

ParameterRole
localitelocality code (e.g. gin_boffa)
grandeurvariable code (e.g. ghi, dni, t2m)
sourcesource code (e.g. nasa_power)
limit / offsetpagination (default 100, max 1,000)
format=csvon detail: measurements as CSV

The niveau_effectif field of each measurement says where it comes from.

ValueMeaning
Aground measurement
Bsatellite or reanalysis data
Cvalue derived by computation
Catalog Try it 
GET /v1/series?localite=gin_boffa&grandeur=ghi
Response 
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
}
Series detail Try it 
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" }
  ]
}

Localities

A locality is the API's generic place entity. The reference set has 81 entities: the continent, the country, 8 regions, 33 prefectures and 38 communes. Measurements are attached to 34 reference locations: the 33 prefecture seats and Kaloum for Conakry.

GET /v1/localites lists the reference set. GET /v1/localites/{code} returns one locality.

Locality detail Try it 
GET /v1/localites/gin_boffa

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

Variables

On top of raw variables, the API computes derived ones, for example photovoltaic energy yield, diffuse fraction or annual P50 and P90. Calculation assumptions, such as plane tilt or thermal correction, are passed as query parameters.

The cross-source uncertainty record gives, for each locality, the gap between satellite sources: NASA POWER against SARAH-3 for GHI, and against CAMS for DNI. It also flags when the point shares its source pixel with another locality.

Cross-source uncertainty Try it 
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"
}

Hourly data

Hourly series are requested by date window, with timestamps in UTC. GET /v1/horaire/{localite}/{grandeur}/disponibilite gives the range served. A window outside it returns the error PLAGE_TEMPORELLE_NON_DISPONIBLE.

Hourly window Try it 
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" }
  ]
}

Releases and citation

The API serves a dated copy of the reference database, called a release. GET /v1/edition returns its identifier, date and coverage, and the edition field of GET /v1/health repeats it. To cite the data in a report or a paper, give the release identifier and the DOI.

The engine's code and full documentation are in the repository. For usage beyond the free quota, write to us.

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.

Errors

All errors have the same shape: an erreur object with a code and a message. A published code always keeps its meaning. Codes are French, like the rest of the contract.

HTTPCode and meaning
401AUTH_HEADER_MANQUANTAuthorization header missing
401AUTH_CLE_INVALIDEunknown or revoked key
404RESSOURCE_SERIE_INCONNUEno series with this code
404RESSOURCE_LOCALITE_INCONNUEno locality with this code
422VALIDATION_VALEUR_INVALIDEparameter out of bounds or malformed
400PLAGE_TEMPORELLE_NON_DISPONIBLEwindow outside the range served
429CLES_LIMITE_EMISSION_ATTEINTEper-IP issuance limit reached
429CLES_QUOTA_JOURNALIER_DEPASSEdaily quota exhausted
Error envelope 
401 Unauthorized
{
  "erreur": {
    "code": "AUTH_CLE_INVALIDE",
    "message": "Clé API invalide ou révoquée.",
    "details": {}
  }
}