Kuma Data Core API

The Kuma Data Core public API serves Guinea's climate and solar baseline: 34 towns, more than a million daily, monthly and hourly measurements, some twenty variables. Base URL https://api.kumascience.com, REST, JSON by default, CSV on series detail.

No value travels alone. Every response carries the source, the method, the unit, the confidence grade (A ground measurement, B modeled baseline, C derived) and the editorial status of the measurement. What the API serves is a dated release: what you cite stays reproducible.

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 themselves do not change with your reading language.

Access is open: a free, self-service key is all you need. Only GET /v1/edition, GET /v1/health and POST /v1/cles answer without a key.

Request · no key

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

Response

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

Authentication

A contact address is enough: the key is issued immediately, with no human review, and is shown only once (the server keeps only a fingerprint). It then goes in the Authorization header of every request.

Quota: 5,000 requests per day per key.
Issuance is capped at 3 keys per IP address over 24 hours.
The prefixe field is the key's public identifier: keep it for support or a revocation request.

Get a key

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 catalog is paginated (an items, total, limit, offset envelope) and filters by locality, variable and source. A series detail adds its measurements, each with its effective confidence grade and editorial status.

Parameter	Role
`localite`	locality code (e.g. `gin_boffa`)
`grandeur`	variable code (e.g. `ghi`, `dni`, `t2m`)
`source`	source code (e.g. `nasa_power`)
`limit` / `offset`	pagination (default 100, max 1,000)
`format=csv`	on detail: measurements as CSV

Catalog

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

Series detail

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 geographic reference set is hierarchical: continent, country, 8 regions, 33 prefectures, 38 communes, 81 entities in all. Measurements attach to the 34 covered towns (28 prefecture-seat communes plus the 6 historical pilot towns).

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

Locality detail

GET /v1/localites/gin_boffa

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

Variables

Beyond raw variables, the API exposes Kuma-computed ones: peak sun hours, photovoltaic energy yield, diffuse fraction, humidex, P50/P90. Parametric variables (tilted plane, thermal correction) take their assumptions as query parameters.

The cross-source uncertainty record states, for each locality, where satellite sources disagree (NASA POWER against SARAH-3 for GHI, against CAMS for DNI) and whether the point shares its source pixel with other localities. It is the data's honesty, quantified.

Cross-source uncertainty

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

Stored hourly series have passed quality control (status valide_auto) and are served by time window, in UTC. The public profile never proxies an upstream source in real time: a window outside the stored range answers PLAGE_TEMPORELLE_NON_DISPONIBLE.

Hourly window

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" }
  ]
}

Releases and citation

The server serves a dated copy of the reference database, published as a release. GET /v1/edition gives its identifier, date and coverage; the edition field of GET /v1/health repeats it. In a report or a paper, cite the release identifier together with the DOI: the data you read stays findable.

Data is licensed CC-BY 4.0. The engine is free software (AGPL): code, guide and full reference live 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_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.

Errors

All errors share the same envelope, and codes are stable: a published code never changes meaning. Codes are French, like the rest of the contract.

Code	HTTP	Meaning
`AUTH_CLE_INVALIDE`	401	key not in the valid set, or revoked
`RESSOURCE_INTROUVABLE`	404	no such resource
`PLAGE_TEMPORELLE_NON_DISPONIBLE`	400	window outside the stored range
`CLES_LIMITE_EMISSION_ATTEINTE`	429	per-IP issuance limit reached
`CLES_QUOTA_JOURNALIER_DEPASSE`	429	daily quota exhausted

Error envelope

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