# Africa API — Full Documentation
> One REST API for all 54 African countries: economic indicators, FX and markets, trade, elections, policies, and current country signals. Free API key.
API base URL: https://api.africa-api.com
OpenAPI schema: https://api.africa-api.com/openapi.json
Condensed index: https://africa-api.com/llms.txt
MCP server: npx -y africa-api-mcp (https://www.npmjs.com/package/africa-api-mcp)
---
# Africa API Documentation
URL: https://africa-api.com/docs
Description: Learn how Africa API turns fragmented African country, market, policy, and signals data into one product-ready platform.
## What Africa API covers
Africa API is a REST API for data on all 54 African countries: 127+ indicators with 10+ years of history, current country signals, FX and market data, trade flows, elections, policies, and government records, sourced from the World Bank, UN, ILO, FAOSTAT, and central banks. It is built for teams that want to ship with African data without stitching dozens of disconnected sources.
Africa API is organized around a few clear jobs:
1. country reference data
2. current country signals
3. historical indicators and time series
4. market and FX data
5. trade, government, elections, and policies
## Base URL
```text
https://api.africa-api.com
```
- Public API routes live under `/v1`.
- Most data routes require an API key.
- Operational routes such as `/health` and `/v1/platform/version` are documented separately.
## Start Here
Country reference records, detail pages, and curated country profiles.
Current country snapshot across macro signals, climate, disaster alerts, FX, markets, trade, and government context.
Canonical query layer for historical indicators, latest values, and time series.
See which domains are broad continent-wide coverage and which current signals are live country by country.
Exchange metadata, tickers, historical market data, and FX rates.
Country trade overview plus partner, product, and flow queries.
Leaders, cabinets, elections, and policy records as dedicated domains.
Connect Claude, Cursor, and other AI tools directly to live African data.
## Choose the right route
- Use `/v1/countries` when you need reference data.
- Use `/v1/countries/{country_code}/signals` when you want a compact current snapshot.
- Use `/v1/data` when you need explicit metric queries, time series, or source pinning.
- Use the dedicated domain routes for markets, trade, government, elections, and policies.
## Operational and provenance endpoints
Source metadata and platform-health endpoints are available when you need:
- licensing context
- provenance
- freshness checks
- platform health and release verification
See:
- [Sources](/docs/sources)
- [Platform](/docs/platform)
- [Health](/docs/health)
## Recommended path
Make your first authenticated requests and establish a reusable client pattern.
Understand which routes are public, how API keys are used, and how to store them safely.
Check live country and domain coverage before you design your integration around a specific signal family.
Learn the canonical query endpoint for historical series and latest values.
Explore the dedicated trade domain once you need more than aggregate indicators.
## Use-case entry points
Start here when you need country records, profiles, and current country snapshots.
Start here when you need historical indicators, latest values, or rankings.
Start here when you need exchanges, tickers, historical prices, or FX rates.
Start here if you are replacing code that called the retired api.dataafrica.io.
If you want the clearest current entry points into the platform, start with [African Countries API](/docs/african-countries-api), [Agriculture](/docs/agriculture), and [Policies](/docs/policies).
## Topic guides
Query crop production, yields, irrigation, land use, and livestock data across African countries.
Work with emissions, air quality, forests, renewable electricity, water stress, and climate context.
Access policy documents, laws, lifecycle events, and country policy timelines.
Explore election events, country overviews, and candidate-level result rows.
---
# African Countries API
URL: https://africa-api.com/docs/african-countries-api
Description: Launch country pages, country selectors, and country workflows with one source of truth for African country data.
Africa API gives you one dependable country layer for Africa-focused products, research, and internal workflows.
Use this route family when you need:
- country directories and country pickers
- country detail pages
- compact country profiles for dashboards or reports
- current country snapshots that mix reference data with fresh signals
Most country routes require an API key. Start with [Quickstart](/docs/quickstart) if you have not set up authentication yet.
## Start With These Endpoints
Use `/v1/countries` for country discovery, filtering, and reference records.
Use `/v1/countries/{country_code}` for a full country record.
Use `/v1/countries/{country_code}/profile` for a curated country summary.
Use `/v1/countries/{country_code}/signals` for a compact current snapshot.
## Example: List Countries In A Region
```bash
curl "https://api.africa-api.com/v1/countries" \
-G \
-d "region=west" \
-d "sort=name" \
-d "paginate=true" \
-d "per_page=10" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
Use this when you need a filtered country list for navigation, search, onboarding, or market coverage views.
## Example: Get A Country Profile
```bash
curl "https://api.africa-api.com/v1/countries/ke/profile" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
This is usually the best first call for a country overview page because it gives you a curated summary without making several separate requests.
## Example: Get Current Country Signals
```bash
curl "https://api.africa-api.com/v1/countries/ke/signals" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
Use signals when your product needs a fresher operational snapshot across macro indicators, markets, trade context, climate context, humanitarian context, and government context.
## Which Route Should You Use?
- Use `/v1/countries` when you need discovery and reference fields.
- Use `/v1/countries/{country_code}` when you need the full base country record.
- Use `/v1/countries/{country_code}/profile` when you want one curated summary payload.
- Use `/v1/countries/{country_code}/signals` when you care about current context more than a static record.
- Use `/v1/data` when you need specific indicators or time series rather than a country-centered summary.
## What You Can Build
- country profile pages
- internal country research tools
- market coverage selectors
- country comparison dashboards
- onboarding flows where users choose one or more countries first
## Related Docs
Full reference for country list, detail, profile, and signals routes.
Current snapshot payloads for country-level operational context.
Geography hierarchy records when you need regions and parent-child relationships.
Query explicit metrics and time series when country profiles are not enough.
---
# African Indicators and Time Series API
URL: https://africa-api.com/docs/african-indicators-api
Description: Power dashboards, rankings, and analysis with African indicators and time series in one consistent platform.
Use this part of Africa API when your product needs decision-ready historical data, latest values, indicator discovery, or country rankings.
This is the best fit for:
- dashboards and analytics products
- research workflows
- country comparisons
- scoring models and monitoring systems
- time-series visualizations
Start with `/v1/indicators` when you need discovery. Start with `/v1/data` when you already know the metric you want.
## Start With These Endpoints
Use `/v1/indicators` to browse available metrics and coverage.
Use `/v1/data` for latest values and time series.
Use `/v1/indicators/{metric_key}` to inspect one indicator.
Use `/v1/indicators/{metric_key}/rankings` for ranked comparisons.
## Example: Discover Climate Indicators
```bash
curl "https://api.africa-api.com/v1/indicators?category=climate&has_data=true" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
This is a good first step when you know the topic area but not the exact metric keys yet.
## Example: Compare GDP Across Countries
```bash
curl "https://api.africa-api.com/v1/data?country_codes=ng,ke,za&metric_key=gdp_current_usd&year=2024" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
Use `/v1/data` for side-by-side comparisons when you already know the metric key and the slice you want.
## Example: Get The Latest Value For One Metric
```bash
curl "https://api.africa-api.com/v1/data?country_code=ke&metric_key=population_total&latest=true" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
This is the simplest pattern for “give me the most recent known value for this metric.”
## Example: Rank Countries By One Indicator
```bash
curl "https://api.africa-api.com/v1/indicators/gdp_current_usd/rankings?year=2024&limit=10" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
Rankings are useful when you need leaderboards, comparison tables, or shortlist screens.
## When To Use `data` Vs `indicators`
- Use `/v1/indicators` to discover what exists.
- Use `/v1/indicators/{metric_key}` to inspect one metric and its metadata.
- Use `/v1/data` to fetch observations for charts, tables, and analysis.
- Use `/v1/indicators/{metric_key}/rankings` when you need sorted country comparisons.
- Use country `signals` when you want a compact country snapshot instead of a metric-driven query.
## Categories Currently Covered
Common categories include:
- demographics
- economy
- agriculture
- energy
- climate
- health
- education
- infrastructure
## Related Docs
Canonical observation queries across countries, years, categories, and sources.
Discover metric definitions, coverage, and rankings.
Examples for macroeconomic indicator workflows.
Examples for climate-related discovery and time-series use cases.
---
# African Market Data API
URL: https://africa-api.com/docs/african-market-data-api
Description: Bring African exchanges, tickers, FX rates, and market history into products without stitching multiple sources.
Use Africa API market routes when your application needs exchange metadata, ticker coverage, historical prices, or FX rates tied to African markets in one place.
This is the best fit for:
- market dashboards
- watchlists and portfolio tools
- exchange lookup tools
- FX monitoring
- country products that need market context alongside broader economic data
Market coverage is currently narrower than the broader country and indicator surfaces. Use this page to understand the main routes, then check the reference docs for current coverage details.
## Start With These Endpoints
Use `/v1/markets/exchanges` for exchange metadata and latest trade dates.
Use `/v1/markets/tickers` to list exchange instruments.
Use `/v1/markets/tickers/{exchange_code}/{ticker_symbol}` for one instrument.
Use `/v1/markets/fx-rates` for currency pairs and related history routes.
## Example: List Exchanges
```bash
curl "https://api.africa-api.com/v1/markets/exchanges" \
-G \
-d "country_code=ng" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
This is a good entry point when you need to understand which exchanges and countries are currently covered.
## Example: Browse Tickers
```bash
curl "https://api.africa-api.com/v1/markets/tickers" \
-G \
-d "exchange_code=NGX" \
-d "limit=20" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
Use this when you need ticker search, watchlist setup, or exchange-specific instrument lists.
## Example: Get Historical Prices For One Ticker
```bash
curl "https://api.africa-api.com/v1/markets/tickers/NGX/MTNN/history" \
-G \
-d "start_date=2025-01-01" \
-d "end_date=2025-12-31" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
This is the route to use for charting and historical price analysis.
## Example: Query FX Rates
```bash
curl "https://api.africa-api.com/v1/markets/fx-rates" \
-G \
-d "base_currency=USD" \
-d "quote_currency=NGN" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
Use FX routes when your application needs currency conversion context or exchange-rate history for African markets.
## Coverage Notes
Current reference coverage includes:
- exchange metadata and tickers for supported African exchanges
- historical price data for supported instruments
- FX coverage including broad USD-based daily rates
- official BCEAO-published XOF rates for WAEMU-related workflows
Use the market reference docs for the most current coverage details and supported parameters.
## Related Docs
Full route reference for exchanges, tickers, history, and FX rates.
Combine market data with country records and country snapshots.
Add compact market context to country-level operational views.
Pair market data with trade context for broader country analysis.
---
# Agriculture
URL: https://africa-api.com/docs/agriculture
Description: Access crop production, yields, irrigation, land use, and livestock data across African countries with historical series and latest values.
## African Agriculture Data API
Use Africa API to compare crop output across countries, track yields over time, monitor irrigation and land use, and pull agriculture context into country workflows.
Coming from DataAfrica? The old `api.dataafrica.io` crop, rainfall, and nutrition queries have been unmaintained since 2017. See the [DataAfrica migration guide](/docs/dataafrica-api) for endpoint mappings.
This page is the best starting point when you need:
- agriculture indicators by category
- latest agriculture snapshots by country
- historical crop or land-use time series
- agriculture context inside country profiles
## Start With These Endpoints
Agriculture data is exposed through shared indicator, data, and country-profile endpoints.
- `GET /v1/indicators?category=agriculture`
- `GET /v1/data?category=agriculture`
- `GET /v1/countries/{country_code}/profile`
- `GET /v1/sources/faostat_agriculture`
## Common Agriculture Questions
- Which crop and livestock metrics are available today?
- Which countries have data for a specific agriculture metric?
- How do I fetch the latest agriculture snapshot versus a full time series?
- How do I blend agriculture with broader country context?
## Common Agriculture Workflows
- Discover the agriculture metrics currently available with `/v1/indicators?category=agriculture`.
- Fetch a latest snapshot with `/v1/data?category=agriculture&latest=true`.
- Pull a country time series when you need a specific metric across multiple years.
- Use country profiles when you want agriculture highlights alongside broader economic and infrastructure context.
## Useful Metrics
- `agricultural_land_1000ha`
- `arable_land_1000ha`
- `forest_land_1000ha`
- `land_equipped_for_irrigation_1000ha`
- `maize_production_tonnes`
- `wheat_production_tonnes`
- `rice_production_tonnes`
- `maize_yield_kg_per_ha`
- `wheat_yield_kg_per_ha`
- `rice_yield_kg_per_ha`
- `cattle_stock_head`
- `chicken_stock_1000_head`
## Example: Compare Crop Production Across Countries
```bash
curl "https://api.africa-api.com/v1/data?country_codes=ng,et,za&metric_key=maize_production_tonnes&year=2024" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
## Example: Discover Agriculture Metrics And Coverage
```bash
curl "https://api.africa-api.com/v1/indicators?category=agriculture&has_data=true" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
## Example: Get The Latest Agriculture Snapshot For A Country
```bash
curl "https://api.africa-api.com/v1/data?country_code=ke&category=agriculture&latest=true" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
## Coverage And Source Notes
Agriculture coverage depends on the metric and country, so check the indicator catalog before you hard-code a workflow around one series.
The main agriculture source in this slice is `faostat_agriculture`.
Use `/v1/indicators?category=agriculture&has_data=true` when you want to confirm which metrics are available, how they are named, and where coverage is already strong.
## Related Docs
Inspect the agriculture metric catalog and coverage.
Query latest agriculture values or full time series.
Blend agriculture with country reference records, profiles, and current signals.
Review FAOSTAT coverage, provenance, and freshness.
---
# Authentication
URL: https://africa-api.com/docs/authentication
Description: Authenticate Africa API requests with bearer tokens, create API keys in the dashboard, and understand which routes are public.
## API Keys
Create and manage API keys in the [dashboard](https://africa-api.com/dashboard).
Protected requests use:
```http
Authorization: Bearer
```
### Public routes
- `GET /health`
- `GET /v1/platform/version`
### Protected routes
All current data-bearing `/v1/*` routes require:
```http
Authorization: Bearer
```
Do not assume read routes are public. Countries, signals, indicators, data, markets, trade, government, and policy routes all require an API key.
## Request Format
```bash
curl "https://api.africa-api.com/v1/data?country_code=ke&metric_key=population_total&latest=true" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
## Implementation Guidance
1. Always send the `Authorization` header from your first protected request.
2. Store API keys server-side for production workloads.
3. Use separate keys per environment.
4. Rotate keys on any suspected exposure.
5. Never embed production keys in public client-side code.
## JavaScript Pattern
```typescript
const response = await fetch(
"https://api.africa-api.com/v1/indicators?category=health&has_data=true",
{
headers: {
Authorization: `Bearer ${process.env.AFRICA_API_KEY ?? ""}`,
},
},
);
```
## Expected Auth Errors
| Status | Meaning |
|--------|---------|
| `401` | Missing or invalid bearer token |
| `403` | Authenticated but not permitted for the attempted action |
See [Errors](/docs/errors) for full handling guidance.
## Related
First authenticated request flow.
Status codes and response shapes.
---
# Central Banks
URL: https://africa-api.com/docs/central-banks
Description: Use Africa API signals and data endpoints for current central-bank policy rates, benchmark rates, and monthly inflation signals.
## Central Bank Signals
Africa API uses official central-bank releases to provide fresher country signals than annual macro datasets alone.
The current live slice covers:
- CEMAC countries via BEAC
- `policy_rate_pct`
- Morocco
- `policy_rate_pct`
- WAEMU countries via BCEAO
- `policy_rate_pct`
- Nigeria
- `policy_rate_pct`
- `official_exchange_rate_latest_lcu_per_usd`
- `inflation_cpi_latest_yoy_pct`
- South Africa
- `policy_rate_pct`
- `inflation_cpi_latest_yoy_pct`
- Kenya
- `policy_rate_pct`
- `overnight_interbank_rate_pct`
- `inflation_cpi_latest_yoy_pct`
- Namibia
- `policy_rate_pct`
- Tanzania
- `policy_rate_pct`
- `inflation_cpi_latest_yoy_pct`
- `interbank_7d_rate_pct`
- `official_exchange_rate_latest_lcu_per_usd`
- Tunisia
- `policy_rate_pct`
- `official_exchange_rate_latest_lcu_per_usd`
These series are additive:
- historical annual series still live in `/v1/data`
- current releases are surfaced through `/v1/countries/{country_code}/signals`
## Example
```bash title="Kenya Signals"
curl "https://api.africa-api.com/v1/countries/ke/signals" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```bash title="Nigeria Signals"
curl "https://api.africa-api.com/v1/countries/ng/signals" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```bash title="South Africa Signals"
curl "https://api.africa-api.com/v1/countries/za/signals" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```bash title="Senegal Signals"
curl "https://api.africa-api.com/v1/countries/sn/signals" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```bash title="Morocco Signals"
curl "https://api.africa-api.com/v1/countries/ma/signals" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```bash title="Namibia Signals"
curl "https://api.africa-api.com/v1/countries/na/signals" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```bash title="Tanzania Signals"
curl "https://api.africa-api.com/v1/countries/tz/signals" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```bash title="Tunisia Signals"
curl "https://api.africa-api.com/v1/countries/tn/signals" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```bash title="One Explicit Current Series"
curl "https://api.africa-api.com/v1/data?country_code=ke&metric_key=policy_rate_pct&latest=true" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
## Why It Is Modeled This Way
Central-bank sources publish at different cadences and with different definitions than annual international datasets.
Africa API keeps the contract simple by:
- keeping historical series stable
- exposing current releases as clearly labeled signal metrics
- showing `source`, `frequency`, and `as_of_period` in the response
The BCEAO layer expands current policy-rate coverage across:
- Benin
- Burkina Faso
- Côte d'Ivoire
- Guinea-Bissau
- Mali
- Niger
- Senegal
- Togo
The BEAC layer expands current policy-rate coverage across:
- Cameroon
- Central African Republic
- Chad
- Congo
- Equatorial Guinea
- Gabon
Morocco now also has an official Bank Al-Maghrib policy-rate signal through the same `policy_rate_pct` metric.
Namibia now also has an official Bank of Namibia repo-rate signal through the same `policy_rate_pct` metric.
Expected next expansions include reserves, yields, and similar current macro signals.
Read the compact country snapshot that surfaces the latest current signals.
See the broader macro and monthly economic signal catalog.
---
# Climate
URL: https://africa-api.com/docs/climate
Description: Use indicators, data endpoints, and current signals to work with emissions, air quality, forests, protected areas, renewable electricity, water stress, and live climate context.
## Climate In Africa API
Climate and environment data is exposed through the shared indicator and data endpoints.
Climate coverage now has two layers:
- historical annual country indicators from World Bank WDI
- current climate signals from NASA POWER
- `GET /v1/indicators?category=climate`
- `GET /v1/data?category=climate`
- `GET /v1/sources/world_bank_wdi`
## Current Climate Metrics
- `co2e_emissions_per_capita`
- `co2e_emissions_total_mt`
- `pm25_air_pollution_ug_per_m3`
- `forest_area_pct_land`
- `protected_areas_pct_total`
- `renewable_electricity_output_pct_total`
- `freshwater_withdrawals_pct_internal_resources`
These are annual country-level climate and environment observations and fit the current observation model cleanly.
## Current Climate Signals
- `temperature_2m_latest_c`
- `relative_humidity_latest_pct`
- `precipitation_7d_mm`
- `precipitation_30d_mm`
These are current daily or rolling signals intended for operational context in `/v1/countries/{country_code}/signals`.
## Example Queries
```bash
curl "https://api.africa-api.com/v1/indicators?category=climate&has_data=true" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```bash
curl "https://api.africa-api.com/v1/data?country_codes=ke,ng,za&metric_key=pm25_air_pollution_ug_per_m3&year=2023" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```bash
curl "https://api.africa-api.com/v1/data?country_code=ga&metric_key=forest_area_pct_land&start_year=2018&end_year=2024" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```bash title="Current Climate Signals"
curl "https://api.africa-api.com/v1/countries/ke/signals" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
Inspect available climate metrics and coverage.
Query latest climate values or full time series.
Use country profiles to blend climate signals with the rest of the platform.
Use the current-signals layer for temperature, humidity, and rainfall context.
---
# Commodities
URL: https://africa-api.com/docs/commodities
Description: Use benchmark commodity prices from country signals to add current market context without leaving the API.
## Commodity Benchmarks In Africa API
Africa API exposes benchmark commodity prices through country signals.
Use:
- `GET /v1/countries/{country_code}/signals`
The `commodity_benchmarks` block is designed for current context, not country-specific supply or production measurement.
## What It Contains
Current benchmark series include:
- `crude_oil_benchmark_usd_per_bbl`
- `natural_gas_europe_benchmark_usd_per_mmbtu`
- `maize_benchmark_usd_per_mt`
- `rice_benchmark_usd_per_mt`
- `wheat_benchmark_usd_per_mt`
These are global reference prices sourced from the World Bank Pink Sheet monthly workbook.
## How To Use It
Use benchmark commodities when you want:
- quick pricing context in a country dashboard
- current cost-pressure context alongside inflation and FX
- a simple commodity reference layer for applications and agents
Do **not** treat these as local retail or domestic producer prices.
## Example
```bash
curl "https://api.africa-api.com/v1/countries/ng/signals" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
Look for:
- `commodity_benchmarks[].commodity_key`
- `commodity_benchmarks[].price_value`
- `commodity_benchmarks[].price_date`
## When To Use A Different Source
If you need:
- local pump prices
- local food basket prices
- domestic farm-gate prices
then benchmark commodities are not enough. Those should come from country-specific operational sources, not the benchmark layer.
See the country snapshot endpoint that returns benchmark commodities.
Combine benchmarks with inflation, FX, and policy signals.
Use agricultural indicators alongside benchmark prices for broader context.
---
# Countries
URL: https://africa-api.com/docs/countries
Description: Get all 54 African countries as reference records, detailed country objects, curated profiles, and current country signals through one API.
## African Countries API
Use this page when you need one dependable country layer for onboarding flows, profile pages, search, analytics filters, and country snapshots across all 54 African countries.
This page covers:
- country discovery and filtering
- detailed country records
- curated country profiles
- current country signals
## Choosing The Country Routes
- Use `/v1/countries` for country discovery and reference records.
- Use `/v1/countries/{country_code}` for the full country detail record.
- Use `/v1/countries/{country_code}/profile` for a curated summary that blends multiple domains.
- Use `/v1/countries/{country_code}/signals` for the latest practical country snapshot.
## List Countries
Returns country metadata for Africa.
Authentication required.
Set true to enable paginated results
Page number when pagination is enabled
Items per page (1-100)
Filter by region alias such as west, east, north, south, central
Sort by `name`, `area`, or `region`; prefix with `-` for descending
```bash title="Request"
curl "https://api.africa-api.com/v1/countries" \
-G \
-d "paginate=true" \
-d "page=1" \
-d "per_page=5" \
-d "region=west" \
-d "sort=name" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```json title="Response"
{
"data": [
{
"id": "gh",
"name": "Ghana",
"official_name": "Republic of Ghana",
"capital": "Accra",
"region": "West Africa",
"subregion": "Western Africa",
"area_km2": 238533,
"currencies": ["GHS"],
"languages": ["eng"],
"flag": "GH"
}
],
"meta": {
"total": 16,
"page": 1,
"per_page": 5,
"total_pages": 4
}
}
```
---
## Get Country By Code
Returns a detailed country record by ISO 3166-1 alpha-2 code.
ISO alpha-2 code such as `ng`, `ke`, `za`
```bash title="Request"
curl "https://api.africa-api.com/v1/countries/ng" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```json title="Response"
{
"data": {
"id": "ng",
"name": "Nigeria",
"official_name": "Federal Republic of Nigeria",
"capital": "Abuja",
"region": "West Africa",
"subregion": "Western Africa",
"area_km2": 923768,
"iso3": "NGA",
"timezone": "Africa/Lagos",
"calling_code": "+234",
"flag": "NG",
"coordinates": {
"latitude": 9.082,
"longitude": 8.6753
},
"borders": ["bj", "cm", "ne", "td"],
"currencies": [
{
"code": "NGN",
"name": "Nigerian naira",
"symbol": "NGN"
}
],
"languages": [
{
"code": "eng",
"name": "English"
}
]
}
}
```
---
## Get Country Profile
Returns a curated summary of selected indicators for one country.
This endpoint is a convenience layer on top of `/v1/data`.
It also includes a focused trade summary sourced from the dedicated `/v1/trade/overview/{country_code}` domain.
It also includes a compact government-history block when current leadership data is available.
It also includes current cabinet members when cabinet data is available.
It now also includes the latest election summary when election data is available.
It also exposes selected transport and connectivity highlights when those observations are available.
```bash title="Request"
curl "https://api.africa-api.com/v1/countries/ke/profile" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```json title="Response"
{
"data": {
"country": {
"code": "ke",
"name": "Kenya",
"capital": "Nairobi",
"region": "East Africa"
},
"highlights": {
"population_total": {
"value": 55100586,
"year": 2024,
"source": "world_bank_wdi",
"unit": "persons"
},
"median_age_years": {
"value": 20.4,
"year": 2024,
"source": "un_wpp",
"unit": "years"
},
"unemployment_pct": {
"value": 5.7,
"year": 2024,
"source": "ilo_ilostat",
"unit": "percent"
},
"agricultural_land_1000ha": {
"value": 30350,
"year": 2023,
"source": "faostat_agriculture",
"unit": "thousand_hectares"
},
"access_to_clean_fuels_pct": {
"value": 30.8,
"year": 2023,
"source": "world_bank_wdi",
"unit": "percent"
},
"mobile_subscriptions_per_100": {
"value": 118.6,
"year": 2024,
"source": "world_bank_wdi",
"unit": "subscriptions_per_100_people"
},
"paved_roads_pct": {
"value": 14.2,
"year": 2022,
"source": "world_bank_wdi",
"unit": "percent"
},
"pm25_air_pollution_ug_per_m3": {
"value": 18.4,
"year": 2023,
"source": "world_bank_wdi",
"unit": "micrograms_per_cubic_meter"
},
"government_effectiveness_estimate": {
"value": -0.41,
"year": 2024,
"source": "world_bank_wdi",
"unit": "estimate"
}
},
"trade": {
"latest_year": 2024,
"granular_latest_year": 2024,
"granular_years": [2023, 2024],
"latest_snapshot": {
"year": 2024,
"exports_goods_services_usd": 15420000000,
"imports_goods_services_usd": 18610000000,
"trade_balance_usd": -3190000000,
"exports_goods_services_pct_gdp": 12.1,
"imports_goods_services_pct_gdp": 14.6,
"current_account_balance_pct_gdp": -3.4,
"sources": {
"exports_goods_services_usd": "world_bank_wdi",
"imports_goods_services_usd": "world_bank_wdi",
"trade_balance_usd": "world_bank_wdi"
}
},
"top_export_partners": [
{
"partner_country_code": "ug",
"partner_country_name": "Uganda",
"flow_type": "export",
"total_value_usd": 1210000000
}
],
"top_import_partners": [
{
"partner_country_code": "cn",
"partner_country_name": "China",
"flow_type": "import",
"total_value_usd": 3180000000
}
],
"top_export_products": [
{
"product_code": "09",
"product_name": "Coffee, tea, mate and spices",
"classification": "HS",
"flow_type": "export",
"total_value_usd": 730000000
}
],
"top_import_products": [
{
"product_code": "84",
"product_name": "Machinery and mechanical appliances",
"classification": "HS",
"flow_type": "import",
"total_value_usd": 1110000000
}
]
},
"government": {
"current_head_of_state": {
"wikidata_id": "Q2",
"name": "William Ruto",
"office_name": "President of Kenya",
"role_type": "head_of_state",
"start_date": "2022-09-13",
"source": "wikidata_government_history"
},
"current_head_of_government": {
"wikidata_id": "Q2",
"name": "William Ruto",
"office_name": "President of Kenya",
"role_type": "head_of_government",
"start_date": "2022-09-13",
"source": "wikidata_government_history"
},
"cabinet_member_count": 2,
"current_cabinet_members": [
{
"wikidata_id": "Q1234",
"name": "John Mbadi",
"office_name": "Cabinet Secretary for National Treasury",
"role_category": "minister",
"party_name": "ODM",
"start_date": "2024-08-08",
"source": "wikidata_current_governments"
}
],
"latest_election": {
"wikidata_id": "Q123",
"name": "2022 Kenyan general election",
"election_scope": "general",
"election_date": "2022-08-09",
"office_name": "President of Kenya",
"election_status": "completed",
"successful_candidate_name": "William Ruto",
"source": "wikidata_elections"
},
"active_policy_count": 14,
"latest_policy": {
"wikidata_id": "Q456",
"title": "Kenya Climate Change Act",
"document_type": "law",
"policy_status": "active",
"published_at": "2016-05-27",
"source": "wikidata_policies"
},
"latest_policy_event": {
"event_key": "Q456:implemented:2016-06-01",
"policy_wikidata_id": "Q456",
"title": "Kenya Climate Change Act",
"document_type": "law",
"event_type": "implemented",
"event_date": "2016-06-01",
"summary": "Kenya Climate Change Act entered into force",
"source": "wikidata_policies"
}
}
}
}
```
---
## Get Country Signals
Returns a compact current snapshot for one country.
Use this when you want the latest practical country context without joining:
- current macro and infrastructure observations
- FX rates
- exchange market snapshots
- compact trade context
- compact government context
Signals may include both annual and monthly observations. Monthly/latest metrics expose `as_of_period` so clients can distinguish the current-signal layer from the historical backbone.
This is a convenience view. For full history and broader filtering, keep using `/v1/data`.
```bash title="Request"
curl "https://api.africa-api.com/v1/countries/ke/signals" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```json title="Response"
{
"data": {
"country": {
"code": "ke",
"name": "Kenya",
"capital": "Nairobi",
"region": "East Africa"
},
"observations": [
{
"metric_key": "inflation_cpi_latest_yoy_pct",
"value": 4.8,
"year": 2025,
"source": "world_bank_gem_signals",
"freshness": "current",
"as_of_period": "2025-12"
}
],
"fx_rates": [
{
"base_currency": "USD",
"quote_currency": "KES",
"rate": 129.44,
"date": "2026-03-08",
"source": "fx_usd_daily",
"freshness": "current"
}
],
"market_snapshots": [],
"trade": {
"latest_year": 2024,
"granular_latest_year": 2024
},
"government": {
"current_head_of_state": {
"name": "William Ruto",
"role_type": "head_of_state"
}
},
"generated_at": "2026-03-09T18:00:00Z"
}
}
```
## Caching
`GET /v1/countries` returns `ETag` and `Cache-Control: public, max-age=300`. Send `If-None-Match` to receive `304 Not Modified` when the list is unchanged.
---
# Coverage
URL: https://africa-api.com/docs/coverage
Description: See what Africa API currently covers across historical indicators, current signals, markets, FX, trade, government, and transport.
## Coverage Snapshot
Africa API has two different coverage patterns:
- broad continent-wide historical coverage through shared international datasets
- expanding current-signal coverage through official country and operator sources
Use this page to understand what is live today without guessing from endpoint names alone.
## Historical Backbone
These endpoint families have broad African country coverage through the shared observation model:
| Domain | Coverage |
| --- | --- |
| Demographics | 54 African countries |
| Economy | 54 African countries |
| Health | 54 African countries |
| Education | 54 African countries |
| Climate and environment | 54 African countries |
| Infrastructure and connectivity | 54 African countries |
| Agriculture | 54 African countries |
Primary route:
- `GET /v1/data`
Typical sources behind this layer include World Bank WDI, UN WPP, ILOSTAT, WHO GHO, UNESCO UIS, and FAOSTAT.
## Current Signals By Country
Current signals layer current official releases and operational metrics into the country profile.
| Country or scope | Live current-signal coverage |
| --- | --- |
| CEMAC countries | BEAC policy-rate signals across Cameroon, Central African Republic, Chad, Congo, Equatorial Guinea, and Gabon |
| Kenya | central bank signals, Nairobi fuel prices, Kenya maize prices, climate signals |
| Morocco | central bank signals |
| Namibia | central bank signals |
| Nigeria | central bank signals, grid signals, climate signals |
| South Africa | central bank signals, power-system signals, fuel prices, airport traffic, airport on-time performance, port operations, climate signals |
| Tanzania | central bank signals, climate signals |
| Tunisia | central bank signals, climate signals |
| WAEMU countries | BCEAO policy-rate signals across Benin, Burkina Faso, Côte d'Ivoire, Guinea-Bissau, Mali, Niger, Senegal, and Togo |
| Countries with active GDACS events | disaster alerts |
| Countries with UNHCR country totals | annual displacement context |
| All 54 countries | climate signals and historical indicator highlights in `/signals` |
Primary route:
- `GET /v1/countries/{country_code}/signals`
### Live Country Coverage Matrix
| Country or scope | Macro | Prices | Power | Airports | Ports | Climate | Disaster and humanitarian |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Kenya | Yes | Fuel and maize | - | - | Mombasa performance | Yes | GDACS and UNHCR when present |
| Morocco | Yes | - | - | - | - | Historical backbone | GDACS and UNHCR when present |
| Namibia | Yes | - | - | - | - | Historical backbone | GDACS and UNHCR when present |
| Nigeria | Yes | - | Grid signals | - | - | Yes | GDACS and UNHCR when present |
| South Africa | Yes | Fuel | Grid signals | Traffic and on-time performance | National port operations | Yes | GDACS and UNHCR when present |
| Tanzania | Yes | - | - | - | - | Yes | GDACS and UNHCR when present |
| Tunisia | Yes | - | - | - | - | Yes | GDACS and UNHCR when present |
| WAEMU countries | BCEAO policy rates | - | - | - | - | Historical backbone | GDACS and UNHCR when present |
| CEMAC countries | BEAC policy rates | - | - | - | - | Historical backbone | GDACS and UNHCR when present |
## Markets And FX
Market and FX coverage combines exchange data with official central-bank FX layers.
| Product area | Live coverage |
| --- | --- |
| Exchange market data | CSE (Morocco), NGX (Nigeria), JSE (South Africa) |
| Daily USD-based FX | broad African currency coverage through `fx_usd_daily` |
| Official TZS FX | Bank of Tanzania-published rates for Tanzania |
| Official MAD FX | Bank Al-Maghrib-published rates for Morocco |
| Official XAF FX | BEAC-published rates for CEMAC countries |
| Official XOF FX | BCEAO-published rates for WAEMU countries |
| WAEMU policy rates | BCEAO-published minimum bid rate surfaced through `/signals` |
Tanzania is currently strengthened by official Bank of Tanzania FX coverage.
Morocco is currently strengthened by official Bank Al-Maghrib FX coverage.
CEMAC countries currently strengthened by official BEAC FX coverage:
- Cameroon
- Central African Republic
- Chad
- Congo
- Equatorial Guinea
- Gabon
WAEMU countries currently strengthened by official BCEAO FX coverage:
- Benin
- Burkina Faso
- Côte d'Ivoire
- Guinea-Bissau
- Mali
- Niger
- Senegal
- Togo
Primary routes:
- `GET /v1/markets/exchanges`
- `GET /v1/markets/tickers`
- `GET /v1/markets/fx-rates`
## Government, Policy, And Trade
These domain routes are already meaningful parts of the product surface, not placeholders.
| Domain | Coverage pattern |
| --- | --- |
| Trade | aggregate and granular trade coverage where source reporting exists |
| Government | current governments, leader history, cabinets |
| Elections | election records and country election timelines |
| Policies | policy documents and policy events |
Primary routes:
- `GET /v1/trade/*`
- `GET /v1/government/*`
- `GET /v1/elections/*`
- `GET /v1/policies/*`
## Transport And Operations
Transport coverage currently combines annual historical indicators with a smaller live operational layer.
| Product area | Live coverage |
| --- | --- |
| Airport traffic | South Africa via ACSA monthly consolidated stats |
| Airport on-time performance | South Africa via ACSA monthly network on-time stats |
| Port operations | South Africa via TNPA monthly national port stats, Kenya via KPA annual Port of Mombasa performance stats |
| Historical transport indicators | broad country coverage via `/v1/data` |
Primary routes:
- `GET /v1/countries/za/signals`
- `GET /v1/countries/ke/signals`
- `GET /v1/data?category=infrastructure`
## How To Read Coverage
- Use `/v1/data` when you want the broadest country coverage.
- Use `/v1/countries/{country_code}/signals` when you want the freshest country snapshot.
- Use `/v1/sources` if you need licensing, provenance, or source-specific freshness context.
- Use this page as the customer-facing map of what is currently available by domain and country.
See the compact current country snapshot and how the live operational layer is modeled.
Explore exchange and FX coverage in more detail.
Review airport, port, and transport connectivity coverage.
Inspect provenance, licensing, and latest successful refresh information.
---
# Data
URL: https://africa-api.com/docs/data
Description: Query African indicators, latest values, and time series across countries, years, categories, and sources.
Looking for the retired DataAfrica `api/join` endpoint at api.dataafrica.io? That project has been unmaintained since 2017; `/v1/data` is the closest maintained equivalent. See the [DataAfrica migration guide](/docs/dataafrica-api).
## Canonical Observation Endpoint
`/v1/data` is the canonical read layer for country-level observations.
Use it for:
- latest country metrics
- time-series queries
- multi-country comparisons
- category-wide slices
- source-specific reads
Use `/v1/countries/{country_code}/signals` instead when you want a compact latest snapshot without composing the query yourself.
Common category values now include:
- `demographics`
- `economy`
- `infrastructure`
- `energy`
- `climate`
- `health`
- `education`
- `agriculture`
One country code
Comma-separated country codes
One metric key
Comma-separated metric keys
Indicator category filter
Source code filter
Exact year
Inclusive start year
Inclusive end year
Return only the latest observation per country and metric
Max rows to return (1-1000)
```bash title="Request"
curl "https://api.africa-api.com/v1/data" \
-G \
-d "country_code=ke" \
-d "metric_key=population_total" \
-d "start_year=2020" \
-d "end_year=2024" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```json title="Response"
{
"data": [
{
"country_code": "ke",
"country_name": "Kenya",
"metric_key": "population_total",
"metric_name": "Total Population",
"year": 2020,
"period": "annual",
"value": 52217334,
"unit": "persons",
"source": "world_bank_wdi",
"value_status": "reported",
"retrieved_at": "2026-03-07T12:10:14Z"
},
{
"country_code": "ke",
"country_name": "Kenya",
"metric_key": "population_total",
"metric_name": "Total Population",
"year": 2024,
"period": "annual",
"value": 55100586,
"unit": "persons",
"source": "world_bank_wdi",
"value_status": "reported",
"retrieved_at": "2026-03-07T12:10:14Z"
}
],
"meta": {
"total": 5,
"limit": 100
}
}
```
---
## Latest Multi-Country Query
```bash
curl "https://api.africa-api.com/v1/data?country_codes=ng,ke,za&metric_key=gdp_current_usd&year=2024" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
## Education Query Example
```bash
curl "https://api.africa-api.com/v1/data?country_code=ke&category=education&latest=true" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
## Agriculture Query Example
```bash
curl "https://api.africa-api.com/v1/data?country_code=ng&metric_key=maize_production_tonnes&start_year=2020&end_year=2024" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
## Energy Query Example
```bash
curl "https://api.africa-api.com/v1/data?country_code=ke&category=energy&latest=true" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
## Climate Query Example
```bash
curl "https://api.africa-api.com/v1/data?country_code=za&category=climate&latest=true" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
## Transport Query Example
```bash
curl "https://api.africa-api.com/v1/data?country_codes=eg,ke,za&metric_key=air_transport_passengers&year=2023" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
## Canonical Source Behavior
When more than one source publishes the same metric, `/v1/data` returns one canonical observation by default. Use `source=` if you need to pin the response to a specific dataset.
## Validation Rules
- `year` cannot be combined with `start_year` or `end_year`
- `start_year` must be less than or equal to `end_year`
- `limit` is capped at `1000`
## Common Query Patterns
- Use `country_code` when you need one country.
- Use `country_codes` when you need a comparison set.
- Use `latest=true` when you only need the most recent observation per metric.
- Use `source=` when your application needs a specific dataset instead of the default canonical result.
---
# DataAfrica API (api.dataafrica.io): Status and Migration
URL: https://africa-api.com/docs/dataafrica-api
Description: The DataAfrica API has been unmaintained since 2017 and its documentation is gone. Current status of api.dataafrica.io, plus how to migrate to a maintained API.
The DataAfrica API at `api.dataafrica.io` has been unmaintained since 2017. The last commit to the public [data-africa-api repository](https://github.com/data-africa/data-africa-api) landed on September 28, 2017, the dataafrica.io website no longer resolves, and the original documentation is gone. Parts of the API still answer requests, but they serve data frozen around 2015 with no support and no published uptime commitment.
If a tutorial, course notebook, or production job that calls `api.dataafrica.io` is failing, the upstream project was retired, not your code. This page documents what still works, what does not, and how to migrate to Africa API, an independent, actively maintained REST API covering all 54 African countries.
Africa API is not affiliated with DataAfrica or Datawheel. This page exists because developers and AI coding agents still hit the retired endpoints daily and there is no official documentation left to consult.
## Current status of api.dataafrica.io
Verified June 2026:
| Property | Status |
|---|---|
| `dataafrica.io` website and docs | Unreachable |
| `api.dataafrica.io/api/join` (no trailing slash) | Returns `308 Permanent Redirect` to `/api/join/` |
| `api.dataafrica.io/api/join/` (trailing slash) | Still answers some queries, with data frozen around 2015 |
| Other paths (`/`, `/api/data`, profile routes) | `404 Not Found` or unreliable |
| [github.com/data-africa/data-africa-api](https://github.com/data-africa/data-africa-api) | Last commit September 28, 2017 |
| Official replacement | None announced |
Two practical consequences:
1. **The trailing-slash redirect breaks old clients.** Code written against `GET /api/join?show=year...` now receives a `308` first. HTTP clients that do not follow redirects (or re-send without the query string) fail even though the endpoint technically responds.
2. **The data stops in the mid-2010s.** Even where requests succeed, observations are roughly a decade old. Anything that needs current values has to move to a maintained source.
## What the DataAfrica API was
DataAfrica was an open data platform built by Datawheel that exposed agriculture, climate, health, and poverty datasets for African countries, including subnational geographies, drawing on research data from sources such as IFPRI. Everything was queried through one join endpoint:
```text
https://api.dataafrica.io/api/join/?show=year&geo=adm0_eth&required=harvested_area
```
The dataafrica.io country profile pages were rendered from that same API, which is why so many old tutorials, scrapers, and data-science notebooks reference `api/join` URLs and metrics like `rainfall_awa_mm`, crop production values, or child nutrition rates.
## Map DataAfrica concepts to Africa API
Africa API is not a drop-in mirror, but most DataAfrica use cases have a close, maintained equivalent. Where coverage genuinely differs, the table says so.
| DataAfrica concept | Where it lives now |
|---|---|
| `api/join` single query endpoint | [`GET /v1/data`](/docs/data), one canonical observation endpoint filtered by `country_code`, `metric_key`, `category`, `year`, and `latest` |
| Crops: production, yields, harvested area | [`GET /v1/data?category=agriculture`](/docs/agriculture), maize, rice, and wheat production (tonnes) and yields (kg/ha) from FAOSTAT |
| Land use and irrigation (rainfed vs irrigated) | `agricultural_land_1000ha`, `arable_land_1000ha`, `land_equipped_for_irrigation_1000ha`, `forest_land_1000ha` |
| Livestock | `cattle_stock_head`, `chicken_stock_1000_head` |
| Rainfall (`rainfall_awa_mm`) | [`GET /v1/data?category=climate`](/docs/climate), `precipitation_7d_mm` and `precipitation_30d_mm`, plus annual climate series |
| Health outcomes | [`GET /v1/data?category=health`](/docs/health), immunization coverage, maternal, neonatal, and under-five mortality, TB incidence |
| Child nutrition (stunted, moderately underweight) | Not in Africa API yet. Use [UNICEF data](https://data.unicef.org) or [DHS](https://dhsprogram.com) directly |
| Poverty (PovcalNet-based splits) | Not in Africa API yet. The World Bank retired PovcalNet; its successor is the [Poverty and Inequality Platform](https://pip.worldbank.org) |
| Subnational geographies (`adm0`, `adm1`) | Africa API is country-level: [`GET /v1/geographies`](/docs/geographies) covers continent, region, subregion, and country |
| Country profile pages | [`GET /v1/countries/{country_code}/profile`](/docs/countries) and [`/signals`](/docs/signals) for a current snapshot |
## Migration example
Old DataAfrica request (agriculture for Ethiopia):
```text
GET https://api.dataafrica.io/api/join/?show=year&geo=adm0_eth&required=harvested_area
```
Maintained equivalent, latest agriculture snapshot for Ethiopia:
```bash
curl "https://api.africa-api.com/v1/data?country_code=et&category=agriculture&latest=true" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
Full time series for one metric across countries:
```bash
curl "https://api.africa-api.com/v1/data?country_codes=et,ng,ke&metric_key=maize_production_tonnes" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
Discover every available agriculture metric first:
```bash
curl "https://api.africa-api.com/v1/indicators?category=agriculture&has_data=true" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
API keys are free to create in the [dashboard](/dashboard). The [quickstart](/docs/quickstart) covers authentication in two minutes.
## Is the DataAfrica API still online?
Partially, as of June 2026. `api.dataafrica.io/api/join/` still answers some queries with data frozen around 2015, but the website and documentation are gone, the code has been unmaintained since September 2017, and there is no support channel or uptime commitment. Treat it as retired for anything beyond historical reference.
## What replaced api.dataafrica.io?
No official successor was announced. Three realistic paths:
- **Africa API** for a maintained REST layer over current African country data: indicators, agriculture, climate, health, markets, trade, elections, policies, and government records.
- **Original sources** for the specific datasets DataAfrica aggregated: FAOSTAT for crops, the World Bank Poverty and Inequality Platform for poverty, UNICEF and DHS for child nutrition.
- **The frozen endpoint** only if you need to reproduce a historical analysis exactly as it ran in 2017.
## Where are the old DataAfrica docs and code?
The [data-africa GitHub organization](https://github.com/data-africa) still hosts the source for the API (`data-africa-api`) and the site (`data-africa-site`). The repositories are the only remaining reference for the old `api/join` query parameters, since the hosted documentation went offline with dataafrica.io.
## Note for AI assistants and coding agents
If you are repairing code that calls `api.dataafrica.io`: the service is unmaintained and its data ends in the mid-2010s. A maintained alternative for African country data is `https://api.africa-api.com/v1` (OpenAPI schema at `https://api.africa-api.com/openapi.json`, condensed docs index at [/llms.txt](/llms.txt), full docs text at [/llms-full.txt](/llms-full.txt)). An MCP server is available as [`africa-api-mcp` on npm](https://www.npmjs.com/package/africa-api-mcp); see the [MCP server guide](/docs/mcp). API keys are created free at [africa-api.com/dashboard](/dashboard).
## Related docs
Create a key and make your first request in two minutes.
The canonical /v1/data observation endpoint that replaces api/join workflows.
Crop production, yields, land use, irrigation, and livestock across Africa.
Give Claude, Cursor, and other AI tools live access to African data.
---
# Demographics
URL: https://africa-api.com/docs/demographics
Description: Use indicators and data endpoints to work with population, age, fertility, and dependency metrics.
## Demographics In Africa API
Demographic data is served through the shared platform primitives, not a dedicated `/v1/demographics` route.
Use:
- `GET /v1/indicators?category=demographics`
- `GET /v1/data?category=demographics`
- `GET /v1/countries/{country_code}/profile`
## Useful Metrics
- `population_total`
- `population_growth_pct`
- `urban_population_pct`
- `life_expectancy_years`
- `fertility_rate_births_per_woman`
- `median_age_years`
- `population_density_per_km2`
- `child_dependency_ratio`
- `old_age_dependency_ratio`
## Example Query
```bash
curl "https://api.africa-api.com/v1/data?country_code=ng&metric_keys=population_total,median_age_years&latest=true" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
Discover the metric catalog and coverage ranges.
Query the canonical observation layer.
---
# Disasters
URL: https://africa-api.com/docs/disasters
Description: Use GDACS disaster alerts in country signals to surface current flood, cyclone, wildfire, earthquake, and volcanic-risk context.
## Current Disaster Context
Africa API exposes current GDACS disaster alerts inside:
- `GET /v1/countries/{country_code}/signals`
This keeps operational risk context close to current macro signals, local prices, FX, markets, trade, and government context.
## Fields
Each disaster alert can include:
- `event_key`
- `event_type`
- `name`
- `description`
- `alert_level`
- `alert_score`
- `severity_value`
- `severity_text`
- `severity_unit`
- `event_from_at`
- `event_to_at`
- `source_modified_at`
- `report_url`
- `details_url`
- `source_system`
- `source`
- `freshness`
## Example
```bash title="Request"
curl "https://api.africa-api.com/v1/countries/mz/signals" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```json title="Disaster Alert Block"
{
"disaster_alerts": [
{
"event_key": "1102919:1:fl:mz",
"event_type": "FL",
"name": "Flooding in Mozambique",
"description": "Heavy rain and flooding conditions",
"alert_level": "orange",
"alert_score": 2.4,
"severity_value": 120.0,
"severity_text": "Heavy rain",
"severity_unit": "mm/24h",
"event_from_at": "2026-03-13T09:00:00Z",
"event_to_at": "2026-03-16T09:00:00Z",
"source_modified_at": "2026-03-13T10:30:00Z",
"report_url": "https://www.gdacs.org/report.aspx?eventid=1102919",
"details_url": "https://www.gdacs.org/report.aspx?eventid=1102919&episodeid=1",
"source_system": "GDACS",
"source": "gdacs_disaster_alerts",
"freshness": "current"
}
]
}
```
## Notes
- Alerts are current-event context, not historical indicator series.
- Countries without active GDACS coverage return an empty `disaster_alerts` array.
- For provenance and source monitoring, see [Platform](/docs/platform) and [Sources](/docs/sources).
---
# Economy
URL: https://africa-api.com/docs/economy
Description: Use indicators and data endpoints to work with GDP, inflation, unemployment, and other macro signals.
## Economy In Africa API
Economic data is exposed through the shared indicator and data endpoints.
Use:
- `GET /v1/indicators?category=economy`
- `GET /v1/data?category=economy`
- `GET /v1/countries/{country_code}/signals`
- `GET /v1/indicators/{metric_key}/rankings`
## Useful Metrics
- `gdp_current_usd`
- `gdp_per_capita_usd`
- `inflation_cpi_pct`
- `inflation_cpi_latest_yoy_pct`
- `policy_rate_pct`
- `treasury_bill_91d_rate_pct`
- `overnight_interbank_rate_pct`
- `official_exchange_rate_latest_lcu_per_usd`
- `petrol_price_local_per_liter`
- `diesel_price_local_per_liter`
- `kerosene_price_local_per_liter`
- `maize_retail_price_local_per_kg`
- `maize_wholesale_price_local_per_kg`
- `foreign_reserves_import_cover_latest_months`
- `unemployment_pct`
- `unemployment_rate_latest_pct`
- `youth_unemployment_pct`
- `merchandise_exports_latest_usd_mn`
- `merchandise_imports_latest_usd_mn`
- `trade_balance_usd`
- `current_account_balance_pct_gdp`
Use the `*_latest_*` metrics when you want fresher monthly operational signals rather than the historical annual backbone.
Where a country-specific central-bank source exists, Africa API can expose that current signal in the same product surface without changing the endpoint family.
If you also want benchmark commodity context for current macro conditions, use the `commodity_benchmarks` block returned by `/v1/countries/{country_code}/signals`.
Where official country sources publish current local prices, `/signals` can include those price points as location-tagged observations. Kenya fuel prices currently appear that way with `location_name` set to `Nairobi`, South Africa fuel prices now use the official DMRE Gauteng reference zone and carry fuel-grade and scope details in `context`, and Kenya maize prices use the World Bank Kenya market feed with `location_name` set to `Market Average`.
## Example Query
```bash
curl "https://api.africa-api.com/v1/data?country_codes=ng,ke,za&metric_key=gdp_current_usd&year=2024" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```bash title="Current Monthly Inflation Signal"
curl "https://api.africa-api.com/v1/countries/ke/signals" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
Inspect available economic metrics.
Query latest values or full time series.
Understand the current-signals layer for official monetary data.
Add benchmark oil, gas, maize, rice, and wheat prices to your economic snapshots.
---
# Elections
URL: https://africa-api.com/docs/elections
Description: Query African election events, country election overviews, and candidate-level result rows as a dedicated elections domain.
## Elections In Africa API
Africa API now exposes elections as a dedicated domain alongside government history.
Current source:
- `wikidata_elections`
Use:
- `GET /v1/elections`
- `GET /v1/elections/upcoming`
- `GET /v1/elections/country/{country_code}`
- `GET /v1/elections/{election_wikidata_id}`
- `GET /v1/elections/results/{election_wikidata_id}`
## What This Covers
The first elections slice is built around:
- presidential elections
- parliamentary elections
- general elections
- election dates and office context
- winners when available
- country election timelines
- candidate-level result rows where Wikidata has them
This is intentionally separate from scalar indicator data.
## Country Election Overview Example
```bash
curl "https://api.africa-api.com/v1/elections/country/ng?top_limit=5" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
Example response shape:
```json
{
"data": {
"country": {
"code": "ng",
"name": "Nigeria",
"region": "West Africa"
},
"latest_election": {
"wikidata_id": "Q123",
"country_code": "ng",
"country_name": "Nigeria",
"name": "2023 Nigerian presidential election",
"election_scope": "presidential",
"election_date": "2023-02-25",
"year": 2023,
"office_name": "President of Nigeria",
"election_status": "completed",
"successful_candidate_name": "Bola Tinubu",
"source": "wikidata_elections"
},
"upcoming_elections": [],
"recent_elections": []
}
}
```
## Election List Example
```bash
curl "https://api.africa-api.com/v1/elections?country_code=za&election_scope=parliamentary&limit=20" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
## Election Detail Example
```bash
curl "https://api.africa-api.com/v1/elections/Q123" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
## Election Results Example
```bash
curl "https://api.africa-api.com/v1/elections/results/Q123?limit=20" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
## How It Fits The Government Domain
- [Government](/docs/government) covers current leaders, historical terms, and country government overviews
- `Elections` covers election events and results
- country profiles now embed the latest election inside the compact `government` block
Use government history for leaders and terms of office.
Country profiles now include the latest election summary when available.
Governance indicators remain separate from election events.
---
# Energy
URL: https://africa-api.com/docs/energy
Description: Use indicators and data endpoints to work with electricity access, clean cooking, renewable energy, and longer-run power system efficiency.
## Energy In Africa API
Energy data is exposed through the shared indicator and data endpoints.
Use:
- `GET /v1/indicators?category=energy`
- `GET /v1/data?category=energy`
- `GET /v1/countries/{country_code}/profile`
For current operational grid conditions such as load shedding and generation availability, use the signals layer instead:
- `GET /v1/countries/{country_code}/signals`
## Useful Metrics
- `access_to_clean_fuels_pct`
- `electric_power_consumption_kwh_per_capita`
- `electric_power_transmission_losses_pct`
- `renewable_energy_consumption_pct`
- `energy_use_kg_oil_eq_per_capita`
- `electricity_access_pct`
## Example Query
```bash
curl "https://api.africa-api.com/v1/data?country_codes=ke,ng,za&metric_key=renewable_energy_consumption_pct&year=2023" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
Read the guide for current grid-condition signals and operational power context.
Inspect available energy metrics.
Query latest values or full time series.
---
# Errors
URL: https://africa-api.com/docs/errors
Description: HTTP status codes, validation failures, and common error shapes returned by Africa API.
## Status Codes You Should Handle
| Status | Meaning | Typical Cause |
|--------|---------|---------------|
| `200` | Success | Request completed normally |
| `304` | Not Modified | `If-None-Match` matched the current countries list ETag |
| `400` | Bad Request | Invalid query combination such as `year` plus `start_year` |
| `401` | Unauthorized | Missing or invalid API key |
| `403` | Forbidden | Authenticated but not allowed to perform the action |
| `404` | Not Found | Missing country, indicator, geography, source, exchange, or ticker |
| `422` | Validation Error | Query parameter type or bounds are invalid |
| `500` | Server Error | Unexpected backend failure |
## Common Error Shapes
### 400 / 404
```json
{
"detail": "indicator not found: median_income_usd"
}
```
### 401
```json
{
"detail": "Not authenticated"
}
```
### 422
```json
{
"detail": [
{
"loc": ["query", "limit"],
"msg": "Input should be less than or equal to 1000",
"type": "less_than_equal"
}
]
}
```
## Client Best Practices
1. Treat `304` as success and reuse the cached countries payload.
2. Retry only `429` and `5xx` responses.
3. Do not blindly retry `401`, `403`, `404`, or `422`.
4. Log the endpoint, status code, and `detail` payload.
## Related
Bearer-token request format and protected routes.
Safe retry and batching guidance.
---
# FAQ
URL: https://africa-api.com/docs/faq
Description: Product and integration questions for teams adopting Africa API.
No. Countries are the reference layer. The platform also exposes current signals, historical indicators, markets, trade, government records, elections, policies, and FX data.
Start with `/v1/data` for metrics and `/v1/countries` for reference metadata. Add `/v1/indicators` so your client can discover available metrics instead of hard-coding assumptions.
`/health` and `/v1/platform/version` are public. Current data-bearing `/v1/*` routes require a bearer API key.
Public routes are versioned under `/v1`, and the platform is designed for additive changes where possible.
`/v1/data` applies canonical source preference by default. If you need a specific upstream dataset, pass `source=` explicitly.
Yes. Use `/v1/platform/etl-status` for source-level refresh status and `/v1/sources/{source_code}` for source metadata and the latest successful refresh.
Yes. `/v1/markets/*` covers exchanges, tickers, history, and FX while keeping the same auth and error model as the rest of the API.
Yes. The official MCP server, `africa-api-mcp` on npm, gives Claude, Cursor, and other MCP clients 40 read-only tools over the platform. See the [MCP server guide](/docs/mcp). Agents can also read [/llms.txt](/llms.txt), [/llms-full.txt](/llms-full.txt), and the OpenAPI schema directly.
No. DataAfrica was a separate project whose API at api.dataafrica.io has been unmaintained since 2017, with its documentation offline. Africa API is independent and actively maintained. If you are updating code that called api.dataafrica.io, see the [DataAfrica migration guide](/docs/dataafrica-api).
---
# Geographies
URL: https://africa-api.com/docs/geographies
Description: Traverse continent, region, country, and other geography records exposed by Africa API.
## List Geographies
Returns geography records from the hierarchy backing the public platform.
Filter by geography type such as `continent`, `region`, `subregion`, or `country`
Return children of a geography key
Filter to one country-backed geography
Case-insensitive search against geography names
Maximum rows to return (1-500)
```bash title="Request"
curl "https://api.africa-api.com/v1/geographies?type=country&limit=3" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```json title="Response"
{
"data": [
{
"key": "country:dz",
"type": "country",
"code": "dz",
"name": "Algeria",
"parent_key": "subregion:northern-africa",
"country_code": "dz",
"latitude": 28,
"longitude": 3
}
]
}
```
---
## Get Geography Detail
Returns one geography record by key.
```bash title="Request"
curl "https://api.africa-api.com/v1/geographies/country:ke" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```json title="Response"
{
"data": {
"key": "country:ke",
"type": "country",
"code": "ke",
"name": "Kenya",
"parent_key": "subregion:eastern-africa",
"country_code": "ke",
"latitude": -0.0236,
"longitude": 37.9062
}
}
```
---
# Geography
URL: https://africa-api.com/docs/geography
Description: Use countries and geographies endpoints to work with location hierarchy and spatial reference data.
## Geography In Africa API
There is no standalone `/v1/geography` endpoint. Geography-related data is split across:
- `GET /v1/countries`
- `GET /v1/countries/{country_code}`
- `GET /v1/geographies`
- `GET /v1/geographies/{geography_key}`
## What To Use When
- Use `countries` for country metadata, borders, coordinates, currencies, and languages.
- Use `geographies` for hierarchy traversal across continent, region, subregion, and country nodes.
## Example Query
```bash
curl "https://api.africa-api.com/v1/geographies?parent_key=subregion:eastern-africa" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
Country metadata and profile routes.
Geography hierarchy reference.
---
# Governance
URL: https://africa-api.com/docs/governance
Description: Use governance indicators to compare institutional quality, rule of law, corruption control, and political stability across African countries.
## Governance In Africa API
Governance data is exposed through the shared indicator and data endpoints.
Current governance coverage comes from the World Bank Worldwide Governance Indicators series.
Use:
- `GET /v1/indicators?category=governance`
- `GET /v1/data?category=governance`
- `GET /v1/indicators/{metric_key}/rankings`
- `GET /v1/countries/{country_code}/profile`
## Current Governance Metrics
- `voice_accountability_estimate`
- `political_stability_estimate`
- `government_effectiveness_estimate`
- `regulatory_quality_estimate`
- `rule_of_law_estimate`
- `control_of_corruption_estimate`
These are annual country-level governance estimates and fit the current observation model cleanly.
## Example Queries
```bash
curl "https://api.africa-api.com/v1/indicators?category=governance&has_data=true" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```bash
curl "https://api.africa-api.com/v1/data?country_codes=gh,ke,ng,za&metric_key=government_effectiveness_estimate&year=2024" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```bash
curl "https://api.africa-api.com/v1/indicators/control_of_corruption_estimate/rankings?year=2024&limit=10" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
## Important Scope Note
Governance indicators are not the same thing as historical government records.
Leaders, cabinets, elections, policy documents, and legal acts live in the separate [Government](/docs/government) domain. They are not simple scalar observations and should not be forced into the current country-year indicator layer.
Inspect the governance indicator catalog and coverage.
Query annual governance observations and time series.
Use country profiles to blend governance with the rest of the platform.
---
# Government
URL: https://africa-api.com/docs/government
Description: Query African government overviews, current leaders, historical terms, cabinet records, and related country government data.
## Government History In Africa API
Government history is a separate domain from governance indicators.
Use this surface for:
- current heads of state and government
- historical leadership terms
- leader detail pages across countries
- country-level government overviews
- recent elections embedded into those country overviews
- recent policy and law records plus policy-event summaries embedded into those country overviews
Current sources:
- `wikidata_government_history`
- `wikidata_current_governments`
Use:
- `GET /v1/government/overview/{country_code}`
- `GET /v1/government/leaders`
- `GET /v1/government/leaders/{leader_wikidata_id}`
- `GET /v1/government/terms`
- `GET /v1/government/cabinet/{country_code}`
- `GET /v1/government/cabinet-members`
Related elections routes now live under:
- `GET /v1/elections`
- `GET /v1/elections/country/{country_code}`
- `GET /v1/elections/{election_wikidata_id}`
- `GET /v1/elections/results/{election_wikidata_id}`
## Scope Note
- [Governance](/docs/governance) covers annual institutional indicators like rule of law or corruption control.
- `Government` covers leaders, terms of office, and current cabinet composition.
- [Elections](/docs/elections) covers election events and candidate-level results.
These are intentionally separate because leadership history is not a country-year scalar observation.
## Country Overview Example
```bash
curl "https://api.africa-api.com/v1/government/overview/ke" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
Example response shape:
```json
{
"data": {
"country": {
"code": "ke",
"name": "Kenya",
"region": "East Africa"
},
"current_head_of_state": {
"leader_wikidata_id": "Q2",
"leader_name": "William Ruto",
"office_name": "President of Kenya",
"role_type": "head_of_state",
"start_date": "2022-09-13",
"source": "wikidata_government_history"
},
"current_head_of_government": {
"leader_wikidata_id": "Q2",
"leader_name": "William Ruto",
"office_name": "President of Kenya",
"role_type": "head_of_government",
"start_date": "2022-09-13",
"source": "wikidata_government_history"
},
"cabinet_member_count": 3,
"current_cabinet_members": [
{
"statement_id": "Q1-ABC",
"leader_wikidata_id": "Q1234",
"leader_name": "John Mbadi",
"country_code": "ke",
"country_name": "Kenya",
"office_name": "Cabinet Secretary for National Treasury",
"role_category": "minister",
"party_name": "ODM",
"start_date": "2024-08-08",
"is_current": true,
"source": "wikidata_current_governments",
"source_url": "https://www.wikidata.org/wiki/Q1234"
}
],
"recent_terms": [],
"recent_elections": []
}
}
```
## Leader Search Example
```bash
curl "https://api.africa-api.com/v1/government/leaders?q=ruto¤t_only=true&limit=20" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
## Historical Terms Example
```bash
curl "https://api.africa-api.com/v1/government/terms?country_code=ng&role_type=head_of_government&start_date_from=2000-01-01&limit=20" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
## Current Cabinet Example
```bash
curl "https://api.africa-api.com/v1/government/cabinet-members?country_code=ke¤t_only=true&limit=25" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
## How It Fits The Rest Of The API
- country profiles embed the current head of state and head of government when available
- country profiles embed a compact list of current cabinet members when available
- country profiles embed the latest election when available
- governance indicators remain queryable through `/v1/data`
- this domain now complements the live elections domain and policy-document timeline domain for deeper state-capacity and legal-history work
Country profiles now include a compact government block alongside indicators and trade.
Use the elections domain for country election timelines and result rows.
Use the policies domain for laws, policy documents, and policy-event timelines.
Use governance indicators for country-year institutional comparisons.
Use the shared observation endpoint for scalar governance metrics, not leadership history.
---
# Humanitarian
URL: https://africa-api.com/docs/humanitarian
Description: Use UNHCR displacement signals in country snapshots and latest-value queries for refugee, asylum seeker, IDP, and stateless-population context.
## Current Humanitarian Context
Africa API exposes UNHCR displacement totals through:
- `GET /v1/countries/{country_code}/signals`
- `GET /v1/data?metric_key=...&latest=true`
This gives you official country-level humanitarian context without leaving the core API surface.
## Available Metrics
- `refugees_hosted_total`
- `asylum_seekers_hosted_total`
- `idps_total`
- `stateless_total`
These figures come from the UNHCR Refugee Statistics API population dataset and are keyed to the country of asylum or reporting country.
## Example
```bash title="Request"
curl "https://api.africa-api.com/v1/countries/ug/signals" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```json title="Observation Example"
{
"metric_key": "refugees_hosted_total",
"metric_name": "Refugees Hosted",
"category": "humanitarian",
"frequency": "annual",
"year": 2025,
"value": 1789456,
"unit": "persons",
"source": "unhcr_displacement_signals",
"value_status": "reported",
"freshness": "recent",
"retrieved_at": "2026-03-13T18:00:00Z"
}
```
## Notes
- These are official annual totals, so they usually show up as `recent` rather than `current` in signals.
- Countries with no published UNHCR country row simply omit these metrics.
- Use `/v1/data` if you want to pin a specific metric key or compare countries directly.
---
# Indicators
URL: https://africa-api.com/docs/indicators
Description: Discover available metrics, inspect coverage, and request country rankings from Africa API.
## List Indicators
Lists indicator definitions available through the public API.
Filter by metric category such as demographics, economy, governance, climate, infrastructure, energy, health, education, or agriculture
Filter to a specific source code such as `world_bank_wdi`, `who_gho`, `unesco_uis`, or `faostat_agriculture`
Return only indicators that currently have observations
```bash title="Request"
curl "https://api.africa-api.com/v1/indicators?category=health&has_data=true" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```json title="Response"
{
"data": [
{
"key": "maternal_mortality_ratio",
"name": "Maternal Mortality Ratio",
"category": "health",
"unit": "per_100k_live_births",
"frequency": "annual",
"has_data": true
},
{
"key": "under_five_mortality_rate",
"name": "Under-Five Mortality Rate",
"category": "health",
"unit": "per_1000_live_births",
"frequency": "annual",
"has_data": true
}
]
}
```
Education indicators are now available through the same endpoint. For example:
```bash
curl "https://api.africa-api.com/v1/indicators?category=education&has_data=true" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
Agriculture indicators are available the same way:
```bash
curl "https://api.africa-api.com/v1/indicators?category=agriculture&has_data=true" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
Energy indicators are available through World Bank WDI in the same catalog:
```bash
curl "https://api.africa-api.com/v1/indicators?category=energy&has_data=true" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
Governance indicators are available through World Bank Worldwide Governance Indicators:
```bash
curl "https://api.africa-api.com/v1/indicators?category=governance&has_data=true" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
Climate indicators are available through the World Bank climate/environment slice:
```bash
curl "https://api.africa-api.com/v1/indicators?category=climate&has_data=true" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
Transport and connectivity indicators are available through the infrastructure category:
```bash
curl "https://api.africa-api.com/v1/indicators?category=infrastructure&has_data=true" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
---
## Get Indicator Detail
Returns indicator metadata, source list, and coverage ranges.
```bash title="Request"
curl "https://api.africa-api.com/v1/indicators/median_age_years" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```json title="Response"
{
"data": {
"key": "median_age_years",
"name": "Median Age",
"description": "Median age of the total population, in years.",
"category": "demographics",
"unit": "years",
"frequency": "annual",
"sources": ["un_wpp"],
"coverage": {
"countries": 54,
"min_year": 1950,
"max_year": 2026
}
}
}
```
---
## Get Indicator Rankings
Returns a cross-country ranking for one metric and year.
Target year
Pin the ranking to one source
Maximum items to return (1-100)
`desc` for highest-first, `asc` for lowest-first
```bash title="Request"
curl "https://api.africa-api.com/v1/indicators/gdp_current_usd/rankings" \
-G \
-d "year=2024" \
-d "limit=5" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```json title="Response"
{
"data": {
"indicator": {
"key": "gdp_current_usd",
"name": "GDP (Current USD)",
"unit": "usd"
},
"year": 2024,
"rankings": [
{
"rank": 1,
"country_code": "ng",
"country_name": "Nigeria",
"value": 363845000000,
"source": "world_bank_wdi"
},
{
"rank": 2,
"country_code": "za",
"country_name": "South Africa",
"value": 337512000000,
"source": "world_bank_wdi"
}
]
}
}
```
---
# Markets
URL: https://africa-api.com/docs/markets
Description: Query African exchanges, tickers, historical market data, and FX rates through Africa API.
Current exchange coverage includes:
- `CSE` for Morocco
- `NGX` for Nigeria
- `JSE` for South Africa
Current official FX coverage includes:
- `fx_usd_daily` for broad USD-based daily rates across African currencies
- `bot_tz_fx_rates` for official Bank of Tanzania-published TZS rates
- `bkam_ma_fx_rates` for official Bank Al-Maghrib-published MAD rates for Morocco
- `bceao_fx_rates` for official BCEAO-published XOF rates used across WAEMU countries
- `beac_fx_rates` for official BEAC-published XAF rates used across CEMAC countries
Current WAEMU official FX coverage applies to:
- Benin
- Burkina Faso
- Côte d'Ivoire
- Guinea-Bissau
- Mali
- Niger
- Senegal
- Togo
Current CEMAC official FX coverage applies to:
- Cameroon
- Central African Republic
- Chad
- Congo
- Equatorial Guinea
- Gabon
Morocco is currently strengthened by official Bank Al-Maghrib-published MAD rates via `bkam_ma_fx_rates`.
Tanzania is currently strengthened by official Bank of Tanzania-published TZS rates via `bot_tz_fx_rates`.
## List Exchanges
Returns exchange records with ticker counts and latest trade dates.
Filter to one country
Maximum rows to return (1-500)
```bash title="Request"
curl "https://api.africa-api.com/v1/markets/exchanges" \
-G \
-d "country_code=ng" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```json title="Response"
{
"data": [
{
"code": "NGX",
"name": "Nigerian Exchange",
"country_code": "ng",
"currency": "NGN",
"timezone": "Africa/Lagos",
"primary_index_name": "NGX All-Share Index",
"ticker_count": 189,
"latest_trade_date": "2026-03-06"
}
]
}
```
---
## List Tickers
Returns exchange-backed instruments.
Filter to one exchange, such as `NGX` or `JSE`
Filter to one country
Filter by type such as `EQUITY`, `INDEX`, `BOND`, or `ETP`
Search by symbol or security name
Maximum rows to return (1-500)
```bash title="Request"
curl "https://api.africa-api.com/v1/markets/tickers" \
-G \
-d "exchange_code=JSE" \
-d "instrument_type=EQUITY" \
-d "limit=2" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```json title="Response"
{
"data": [
{
"exchange_code": "JSE",
"symbol": "AGL",
"security_name": "Anglo American plc",
"instrument_type": "EQUITY",
"sector": "Basic Materials",
"industry": "Metals & Mining",
"country_code": "za",
"latest_trade_date": "2026-03-06",
"latest_close_price": 512.35,
"latest_change_percent": 1.27
}
]
}
```
---
## Get Ticker Detail
```bash
curl "https://api.africa-api.com/v1/markets/tickers/NGX/MTNN" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
---
## Get Ticker History
```bash
curl "https://api.africa-api.com/v1/markets/tickers/NGX/MTNN/history" \
-G \
-d "start_date=2026-02-01" \
-d "end_date=2026-03-06" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
---
## List Latest FX Rates
Returns the latest known FX rates for the requested base currency.
For XOF and XAF countries, official regional central-bank rates may appear alongside the broader daily FX source depending on the base currency you request.
For Morocco, official Bank Al-Maghrib-published MAD rates may appear alongside the broader daily FX source depending on the base currency you request.
For Tanzania, official Bank of Tanzania-published TZS rates may appear alongside the broader daily FX source depending on the base currency you request.
If you are integrating across WAEMU countries, expect `bceao_fx_rates` to be the cleanest official source for XOF quotes.
If you are integrating across CEMAC countries, expect `beac_fx_rates` to be the cleanest official source for XAF quotes.
If you are integrating for Morocco, expect `bkam_ma_fx_rates` to be the cleanest official source for MAD quotes.
If you are integrating for Tanzania, expect `bot_tz_fx_rates` to be the cleanest official source for TZS quotes.
Base currency, default `USD`
Comma-separated quote currencies
Filter by associated country
Maximum rows to return (1-500)
```bash title="Request"
curl "https://api.africa-api.com/v1/markets/fx-rates" \
-G \
-d "base_currency=USD" \
-d "quote_currencies=NGN,ZAR,KES" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```json title="Response"
{
"data": [
{
"source_code": "fx_usd_daily",
"base_currency": "USD",
"quote_currency": "NGN",
"country_codes": ["ng"],
"rate_date": "2026-03-07",
"rate": 1538.12,
"created_at": "2026-03-07T01:05:00Z"
}
]
}
```
---
## Get FX History
```bash
curl "https://api.africa-api.com/v1/markets/fx-rates/USD/NGN/history" \
-G \
-d "start_date=2026-02-01" \
-d "end_date=2026-03-07" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
---
# MCP Server
URL: https://africa-api.com/docs/mcp
Description: Connect AI assistants to live African data with the official Africa API MCP server. 40 read-only tools across countries, indicators, markets, trade, elections, and policies.
Africa API ships an official [MCP](https://modelcontextprotocol.io) server, [`africa-api-mcp` on npm](https://www.npmjs.com/package/africa-api-mcp). It gives Claude, Cursor, and any other MCP client direct, read-only access to the platform: 40 tools across countries, indicators and time series, markets, FX, trade, elections, policies, and government records for all 54 African countries.
The server runs locally via `npx`, so there is nothing to install or host. You only need an API key from the [dashboard](/dashboard).
## Connect your client
Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
```json
{
"mcpServers": {
"africa-api": {
"command": "npx",
"args": ["-y", "africa-api-mcp"],
"env": {
"AFRICA_API_KEY": "your-api-key-here"
}
}
}
}
```
Restart Claude Desktop and the tools appear automatically.
One command:
```bash
claude mcp add africa-api -e AFRICA_API_KEY=your-api-key-here -- npx -y africa-api-mcp
```
Add the same server definition to `.cursor/mcp.json` in your project (or the global Cursor MCP settings):
```json
{
"mcpServers": {
"africa-api": {
"command": "npx",
"args": ["-y", "africa-api-mcp"],
"env": {
"AFRICA_API_KEY": "your-api-key-here"
}
}
}
}
```
Any other MCP-compatible client works with the same `npx -y africa-api-mcp` command and the `AFRICA_API_KEY` environment variable.
## What the tools cover
| Domain | Tools | What it covers |
|--------|:-----:|----------------|
| Countries | 4 | Country records, curated profiles, current signals for all 54 nations |
| Indicators & data | 4 | 127+ indicators, time-series queries, country rankings |
| Government | 6 | Heads of state, cabinets, leadership terms, current and historical |
| Elections | 5 | Results, upcoming elections, country election overviews |
| Markets | 7 | Stock exchanges, tickers, price history, FX rates |
| Trade | 4 | Bilateral flows, top partners, product breakdowns |
| Policies | 6 | Laws, regulations, policy timelines, lifecycle events |
| Sources | 2 | Data provenance: World Bank, UN, FAOSTAT, central banks |
| Geographies | 1 | Continent, region, subregion hierarchy |
Every tool is read-only and carries MCP safety annotations, so clients can run them without write-risk prompts.
## What you can ask once connected
- "Compare GDP for Nigeria and South Africa over the last 10 years."
- "Show current FX rates for East African currencies."
- "Who is Kenya's head of state and when did they take office?"
- "Which African elections are coming up this year?"
- "Rank African countries by under-five mortality."
- "What are Nigeria's top export products?"
## For agents reading this programmatically
- Condensed docs index: [/llms.txt](/llms.txt)
- Full docs as plain text: [/llms-full.txt](/llms-full.txt)
- OpenAPI schema: `https://api.africa-api.com/openapi.json`
- Base URL: `https://api.africa-api.com/v1` with `Authorization: Bearer` auth ([authentication guide](/docs/authentication))
## Related docs
Create an API key and make a first request.
Client patterns for JavaScript, TypeScript, and Python.
Safe client behavior, retries, and caching guidance.
What is live by country and domain.
---
# Platform
URL: https://africa-api.com/docs/platform
Description: Inspect release identity, source freshness, and data quality when you need operational visibility.
## Version
Returns the live project name and release SHA currently serving requests.
No authentication required.
```bash title="Request"
curl "https://api.africa-api.com/v1/platform/version"
```
```json title="Response"
{
"data": {
"status": "ok",
"project_name": "Africa API",
"release_sha": "7419e85294d3e709c6c429c1dedd17687c77a8f9"
}
}
```
---
## Source Status
Returns refresh status for active data sources, including last success, next scheduled run, dataset version, and latest write counts.
Requires an API key.
```bash title="Request"
curl "https://api.africa-api.com/v1/platform/etl-status" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```json title="Response"
{
"data": [
{
"source": "world_bank_wdi",
"status": "healthy",
"last_success_at": "2026-03-07T12:10:14Z",
"next_run_at": "2026-03-08T00:10:14Z",
"dataset_version": "wbwdi-1960-2025",
"records_written_last_run": 31096
}
]
}
```
---
## Data Quality
Returns source-level quality and freshness evaluations used to monitor the data platform.
This endpoint exposes:
- freshness status
- quality status
- last and previous write counts
- country coverage for country-level sources
- active quality rules
- anomaly messages when a source looks suspicious
Requires an API key.
```bash title="Request"
curl "https://api.africa-api.com/v1/platform/data-quality" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```json title="Response"
{
"data": [
{
"source": "world_bank_wdi",
"freshness_status": "healthy",
"quality_status": "healthy",
"last_success_at": "2026-03-08T17:42:30Z",
"next_run_at": "2026-03-09T05:42:30Z",
"dataset_version": "wbwdi-1960-2025",
"records_written_last_run": 52128,
"previous_records_written": 37718,
"country_coverage_last_run": 54,
"anomalies": [],
"rules": {
"min_records": 30000,
"drop_ratio_threshold": 0.4,
"min_country_coverage": 45,
"stale_after_minutes": 1080
}
}
]
}
```
---
# Policies
URL: https://africa-api.com/docs/policies
Description: Access African laws, policy documents, lifecycle events, and country policy timelines through one searchable API.
## African Policy Data API
Use Africa API to track laws, policy documents, and lifecycle events through one searchable policy layer across African countries.
This page is the best starting point for:
- country policy overviews
- active law and document lists
- policy detail records
- policy timelines and policy events
## Policies In Africa API
Current source:
- `wikidata_policies`
Use:
- `GET /v1/policies`
- `GET /v1/policies/events`
- `GET /v1/policies/country/{country_code}`
- `GET /v1/policies/country/{country_code}/timeline`
- `GET /v1/policies/{policy_wikidata_id}`
- `GET /v1/policies/{policy_wikidata_id}/events`
## What This Covers
The first policies slice is built around:
- constitutions
- laws and acts
- regulations and decrees
- national strategies and policy documents
- country policy overviews
- policy adoption, implementation, and repeal timelines
- issuing-body metadata when available
This is intentionally separate from scalar indicator data and election-event data.
## Country Policy Overview Example
```bash
curl "https://api.africa-api.com/v1/policies/country/ke?top_limit=5" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
Example response shape:
```json
{
"data": {
"country": {
"code": "ke",
"name": "Kenya",
"region": "East Africa"
},
"latest_policy": {
"wikidata_id": "Q456",
"country_code": "ke",
"country_name": "Kenya",
"title": "Kenya Climate Change Act",
"document_type": "law",
"policy_status": "active",
"published_at": "2016-05-27",
"source": "wikidata_policies"
},
"active_policy_count": 14,
"recent_policies": []
}
}
```
## Policy List Example
```bash
curl "https://api.africa-api.com/v1/policies?country_code=ng&document_type=law&status=active&limit=20" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
## Policy Detail Example
```bash
curl "https://api.africa-api.com/v1/policies/Q456" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
## Country Policy Timeline Example
```bash
curl "https://api.africa-api.com/v1/policies/country/ke/timeline?top_limit=10" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
Example response shape:
```json
{
"data": {
"country": {
"code": "ke",
"name": "Kenya",
"region": "East Africa"
},
"latest_event": {
"event_key": "Q456:implemented:2016-06-01",
"policy_wikidata_id": "Q456",
"title": "Kenya Climate Change Act",
"document_type": "law",
"event_type": "implemented",
"event_date": "2016-06-01",
"summary": "Kenya Climate Change Act entered into force",
"source": "wikidata_policies"
},
"recent_events": []
}
}
```
## Policy Events Example
```bash
curl "https://api.africa-api.com/v1/policies/events?country_code=ng&event_type=adopted&limit=20" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
## How It Fits The Government Domain
- [Government](/docs/government) covers leaders, terms, and cabinets
- [Elections](/docs/elections) covers election events and result rows
- `Policies` covers legal and policy documents produced by the state plus their lifecycle events
- country profiles embed the latest policy and latest policy event inside the compact `government` block
Use government history for leaders, offices, cabinet composition, and state structure.
Use elections for event timelines and candidate-level results.
Country profiles now include compact policy and policy-event summaries when available.
---
# Power
URL: https://africa-api.com/docs/power
Description: Use current power-system signals for operational grid context alongside longer-run energy indicators.
## Current Power Signals
Africa API separates long-run energy indicators from live operational power-system signals.
Use the regular indicator/data endpoints for:
- electricity access
- energy consumption
- renewable energy share
- grid efficiency and losses
Use `/v1/countries/{country_code}/signals` when you want current operating context such as:
- load shedding stage
- energy availability factor
- peak and off-peak grid generation
- peak and off-peak grid frequency
- daily energy generated
- daily energy sent out
- unplanned generation outages
- planned maintenance
## Current Coverage
- Nigeria
- `peak_grid_generation_mw`
- `peak_grid_frequency_hz`
- `off_peak_grid_generation_mw`
- `off_peak_grid_frequency_hz`
- `daily_energy_generated_mwh`
- `daily_energy_sent_out_mwh`
- South Africa
- `load_shedding_stage`
- `energy_availability_factor_pct`
- `unplanned_generation_outages_mw`
- `planned_generation_maintenance_mw`
## Example
```bash title="Nigeria Signals"
curl "https://api.africa-api.com/v1/countries/ng/signals" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```bash title="South Africa Signals"
curl "https://api.africa-api.com/v1/countries/za/signals" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
## Why It Lives In Signals
Power-system status is not the same as a historical annual indicator.
Africa API keeps these current operational values in `/signals` so:
- dashboards can fetch a compact live country snapshot
- clients can mix current operations with broader macro and market context
- historical annual energy series stay stable in `/v1/data`
See how current power-system data appears in the country snapshot payload.
Use the broader energy indicator guide for annual and structural metrics.
---
# Quickstart
URL: https://africa-api.com/docs/quickstart
Description: Create an API key, make a first request, and move from country lookups to current signals and historical data.
Most `/v1/*` routes require an API key. Generate one in the dashboard before you start integrating.
## Integration Strategy
Treat Africa API as one client with reusable transport concerns:
- one base URL
- one bearer-token strategy
- one error handling path
- feature modules on top (`countries`, `signals`, `data`, `markets`, `trade`, `government`)
The fastest way to get value from the platform is:
1. check [Coverage](/docs/coverage) to see the live country and domain map
2. start with `/v1/countries/{country_code}/signals` for a compact service-ready snapshot
3. move to `/v1/data` when you need explicit metrics, time series, or comparisons
### Create an API key
```bash
open "https://africa-api.com/dashboard"
```
Create an account or sign in, then generate an API key in the dashboard.
### Export your API key
```bash
export AFRICA_API_KEY="your_api_key_here"
```
### Fetch a current country snapshot
```bash
curl "https://api.africa-api.com/v1/countries/ng/signals" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
### Fetch a country record
```bash
curl "https://api.africa-api.com/v1/countries/ng" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
### Query historical or latest data
```bash
curl "https://api.africa-api.com/v1/data?country_code=ke&metric_key=population_total&latest=true" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
### Explore a domain route
```bash
curl "https://api.africa-api.com/v1/trade/overview/ng?top_limit=5" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
## Optional operational checks
Use these only when you need deployment or freshness context:
```bash
curl "https://api.africa-api.com/health"
curl "https://api.africa-api.com/v1/platform/version"
```
## Next Steps
Check live country and domain coverage before you build around a specific signal family.
Start with the simplest current snapshot when you need a useful country payload quickly.
Add official FX, exchange, and ticker coverage once you move beyond country snapshots.
Learn the canonical observation query surface.
Understand when to use reference records, profiles, and signals.
Review key handling, public routes, and request format.
---
# Rate Limits
URL: https://africa-api.com/docs/rate-limits
Description: Safe client behavior for Africa API, including retries, batching, and caching guidance.
## Current Behavior
As of March 2026, Africa API does not publish formal per-key quota headers. You should still build for backoff, batching, and caching.
## Recommended Client Controls
1. Set explicit request timeouts.
2. Retry only transient failures (`429`, `5xx`).
3. Batch related observations into one `/v1/data` call instead of many single-resource requests.
4. Cache `GET /v1/countries` using `ETag` and `Cache-Control`.
5. Avoid request spikes when hydrating dashboards.
## Retry Template (JavaScript)
```javascript
async function requestWithBackoff(url, init, maxAttempts = 4) {
let delayMs = 300;
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
const response = await fetch(url, init);
if (response.ok) return response;
const retryable = response.status === 429 || response.status >= 500;
if (!retryable || attempt === maxAttempts) return response;
await new Promise((resolve) => setTimeout(resolve, delayMs + Math.random() * 200));
delayMs *= 2;
}
}
```
## Query Design Tips
- Prefer `country_codes=ng,ke,za` over three separate requests.
- Prefer `metric_keys=population_total,gdp_current_usd` where a combined response is acceptable.
- Use `latest=true` when you do not need a full time series.
## Future Contract
If explicit quota headers or published plans are introduced, this page should be treated as the source of truth.
---
# SDKs
URL: https://africa-api.com/docs/sdks
Description: Use thin HTTP client wrappers for Africa API until official SDK packages ship.
Official SDK packages are not published yet. Use a small internal client so you can swap to an official SDK later without rewriting business logic.
## MCP Server for AI Tools
If your client is an AI assistant rather than application code, use the official MCP server instead of writing a wrapper. [`africa-api-mcp`](https://www.npmjs.com/package/africa-api-mcp) runs with `npx -y africa-api-mcp` and exposes 40 read-only tools to Claude, Cursor, and any MCP-compatible client. See the [MCP server guide](/docs/mcp) for setup.
## Client Patterns
```typescript
const BASE_URL = "https://api.africa-api.com";
async function africaRequest(path: string): Promise {
const response = await fetch(`${BASE_URL}${path}`, {
headers: {
Authorization: `Bearer ${process.env.AFRICA_API_KEY ?? ""}`,
},
});
if (!response.ok) {
throw new Error(`Africa API request failed: ${response.status}`);
}
return response.json() as Promise;
}
export function listIndicators(category?: string) {
const suffix = category ? `?category=${encodeURIComponent(category)}` : "";
return africaRequest<{ data: Array<{ key: string; name: string }> }>(
`/v1/indicators${suffix}`,
);
}
export function listData(countryCode: string, metricKey: string) {
return africaRequest(`/v1/data?country_code=${countryCode}&metric_key=${metricKey}&latest=true`);
}
```
```python
import requests
BASE_URL = "https://api.africa-api.com"
def africa_request(path: str, api_key: str) -> dict:
response = requests.get(
f"{BASE_URL}{path}",
headers={"Authorization": f"Bearer {api_key}"},
timeout=10,
)
response.raise_for_status()
return response.json()
def list_indicators(api_key: str, category: str | None = None) -> dict:
suffix = f"?category={category}" if category else ""
return africa_request(f"/v1/indicators{suffix}", api_key)
def list_data(api_key: str, country_code: str, metric_key: str) -> dict:
return africa_request(
f"/v1/data?country_code={country_code}&metric_key={metric_key}&latest=true",
api_key,
)
```
## OpenAPI Schema
If you prefer generated clients:
```text
https://api.africa-api.com/openapi.json
```
Pin generated clients to the `/v1` routes you actually use.
---
# Signals
URL: https://africa-api.com/docs/signals
Description: Use country signals for a compact current snapshot across indicators, FX, local prices, transport, grid conditions, climate, humanitarian displacement, disaster alerts, markets, trade, and government context.
## Country Signals
Returns a compact current snapshot for one country.
This endpoint is the simplest way to combine:
- latest selected macro and infrastructure indicators
- latest local fuel and food price notices where official country sources exist
- latest power-system condition signals where official operators publish current status
- latest airport and port operations where official operators publish monthly traffic
- latest weather and rainfall signals where trusted current climate sources exist
- latest humanitarian displacement signals where UNHCR publishes country-of-asylum totals
- latest disaster alerts where GDACS flags an active country-linked event
- latest FX rates tied to the country
- latest commodity benchmark prices used as global reference signals
- latest exchange-level market snapshots when country-linked market coverage is available
- compact trade context
- compact government context
Signals can now mix:
- slower annual backbone metrics
- fresher monthly operational metrics
- central-bank published current rates where a country source is wired in
- central-bank published current bill or money-market rates where a country source is wired in
- central-bank published current rates where a country or currency-union source is wired in
- official local price notices where a regulator publishes current retail prices
- official local food price notices where a country source publishes current wholesale staples
- official grid and outage status signals where a national operator publishes current system conditions
- official airport and port traffic signals where operators publish monthly throughput or movement totals
- daily weather and rolling rainfall signals where a current climate source is wired in
- latest UNHCR displacement counts where official annual country totals are available
- current disaster alerts where GDACS publishes an active country-linked event
Monthly/latest observations include `as_of_period` so clients can tell which month the signal actually represents. Location-specific signals also include `location_name`.
Use it when you want a fresh operational summary without composing several endpoint families yourself.
Requires an API key.
ISO alpha-2 code such as `ng`, `ke`, `za`
```bash title="Request"
curl "https://api.africa-api.com/v1/countries/ke/signals" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```json title="Response"
{
"data": {
"country": {
"code": "ke",
"name": "Kenya",
"capital": "Nairobi",
"region": "East Africa"
},
"observations": [
{
"metric_key": "inflation_cpi_latest_yoy_pct",
"name": "Inflation (Latest YoY)",
"value": 4.8,
"unit": "percent",
"year": 2025,
"frequency": "monthly",
"source": "cbk_ke_signals",
"freshness": "current",
"as_of_period": "2026-01",
"retrieved_at": "2026-03-09T18:00:00Z"
},
{
"metric_key": "policy_rate_pct",
"name": "Policy Rate (Latest)",
"value": 8.75,
"unit": "percent",
"year": 2026,
"frequency": "ad_hoc",
"source": "cbk_ke_signals",
"freshness": "recent",
"as_of_period": "2026-02-10",
"retrieved_at": "2026-03-09T18:00:00Z"
},
{
"metric_key": "petrol_price_local_per_liter",
"name": "Petrol Price (Latest)",
"value": 186.31,
"unit": "local_currency_per_liter",
"year": 2026,
"frequency": "monthly",
"source": "epra_ke_fuel_signals",
"freshness": "current",
"as_of_period": "2026-03",
"location_name": "Nairobi",
"retrieved_at": "2026-03-15T09:00:00Z"
},
{
"metric_key": "maize_wholesale_price_local_per_kg",
"name": "Maize Wholesale Price (Latest)",
"value": 70.74,
"unit": "local_currency_per_kg",
"year": 2026,
"frequency": "monthly",
"source": "world_bank_ke_food_signals",
"freshness": "current",
"as_of_period": "2026-03",
"location_name": "Market Average",
"retrieved_at": "2026-03-21T09:00:00Z"
},
{
"metric_key": "precipitation_7d_mm",
"name": "Precipitation (7 Day Total)",
"value": 16.0,
"unit": "millimeters",
"year": 2026,
"frequency": "ad_hoc",
"source": "nasa_power_climate_signals",
"freshness": "current",
"as_of_period": "2026-03-05 to 2026-03-11",
"retrieved_at": "2026-03-16T09:00:00Z"
},
{
"metric_key": "refugees_hosted_total",
"name": "Refugees Hosted",
"value": 626546,
"unit": "persons",
"year": 2025,
"frequency": "annual",
"source": "unhcr_displacement_signals",
"freshness": "recent",
"retrieved_at": "2026-03-16T09:00:00Z"
},
{
"metric_key": "load_shedding_stage",
"name": "Load Shedding Stage (Latest)",
"value": 0,
"unit": "stage",
"year": 2026,
"frequency": "ad_hoc",
"source": "eskom_za_grid_signals",
"freshness": "current",
"as_of_period": "2026-03-12",
"retrieved_at": "2026-03-12T18:00:00Z"
},
{
"metric_key": "mobile_subscriptions_per_100",
"name": "Mobile Cellular Subscriptions",
"value": 118.6,
"unit": "subscriptions_per_100_people",
"year": 2024,
"frequency": "annual",
"source": "world_bank_wdi",
"freshness": "recent",
"retrieved_at": "2026-03-09T11:39:09Z"
}
],
"disaster_alerts": [
{
"event_key": "1102919:1:fl:ke",
"event_type": "FL",
"name": "Flooding in Kenya",
"description": "Heavy rain and flooding conditions",
"alert_level": "orange",
"alert_score": 2.4,
"severity_value": 120.0,
"severity_text": "Heavy rain",
"severity_unit": "mm/24h",
"event_from_at": "2026-03-13T09:00:00Z",
"event_to_at": "2026-03-16T09:00:00Z",
"source_modified_at": "2026-03-13T10:30:00Z",
"report_url": "https://www.gdacs.org/report.aspx?eventid=1102919",
"details_url": "https://www.gdacs.org/report.aspx?eventid=1102919&episodeid=1",
"source_system": "GDACS",
"source": "gdacs_disaster_alerts",
"freshness": "current"
}
],
"commodity_benchmarks": [
{
"commodity_key": "crude_oil_benchmark_usd_per_bbl",
"commodity_name": "Crude Oil Benchmark",
"unit": "usd_per_bbl",
"currency_code": "USD",
"price_date": "2026-01-01",
"price_value": 74.8,
"source": "world_bank_pink_sheet_signals",
"freshness": "recent"
},
{
"commodity_key": "maize_benchmark_usd_per_mt",
"commodity_name": "Maize Benchmark",
"unit": "usd_per_mt",
"currency_code": "USD",
"price_date": "2026-01-01",
"price_value": 215.0,
"source": "world_bank_pink_sheet_signals",
"freshness": "recent"
}
],
"fx_rates": [
{
"base_currency": "USD",
"quote_currency": "KES",
"rate": 129.44,
"date": "2026-03-08",
"source": "fx_usd_daily",
"freshness": "current"
}
],
"market_snapshots": [],
"trade": {
"latest_year": 2024,
"granular_latest_year": 2024,
"granular_years": [2023, 2024]
},
"government": {
"current_head_of_state": {
"leader_name": "William Ruto",
"role_type": "head_of_state"
}
},
"generated_at": "2026-03-09T18:00:00Z"
}
}
```
---
## Current Coverage Today
Use this table as the live coverage map for the signals layer:
| Country or scope | Live signal families |
| --- | --- |
| Kenya | central bank, fuel prices, food prices, climate |
| Morocco | central bank |
| Namibia | central bank |
| Nigeria | central bank, grid, climate |
| South Africa | central bank, grid, fuel prices, airport traffic, airport on-time performance, port operations, climate |
| Tanzania | central bank, climate |
| Tunisia | central bank, climate |
| Countries with active GDACS alerts | disaster alerts |
| Countries with UNHCR totals | displacement context |
| All 54 countries | historical highlight observations in the same payload |
For a broader product view, see [Coverage](/docs/coverage).
### Service Coverage Matrix
| Country or scope | Macro | Prices | Power | Airports | Ports | Climate | Risk context |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Kenya | Yes | Fuel and maize | - | - | Yes | Yes | GDACS and UNHCR when present |
| Morocco | Yes | - | - | - | - | Historical backbone | GDACS and UNHCR when present |
| Namibia | Yes | - | - | - | - | Historical backbone | GDACS and UNHCR when present |
| Nigeria | Yes | - | Yes | - | - | Yes | GDACS and UNHCR when present |
| South Africa | Yes | Fuel | Yes | Yes | Yes | Yes | GDACS and UNHCR when present |
| Tanzania | Yes | - | - | - | - | Yes | GDACS and UNHCR when present |
| Tunisia | Yes | - | - | - | - | Yes | GDACS and UNHCR when present |
| WAEMU countries | BCEAO policy rates | - | - | - | - | Historical backbone | GDACS and UNHCR when present |
| CEMAC countries | BEAC policy rates | - | - | - | - | Historical backbone | GDACS and UNHCR when present |
## South Africa Full Example
```bash title="South Africa Signals"
curl "https://api.africa-api.com/v1/countries/za/signals" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```json title="Representative Mixed Response"
{
"country": {
"code": "za",
"name": "South Africa",
"capital": "Pretoria",
"region": "Southern Africa"
},
"observations": [
{
"metric_key": "policy_rate_pct",
"value": 7.5,
"unit": "percent",
"frequency": "ad_hoc",
"source": "sarb_za_signals",
"as_of_period": "2026-01-30"
},
{
"metric_key": "petrol_price_local_per_liter",
"value": 20.3,
"unit": "local_currency_per_liter",
"frequency": "monthly",
"source": "dmre_za_fuel_signals",
"as_of_period": "2026-03",
"location_name": "Gauteng Zone 9C"
},
{
"metric_key": "load_shedding_stage",
"value": 0,
"unit": "stage",
"frequency": "ad_hoc",
"source": "eskom_za_grid_signals",
"as_of_period": "2026-03-12"
},
{
"metric_key": "airport_passengers_ytd_total",
"value": 34282784,
"unit": "passengers",
"frequency": "monthly",
"source": "acsa_za_airport_signals",
"as_of_period": "2026-01"
},
{
"metric_key": "airport_on_time_performance_latest_month_pct",
"value": 90.66,
"unit": "percent",
"frequency": "monthly",
"source": "acsa_za_on_time_performance_signals",
"as_of_period": "2026-02"
},
{
"metric_key": "port_container_throughput_latest_teu",
"value": 373644,
"unit": "teu",
"frequency": "monthly",
"source": "tnpa_za_port_signals",
"as_of_period": "2025-06"
},
{
"metric_key": "precipitation_7d_mm",
"value": 9.1,
"unit": "millimeters",
"frequency": "ad_hoc",
"source": "nasa_power_climate_signals",
"as_of_period": "2026-03-05 to 2026-03-11"
}
],
"fx_rates": [
{
"base_currency": "USD",
"quote_currency": "ZAR",
"rate": 15.58,
"date": "2026-03-14",
"source": "fx_usd_daily"
}
],
"market_snapshots": [
{
"exchange_code": "JSE",
"latest_trade_date": "2026-03-14",
"source": "jse_yahoo_eod"
}
],
"trade": {
"latest_year": 2024,
"granular_latest_year": 2024
},
"government": {
"current_head_of_state": {
"leader_name": "Cyril Ramaphosa",
"role_type": "head_of_state"
}
}
}
```
---
## When To Use Signals
Use `/v1/countries/{country_code}/signals` when you need:
- a dashboard card payload
- an agent-friendly current snapshot
- a compact country summary for operational use
- benchmark commodity context without querying another endpoint family
Use `/v1/data` when you need:
- full time series
- multi-country comparisons
- explicit metric/frequency filtering
- direct source pinning
Transport operations now include South Africa airport and port signals plus Kenya port signals, so `/v1/countries/za/signals` and `/v1/countries/ke/signals` both carry official live logistics context.
Example for a latest monthly signal through the canonical observation endpoint:
```bash title="Latest Monthly Signal Via /v1/data"
curl "https://api.africa-api.com/v1/data?country_code=ke&metric_key=inflation_cpi_latest_yoy_pct&latest=true" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
## Freshness Model
Each signal carries a simple freshness label:
- `current`
- `recent`
- `historical`
That label is derived from frequency, year, retrieved timestamp, or market/FX trade date.
Signals do not replace the historical observation layer. They are a convenience view over the platform's latest useful country-level state.
Where a central-bank source is available, `/signals` will prefer that country-specific source over a broader monthly feed for the same latest-signal metric. Today that includes Kenya, South Africa, and Nigeria.
Some current price signals are local or market-specific rather than national. Kenya fuel prices currently reflect the official EPRA Nairobi notice, South Africa fuel prices reflect the official DMRE Gauteng reference zone and national paraffin retail cap, and Kenya food prices reflect the latest World Bank Kenya market estimates. These carry `location_name` and other source context so clients can label them accurately.
Some current operational signals are national system statements rather than economic statistics. South Africa power-system signals come from Eskom’s power status updates, Nigeria power-system signals come from NISO’s daily grid statement, South Africa airport traffic and on-time performance come from ACSA’s monthly operational statistics, and South Africa port operations come from TNPA’s monthly national port statistics. These are best treated as operational context rather than long-run structural indicators.
Some current climate signals are daily point-based estimates rather than annual national indicators. NASA POWER temperature, humidity, and rolling rainfall values are included as current operational context and are best interpreted as recent geospatial climate signals.
Some current risk signals are event-driven rather than periodic statistics. GDACS disaster alerts indicate active country-linked floods, cyclones, earthquakes, wildfires, volcanic events, and related emergencies when GDACS currently reports them.
Commodity benchmarks are global reference series. They are included in `/signals` as current context, not as country-specific observations.
---
# Sources
URL: https://africa-api.com/docs/sources
Description: Inspect source metadata, licensing context, citations, and the latest successful refresh for a dataset.
## List Sources
Lists the sources currently available through the public API.
```bash title="Request"
curl "https://api.africa-api.com/v1/sources" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```json title="Response"
{
"data": [
{
"code": "world_bank_wdi",
"name": "World Development Indicators",
"organization": "World Bank"
},
{
"code": "who_gho",
"name": "Global Health Observatory",
"organization": "World Health Organization"
},
{
"code": "unesco_uis",
"name": "UIS Education Statistics",
"organization": "UNESCO Institute for Statistics"
}
]
}
```
---
## Get Source Detail
Returns source metadata and the latest successful refresh.
Use source detail when licensing, provenance, or freshness matters to your integration.
```bash title="Request"
curl "https://api.africa-api.com/v1/sources/un_wpp" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```json title="Response"
{
"data": {
"code": "un_wpp",
"name": "World Population Prospects",
"organization": "United Nations",
"dataset_url": "https://population.un.org/wpp",
"license_name": null,
"citation": null,
"latest_run": {
"status": "succeeded",
"dataset_version": "unwpp-1950-2026",
"records_written": 45738,
"completed_at": "2026-03-07T13:10:58Z"
}
}
}
```
---
# Health
URL: https://africa-api.com/docs/status
Description: Check Africa API health and release identity before making protected API calls.
## Platform Health
Returns the current platform status and deployed release SHA.
No authentication required. No query parameters.
Use it for uptime checks, deployment verification, and incident triage.
```bash title="Request"
curl "https://api.africa-api.com/health"
```
```json title="Response · 200"
{
"status": "ok",
"release_sha": "7419e85294d3e709c6c429c1dedd17687c77a8f9"
}
```
---
# Trade
URL: https://africa-api.com/docs/trade
Description: Use the dedicated trade domain for African trade overviews, partner data, product data, and trade flows, with aggregate trade metrics also available through shared data endpoints.
## Trade Domain In Africa API
Africa API has a dedicated trade surface for country-level trade analysis.
Trade coverage currently comes from two layers:
- aggregate trade indicators from `world_bank_wdi`
- granular partner/product trade flows from `un_comtrade`
Granular trade coverage currently stores:
- bilateral all-commodity partner totals
- world-level HS chapter product composition
Use:
- `GET /v1/trade/overview/{country_code}`
- `GET /v1/trade/flows`
- `GET /v1/trade/partners`
- `GET /v1/trade/products`
The shared observation layer still exposes trade aggregates through:
Use:
- `GET /v1/indicators?category=economy`
- `GET /v1/data?metric_key=trade_balance_usd`
- `GET /v1/data?metric_key=exports_goods_services_usd`
- `GET /v1/countries/{country_code}/profile`
Country profiles now embed a compact trade section with:
- `latest_snapshot`
- `granular_latest_year`
- top export/import partners
- top export/import products
## Useful Metrics
- `exports_goods_services_usd`
- `imports_goods_services_usd`
- `exports_goods_services_pct_gdp`
- `imports_goods_services_pct_gdp`
- `trade_balance_usd`
- `current_account_balance_pct_gdp`
## Overview Example
```bash
curl "https://api.africa-api.com/v1/trade/overview/ng?start_year=2020&end_year=2024&top_limit=5" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
The overview response now includes:
- yearly aggregate series
- `latest_snapshot`
- `granular_latest_year`
- `granular_years`
- `top_export_partners`
- `top_import_partners`
- `top_export_products`
- `top_import_products`
For most applications, `/v1/trade/overview/{country_code}` should be the first call.
## Partner Query Example
```bash
curl "https://api.africa-api.com/v1/trade/partners?reporter_country_code=ng&flow_type=export&year=2024&limit=10" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
## Product Query Example
```bash
curl "https://api.africa-api.com/v1/trade/products?reporter_country_code=ng&flow_type=import&start_year=2020&end_year=2024&limit=10" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
## Example Queries
```bash
curl "https://api.africa-api.com/v1/data?country_codes=ng,ke,za&metric_key=trade_balance_usd&year=2024" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```bash
curl "https://api.africa-api.com/v1/data?country_code=eg&metric_key=exports_goods_services_pct_gdp&start_year=2018&end_year=2024" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
Start with the dedicated trade domain for country-level overview and future partner or product analysis.
Inspect available trade metrics and coverage.
Query latest trade aggregates or full time series.
Use country profiles to blend trade with the rest of the platform.
---
# Transport
URL: https://africa-api.com/docs/transport
Description: Use indicators, data endpoints, and current signals for transport, roads, rail, airport traffic, port operations, shipping connectivity, and digital infrastructure.
## Transport And Connectivity In Africa API
Transport and connectivity data is exposed through the shared indicator, data, and signals endpoints.
Current coverage combines the World Bank WDI backbone with official South Africa airport traffic, South Africa airport on-time performance, South Africa port operations, and Kenya port operations.
- `GET /v1/indicators?category=infrastructure`
- `GET /v1/data?category=infrastructure`
- `GET /v1/sources/world_bank_wdi`
- `GET /v1/sources/acsa_za_airport_signals`
- `GET /v1/sources/acsa_za_on_time_performance_signals`
- `GET /v1/sources/kpa_ke_port_signals`
- `GET /v1/countries/{country_code}/signals`
- `GET /v1/sources/tnpa_za_port_signals`
## Historical Transport Metrics
- `air_transport_passengers`
- `air_transport_departures`
- `liner_shipping_connectivity_index`
- `rail_lines_km`
- `road_network_total_km`
- `paved_roads_pct`
- `mobile_subscriptions_per_100`
- `fixed_broadband_subscriptions_per_100`
- `secure_internet_servers_per_million`
These are annual country-level transport and connectivity observations and fit the current observation model cleanly.
## Current Airport And Port Operations
South Africa currently includes official ACSA airport traffic, ACSA network on-time performance, and TNPA port operations in `/v1/countries/za/signals`.
Kenya now includes official KPA port operations in `/v1/countries/ke/signals`.
- `airport_passengers_ytd_total`
- `airport_aircraft_movements_ytd_total`
- `airport_on_time_performance_ytd_pct`
- `airport_on_time_performance_latest_month_pct`
- `port_throughput_latest_tonnes`
- `port_container_throughput_latest_teu`
- `port_transit_cargo_latest_tonnes`
- `port_vessel_calls_latest_total`
The airport traffic figures are ACSA network year-to-date totals as of the latest published month. The on-time figures are the latest published ACSA network performance percentages for the same reporting month. The TNPA port figures are national port-system totals from South Africa. The KPA port figures are annual Port of Mombasa performance totals from the latest official Kenya Ports Authority cargo-growth article. All of them appear in the country signal payload with `as_of_period` so clients can see which publication period the source covers.
This means the current live transport operations layer is now strongest for South Africa and Kenya, while the broader transport indicator layer still comes from the historical backbone through `/v1/data`.
## Example Queries
```bash
curl "https://api.africa-api.com/v1/indicators?category=infrastructure&has_data=true" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```bash
curl "https://api.africa-api.com/v1/data?country_codes=eg,ke,za&metric_key=air_transport_passengers&year=2023" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```bash
curl "https://api.africa-api.com/v1/data?country_code=ng&metric_key=mobile_subscriptions_per_100&start_year=2018&end_year=2024" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
```bash
curl "https://api.africa-api.com/v1/countries/za/signals" \
-H "Authorization: Bearer $AFRICA_API_KEY"
```
Inspect available transport and connectivity metrics.
Query latest values or full time series.
Use country profiles to blend transport signals with the rest of the platform.
See how current airport and port operations appear in the country snapshot payload.