# Uganda OpenData Playground

> Open data about Uganda: every region, sub-region, district, county, sub-county, parish and village, with 2024 census population, government schools, tertiary and TVET institutions with their accredited programmes (NCHE, TVET Council, Ministry TVET register), and Electoral Commission constituencies and electoral areas. Free under Creative Commons Attribution 4.0 International (https://creativecommons.org/licenses/by/4.0/). No key needed to start.

## How to get the data

- API base: https://opendata.ssmusoke.dev/api/v1 (JSON:API 1.1 by default)
- Any list as plain JSON: add `format=json`. As CSV: add `format=csv` or send `Accept: text/csv`. Both return the whole filtered list (up to 100,000 rows), not one page.
- OpenAPI 3.1 description: https://opendata.ssmusoke.dev/api/v1/openapi.json
- Human docs: https://opendata.ssmusoke.dev/docs/api
- Bulk downloads (CSV with a Frictionless data package): https://opendata.ssmusoke.dev/public/downloads

## Main endpoints

- `GET /regions`, `/sub-regions`, `/districts`, `/counties`, `/sub-counties`, `/parishes`, `/villages`: lists; filter by any ancestor, e.g. `/villages?filter[district]=91`
- `GET /{level}/{id}`, `/{level}/{id}/children`, `/{level}/{id}/ancestors`, `/{level}/{id}/statistics`, `/{level}/{id}/history`
- `GET /search?q=kira`: find places by name; each result has its full `path`
- `GET /resolve?district=Kalangala&subCounty=Mugoye&village=Bugoma`: match a typed address to a village
- `GET /statistics?filter[level]=districts&filter[indicator]=population`: 2024 census figures
- `GET /education/schools`, `/education/institutions`: schools, and tertiary and TVET institutions (`filter[regulator]=nche|tvet`)
- `GET /education/programmes?filter[level]=bachelors`: accredited programmes; `/education/register-changes` and `/education/register-snapshots`: how the registers changed over time
- Filter values are lowercase slugs, lists are comma-separated, and `filter[status]` is `current` (default), `former` or `all`
- `GET /elections/constituencies`, `/elections/electoral-areas`
- `GET /changes?filter[changedSince]=2026-01-01`: change feed for mirrors

Use the numeric `id` to identify a place. `ubosCode` is only unique within its parent. Each unit's `identifiers` has its ISO 3166-2 code, OCHA COD-AB P-code, Wikidata QID, OpenStreetMap relation and GeoNames id where known.

## Examples

- `curl 'https://opendata.ssmusoke.dev/api/v1/villages?filter[district]=91&format=csv'`
- `curl 'https://opendata.ssmusoke.dev/api/v1/search?q=gulu&format=json'`
- PHP: `$villages = json_decode(file_get_contents('https://opendata.ssmusoke.dev/api/v1/villages?filter[district]=91&format=json'), true);`

## Datasets

- **Administrative units of Uganda** (Uganda Bureau of Statistics (UBOS)): The administrative hierarchy of Uganda from regions down to villages: 4 regions, 15 sub-regions, districts (including cities and municipal councils), counties, sub-counties, parishes and villages, with the codes used by government and a crosswalk to ISO 3166-2, OCHA COD-AB P-codes, Wikidata, OpenStreetMap and GeoNames.
- **Population and households of Uganda by parish, 2024 census** (Uganda Bureau of Statistics (UBOS), National Population and Housing Census 2024, sub-region profile reports (Volume 2)): Population by sex, household population, number of households and average household size for districts, counties, sub-counties and parishes, from the UBOS National Population and Housing Census 2024 sub-region profile reports, linked to the administrative units in this portal.
- **Government primary and secondary schools in Uganda** (Ministry of Education and Sports: List of Government Primary Schools 2016; Government Secondary Schools): Government primary schools (2016 list) and government secondary schools published by the Ministry of Education and Sports, with their EMIS numbers, linked to the district, sub-county and parish of this portal.
- **Tertiary and TVET institutions and programmes in Uganda** (NCHE, TVET Council and Ministry of Education and Sports): Universities, other tertiary institutions and technical and vocational (TVET) providers on the registers of NCHE, the TVET Council and the Ministry of Education and Sports, with their accredited programmes and a dated record of how each register has changed since April 2025.
- **Constituencies and electoral areas of Uganda, 2025** (Electoral Commission of Uganda: Display list of demarcated electoral areas for local government council elections 2025): Electoral Commission constituencies and the electoral areas of directly elected district, municipality and sub-county councillors from the 2025 demarcation, linked to the districts, counties, sub-counties and parishes of this portal.

## Limits and licence

- Without a key: 60 requests per minute per IP; with a free key (https://opendata.ssmusoke.dev/settings/api-tokens): 600. Send `Authorization: Bearer <key>`.
- Errors are RFC 9457 problem details (`application/problem+json`).
- Licence: Creative Commons Attribution 4.0 International (https://creativecommons.org/licenses/by/4.0/). Cite the original publisher.
- Contact: OpenData@ssmusoke.dev