Skip to content
Kafukufuku Data Hub
Datasets Domains Collections Institutions Guides About Submit Data

API

Kafukufuku Data Hub API

Public JSON endpoints for datasets, source files, institutions, and catalog statistics. Use this page as the stable reference for parameters and example requests. The machine-readable schema remains available at /api/v1/schema/.

Try Datasets API Try Source Files API Open JSON Schema

Basics

  • Base path: /api/v1/
  • Response format: JSON, except CSV export endpoints.
  • Public endpoints allow anonymous access unless marked admin-only.
  • Admin endpoints require an authenticated editor or admin account.
  • Pagination is enabled on list endpoints through Django REST Framework defaults.

Public Endpoints

GET /api/v1/datasets/

Search published dataset records across all datamarts.

Parameters
  • domain: Optional domain slug such as health, agriculture, education, climate, economics, population, gis.
  • district: Exact district filter.
  • year: Exact year filter.
  • q: Free-text search across title, description, indicator, and source fields.
Example
/api/v1/datasets/?domain=agriculture&district=Mzimba&year=2024
GET /api/v1/datasets/<uuid>/

Fetch a single dataset page as JSON, including metadata, coverage, lineage, quality signals, related records, and download URLs.

Parameters
  • domain: Optional domain slug. If omitted, the API will resolve the dataset across known domains.
Example
/api/v1/datasets/11111111-1111-1111-1111-111111111111/?domain=health
GET /api/v1/source-files/

List ingested public source files and their metadata summaries.

Parameters
  • format: Optional file format such as csv, xlsx, json, dta, sav, shp, txt.
  • source: Optional source slug such as hdx, nso, who, worldbank, malawi_agriculture.
  • q: Free-text search across source-file metadata and summaries.
Example
/api/v1/source-files/?source=nso&format=xlsx
GET /api/v1/source-files/<uuid>/

Return source-file metadata, preview rows, indicators, and download URL.

Example
/api/v1/source-files/11111111-1111-1111-1111-111111111111/
GET /api/v1/institutions/

List institution profiles derived from source files and published records.

Example
/api/v1/institutions/
GET /api/v1/institutions/<slug>/

Return a single institution profile with recent source files and records.

Example
/api/v1/institutions/malawi-national-statistical-office/
GET /api/v1/domains/

List available datamart domains and their record counts.

Example
/api/v1/domains/
GET /api/v1/search/suggest/

Return lightweight title suggestions for autocomplete.

Parameters
  • q: Required search prefix with at least 2 characters.
Example
/api/v1/search/suggest/?q=mal
GET /api/v1/stats/

Return top-level counts and year ranges across datamarts.

Example
/api/v1/stats/
GET /api/v1/stats/districts/

Return district-level record counts and year coverage.

Parameters
  • domain: Optional domain slug to limit district stats.
Example
/api/v1/stats/districts/?domain=education
GET /api/v1/health/

Lightweight service health probe.

Example
/api/v1/health/
GET /api/v1/metadata/export.<json|csv>

Bulk metadata export for published dataset records or source-file catalog entries.

Parameters
  • catalog: Required export scope: datasets or source_files.
  • domain: Optional dataset-domain filter for dataset exports.
  • district: Optional district filter for dataset exports.
  • year: Optional year filter for dataset exports.
  • source: Optional source slug filter for source-file exports.
  • format: Optional file-format filter for source-file exports.
  • q: Optional free-text filter using the same behavior as list endpoints.
Example
/api/v1/metadata/export.csv?catalog=source_files&source=nso

Common Response Fields

Dataset Records

  • id
  • datamart
  • title
  • description
  • source_org
  • source_label
  • domain
  • year
  • district
  • region
  • indicator
  • value_numeric
  • unit
  • created_at
  • updated_at

Source Files

  • id
  • title
  • description
  • source_name
  • source_label
  • file_format
  • dataset_type
  • time_start
  • time_end
  • spatial_granularity
  • record_count
  • indicator_count
  • license_name
  • access_level
  • updated_at

Admin API

These endpoints are intended for internal operations. They require an authenticated editor or admin account.

  • GET /api/v1/admin/pipeline/status/: Pipeline health summary for editors and admins.
  • POST /api/v1/admin/pipeline/trigger-crawl/: Trigger a crawler by source name.
  • POST /api/v1/admin/pipeline/reprocess-failures/: Requeue failed raw files and parse jobs.
  • POST /api/v1/admin/pipeline/promote-all/: Promote approved silver records into datamarts.
  • POST /api/v1/admin/pipeline/process-bronze/: Process pending bronze records into silver.
  • GET /api/v1/admin/contributions/: List contributor inquiries.
  • GET /api/v1/admin/contributions/export/: Export contributor inquiries as CSV.
  • GET /api/v1/admin/alerts/: List active admin alerts.
  • POST /api/v1/admin/alerts/dismiss/: Dismiss alerts by id or dismiss all.

Example Queries

Cross-domain search
/api/v1/datasets/?q=maize%20price&district=Lilongwe
District statistics
/api/v1/stats/districts/?domain=agriculture
Source-file catalog filter
/api/v1/source-files/?source=worldbank&format=csv&q=poverty