Skip to content

API Reference

The CEMA Warehouse provides RESTful API endpoints that allow developers to programmatically access datasets without downloading files locally. This maintains a single source of truth and enables real-time data integration.

If you use Python or R for analysis, you can load data directly into your environment without manually downloading files.

The API reference page can be located using this link: API Docs

Your Profile & API Token

Access your profile by clicking your name in the top-right corner to access your Profile page.

Access token from your profile page

  • See your current API token - click Generate API token, it is then auto-populated across all the dataset API endpoints.
  • Regenerate your token - if you think your token has been compromised, generate a new one. The old token will immediately stop working.

API token security

  • Do not share your token in emails, slides, or public GitHub repositories
  • If you share a script with a colleague, remove your token first and ask them to use their own
  • Regenerate your token immediately if you think someone else has it

Use the URL

In our case, the token is auto-populated across all the API's once generated. The followng section shows how to use the API endpoints in your working environments :

Python (pandas)

import pandas as pd

df = pd.read_csv(
    "https://warehouse.cema.africa/api/v2/dataset/your-dataset-slug/YOUR_TOKEN?fmt=csv"
)
print(df.head())

R (data.table)

library(data.table)

dt <- fread(
    "https://warehouse.cema.africa/api/v2/dataset/your-dataset-slug/YOUR_TOKEN?fmt=csv"
)
head(dt)

R (tidyverse)

library(readr)

df <- read_csv(
    "https://warehouse.cema.africa/api/v2/dataset/your-dataset-slug/YOUR_TOKEN?fmt=csv"
)
glimpse(df)

This has been simplified and is automatically placed in your API URLs once you generate your user tokens

Pinning to a specific version

If you are writing a paper or running an analysis that must be reproducible, pin your code to a specific data version:

# Always loads version 1, regardless of future updates
df = pd.read_csv(
    "https://warehouse.cema.africa/api/v2/dataset/your-dataset-slug/YOUR_TOKEN?fmt=csv&version=1"
)

GIS data in Python / R (shapefiles)

import geopandas as gpd

gdf = gpd.read_file(
    "https://warehouse.cema.africa/api/v2/gis/shapefile/your-shapefile-slug/YOUR_TOKEN"
)

library(sf)

sf_data <- st_read(
    "https://warehouse.cema.africa/api/v2/gis/shapefile/your-shapefile-slug/YOUR_TOKEN"
)

The full API documentation with live examples is available at API in the navigation bar (you must be logged in to see it).

CHEERS!