kenya-regions

npm install kenya-regions

No runtime dependencies and no network access. Every figure ships inside the package, so it works the same in Node, a browser bundle, a build step, an edge function or a serverless cold start.

The package is published as both ESM and CommonJS with full type declarations for each, verified against a real install on every commit.

import { kenya, counties, getCounty, getWardsByCounty, search } from 'kenya-regions'

kenya.codes.iso3166Alpha2          // 'KE'
counties.length                    // 47

getCounty(47)                      // Nairobi, by constitutional code
getCounty('KE-30')                 // Nairobi, by ISO 3166-2 code
getCounty('nairobi')               // Nairobi, by slug

getWardsByCounty('Kiambu').length  // 60
search('mbita')[0].region.name     // 'Suba North', found by its former name

CommonJS works identically:

const { counties, getCounty } = require('kenya-regions')

This is the reason the package exists. “Kenya’s regions” is not one list. Several schemes are in active use, they were created for different purposes, and the part that causes bugs is that they do not nest into each other.

Counties, constituencies and wards form a genuine tree, and their codes carry it: each level is numbered sequentially within its parent.

Because the seats follow the map, the parliamentary arithmetic falls straight out of these counts: 290 constituencies elect 290 MPs, 47 counties elect 47 senators and 47 woman representatives, and 1450 wards elect 1450 MCAs.

This is the most common source of confusion in Kenyan administrative data, and datasets rarely say which sense they mean. Both are shipped here, under separate names, so you never have to guess which one you are holding.

Section 48 of the County Governments Act 2012 makes a county’s decentralised units equivalent to the constituencies within it, which is why nearly every Kenyan address form labels the constituency “sub-county”. The national government’s sub-counties are a separate set with different boundaries.

They overlap heavily but not completely: 248 of the 301 share a name with a constituency, and 53 do not. Baringo shows the divergence plainly. Six of each, and not the same six:

getSubCountiesByCounty('Baringo').map((s) => s.name)
// Baringo Central, Baringo North, Koibatek, Marigat, Mogotio, Tiaty

getConstituenciesByCounty('Baringo').map((k) => k.name)
// Baringo Central, Baringo North, Baringo South, Eldama Ravine, Mogotio, Tiaty

Why sub-counties have no numbers

Counties, constituencies and wards all carry official codes. Administrative sub-counties do not, so this package keys them by slug instead. Inventing a numbering would imply an authority the package does not have, and would be indistinguishable from the official codes elsewhere in the data. Slugs are unique across all 301, so they work as a primary key on their own.

Coverage

The source lists sub-counties against ward names rather than codes, so wards are matched by name within their county. 1,438 of the 1,450 wards map to a sub-county, or 99.2%. The remaining 12 have subCounty: null rather than a guess, and are listed in data/sources/name-conflicts.json. getWardsByCounty is always complete.

The national administration continues below this level: sub-county → division → location → sub-location, ending at the Assistant Chief. KNBS census enumeration uses that chain, which is why census microdata will not join cleanly to a ward-level table.

Below the sub-county the national administration keeps going, down to the Assistant Chief. The full chain, as enumerated by the 2009 census:

import { districts } from 'kenya-regions/districts'
import { subLocations } from 'kenya-regions/sublocations'

subLocations[0].population[2009]   // census population
subLocations[0].households
subLocations[0].areaKm2
subLocations[0].densityPerKm2

Sub-locations are the only level below county carrying population, household and area figures, because they are what the census counts. Their populations sum to exactly 38,610,097, the published 2009 national total, and the build asserts this, independently confirming all 7,150 rows.

Codes at these four levels are assigned by this package, derived deterministically from the sorted hierarchy so they stay stable across builds. Unlike county, constituency and ward codes they carry no official authority, and names repeat across parents, so a name alone is never a key.

All four are subpath-only and are not re-exported from kenya-regions. Sub-locations alone outweigh everything else in the package, so nobody pays for them unless they ask.

The single most likely silent bug when joining Kenyan datasets. ISO numbers the counties alphabetically. The Constitution numbers them geographically. They are never the same number.

getCounty(30).name        // 'Baringo'
getCounty('KE-30').name   // 'Nairobi'  ← a different county entirely

Both live on every county record as code and isoCode. isoToCounty() refuses a bare number, so the two cannot be mixed up by accident.

OCHA p-codes are the friendly ones: they follow the constitutional numbering exactly, so KE047 is county 47, and constituency p-codes append the constituency code, giving KE047275.

Every identifier the package holds for a single county, side by side. Sort the list by each numbering scheme to see how far apart they run.

The counties, drawn from the outlines the package ships. Hover to name one; click to open it in the atlas, where its constituencies, sub-counties and wards are laid out, along with the districts and divisions that occupied the same ground before 2013.

The same geometry ships three ways: as GeoJSON from kenya-regions/outlines, as a styleable data/svg/counties.svg, and as an svg_path column in data/csv/county-outlines.csv for anyone drawing a map without a mapping library.

Every dataset is exported directly as a frozen array, in code order. Import it and use it.

Raw JSON is published too, for anyone who wants the data without the API:

import counties from 'kenya-regions/data/counties.json' with { type: 'json' }

Every lookup accepts a Query, which is number | string and covers each way a region is normally identified. Matching ignores case, spacing, apostrophes, slashes and hyphens, so 'Elgeyo/Marakwet', 'elgeyo-marakwet' and 'ELGEYO MARAKWET' all resolve.

Downwards

getConstituenciesByCounty('nairobi')   // 17
getConstituenciesByCounty('KE-30')     // the same 17
getWardsByCounty('Kiambu')             // 60
getWardsByConstituency('Westlands')

Upwards

const { ward, constituency, county } = getWardLineage(1389)!
`${ward.name}, ${constituency.name}, ${county.name} County`
// 'Woodley/Kenyatta Golf Course, Kibra, Nairobi County'

Sub-counties

subCounties.length                    // 301
getSubCounty('koibatek')              // by slug
getSubCounty('Koibatek')              // by name
getSubCountiesByCounty('Kericho')     // 6
getWardsBySubCounty('koibatek')       // full ward records
getSubCountyOfWard(1)                 // Changamwe

Nested trees

const nairobi = getCountyTree('nairobi')!
nairobi.constituencies[0].wards

search('kis', { levels: ['county'], limit: 5 })
search('mbita')                      // → Suba North, matched: 'Mbita'
search('nairobi', { levels: ['ward'] })

Each result carries level, the region record, a score from 0 to 1, and matched, the actual string that matched, which may be an alias rather than the current name. Showing matched in the UI explains to the user why a result appeared.

Ranking is tiered rather than purely fuzzy: exact match, then prefix, then substring, then whole-token prefix, then edit distance. Counties break ties upward, because “Kisumu” is a county, a constituency and a ward, and the county is almost always the intended answer.

The most common reason to install this package is a dropdown, so the shape is provided directly.

countyOptions()
// [{ label: 'Baringo', value: '30', region: {…} }, …]  alphabetical

countyOptions({ alphabetical: false, valueKey: 'slug' })
constituencyOptions({ county: 47 })
wardOptions({ constituency: 'Westlands' })

valueKey accepts 'code', 'slug' or 'name', plus 'isoCode' and 'pcode' for counties, which helps when the value has to match what a backend already stores.

Above every subdivision sits kenya: the identifiers the rest of the world uses, and the national figures the subdivisions roll up to.

import { kenya } from 'kenya-regions'

kenya.codes.iso3166Alpha2         // 'KE'    ISO 3166-1
kenya.codes.iso3166Alpha3         // 'KEN'
kenya.codes.unM49                 // '404'   UN statistical
kenya.codes.callingCode           // '+254'  ITU
kenya.currency.code               // 'KES'   ISO 4217
kenya.timeZone.iana               // 'Africa/Nairobi'
kenya.location.borders            // ETH SOM SSD TZA UGA
kenya.location.boundingBox        // { west, south, east, north }

The codes nest into the subdivision data, and the build asserts it: every county isoCode extends codes.iso3166Alpha2, and every county pcode extends codes.ochaPcode. The country record is the root of the same code trees the counties sit in.

Where Kenya sits in UN M49

001 World → 002 Africa → 202 Sub-Saharan Africa → 014 Eastern Africa → 404 Kenya

Derived, never typed in

kenya.subdivisions and kenya.legislature are computed from the actual datasets at build time, so they cannot drift out of step with them.

Speakers sit ex officio and are excluded from the totals.

Helpers

toInternationalPhone('0712 345 678')  // '+254712345678'
toInternationalPhone('12345')         // undefined
formatCurrency(1234.5)                // 'KSh 1,234.50'
isPostalCode('00100')                 // true

Coarse county outlines ship with this package, at about 15 KB gzipped. Enough to draw a national map and to answer which county a point falls in.

import { countyOutlines, locateCounty } from 'kenya-regions/outlines'

map.addSource('counties', { type: 'geojson', data: countyOutlines })

locateCounty(-1.2864, 36.8172)?.properties.name   // 'Nairobi'
locateCounty(51.5, -0.12)                         // undefined, not in Kenya

Arguments are latitude then longitude, matching how coordinates are spoken and written, even though GeoJSON stores them the other way round.

Every county record also carries a bbox, so a map can be fitted to a county without loading any geometry at all:

getCounty('Nairobi').bbox   // [36.663, -1.442, 37.104, -1.158]

Finer tiers and other levels

Not published. Boundaries at higher detail, and levels below the county, are parked in kenya-regions-geo, which is not on npm. It waits for a use case the outlines here do not already cover.

The gap worth having is constituency and ward boundaries. That is blocked on finding a source whose geometry can be trusted rather than on effort: the obvious one has its Nairobi polygons carrying the administrative sub-counties rather than the constituencies, so a point in the CBD resolves to the wrong constituency. See the plan.

interface County {
  code: number              // 1–47, constitutional
  name: string
  slug: string
  capital: string
  isoCode: string           // 'KE-01'–'KE-47', alphabetical, not code
  pcode: string             // 'KE001'–'KE047', OCHA
  formerProvince: string
  formerProvinceCode: ProvinceCode
  economicBlocs: BlocCode[] // may be empty, may hold several
  asal: 'arid' | 'semi-arid' | null
  cityStatusSince: number | null
  areaKm2: number
  population: { 2009: number; 2019: number }
  centroid: { lat: number; lng: number } | null
  bbox: [number, number, number, number] | null   // west, south, east, north
  aliases: string[]
}

interface Constituency {
  code: number              // 1–290
  name: string
  slug: string
  countyCode: number
  pcode: string             // e.g. 'KE047275'
  areaKm2: number | null
  centroid: { lat: number; lng: number } | null
  aliases: string[]
}

interface Ward {
  code: number              // 1–1450
  name: string
  slug: string
  constituencyCode: number
  countyCode: number
  subCounty: string | null  // sub-county slug; null for 12 unmatched wards
  aliases: string[]
}

interface SubCounty {
  slug: string              // primary key; these units have no official code
  name: string
  countyCode: number
  constituencyCode: number | null   // same-name constituency, if any
  wardCodes: number[]
}

Also exported: Country, Province, EconomicBloc, CountyNode, ConstituencyNode, SearchResult, RegionOption, WardLineage, Level, Query, AsalClass, ProvinceCode, BlocCode and the country sub-types.

Dependent county → constituency → ward selects

const [county, setCounty] = useState<string>()
const [constituency, setConstituency] = useState<string>()

<select onChange={(e) => { setCounty(e.target.value); setConstituency(undefined) }}>
  <option value="">Select a county</option>
  {countyOptions().map((o) => (
    <option key={o.value} value={o.value}>{o.label}</option>
  ))}
</select>

<select disabled={!county} onChange={(e) => setConstituency(e.target.value)}>
  {constituencyOptions({ county: Number(county) }).map((o) => (
    <option key={o.value} value={o.value}>{o.label}</option>
  ))}
</select>

<select disabled={!constituency}>
  {wardOptions({ constituency: Number(constituency) }).map((o) => (
    <option key={o.value} value={o.value}>{o.label}</option>
  ))}
</select>

Validating a submitted address

function validate(countyCode: number, wardCode: number) {
  const lineage = getWardLineage(wardCode)
  if (!lineage) return 'Unknown ward'
  if (lineage.county.code !== countyCode) {
    return `That ward is in ${lineage.county.name}, not the county selected`
  }
  return null
}

Joining against a dataset that uses ISO codes

// A dataset keyed 'KE-01'…'KE-47' must go through isoToCounty,
// never getCounty(Number(...)): the two numbers are unrelated.
const rows = external.map((row) => ({
  ...row,
  county: isoToCounty(row.iso),
}))

Grouping counties for a regional report

const byProvince = provinces.map((province) => ({
  province: province.name,
  counties: getCountiesByProvince(province.code),
  population: getCountiesByProvince(province.code)
    .reduce((total, county) => total + county.population[2019], 0),
}))

Import from a subpath and nothing else is bundled. These are real measurements, taken with esbuild, minified, from a clean install of the packed tarball:

Six times smaller for the same data, in the commonest case of all: a county dropdown.

How the large datasets are stored

Wards, locations and sub-locations ship as arrays of tuples, rebuilt into objects on import. Past a few thousand records the repeated JSON key names cost more than the values do. "formerProvinceCode":"RFT", is about 28 bytes on every row, so dropping the keys is the single biggest saving available.

Fields that can be derived are not stored at all: slug is computed from the name, and densityPerKm2 is recomputed as population over area. Rehydration costs a few milliseconds at import and is invisible to callers: the exported arrays are ordinary typed objects.

Raw JSON is published too:

import counties from 'kenya-regions/data/counties.json' with { type: 'json' }

Sources are committed in the repository under data/sources/, and npm run build:data regenerates every dataset from them offline. No figure in the package is unattributable.

How it is validated

The build refuses to emit anything unless all of the following hold, and the same assertions run again in the test suite on every commit:

• exactly 47 counties, 290 constituencies and 1450 wards
• codes form gapless 1–n sequences with no duplicates at every level
• every constituency belongs to a real county, and every ward agrees with its constituency about which county it is in
• no county without constituencies, no constituency without wards
• county → constituency assignment agrees between two independent sources
• ISO codes, p-codes and slugs are unique
• 23 ASAL counties, 9 of them arid
• 301 sub-counties spanning all 47 counties, none without wards, every ward in the same county as its sub-county, and the ward back-reference round-trips
• 158 districts, 635 divisions, 2723 locations and 7150 sub-locations, each level agreeing with its parent about its ancestry, none childless, and sub-location populations summing to the published 2009 national total
• the country record agrees with the datasets: population equals the sum of the counties, the capital resolves to a real county, every county code extends the country’s, and each chamber’s seats add up

Stated plainly rather than papered over, so you can judge whether they affect your use.

Ward name variants

Official sources spell some ward names differently: Wargadud / Wargudud, Ndavaya / Nadavaya. Where the variants are clearly the same place, the alternative is attached as a searchable alias, so lookups succeed either way.

27 ward code conflicts

For 27 of the 1450 wards, two official sources disagree about which numeric code belongs to which ward within the same constituency. County and constituency membership is unaffected, so no lookup returns a wrong parent. They are listed in data/sources/name-conflicts.json rather than silently resolved in favour of whichever source loaded first.

Ward names are not unique nationally

Several counties have a “Township” or a “Central” ward. Use codes, or scope by constituency, when it matters.

12 wards have no sub-county

The sub-county source spells them differently enough that no confident match was possible, so ward.subCounty is null rather than guessed, giving 99.2% coverage. They are listed in data/sources/name-conflicts.json, and getWardsByCounty is always complete.

The sub-county count is behind

301 ships against a current figure of about 341. See the sub-counties section for why the gap is documented rather than guessed at.

The census hierarchy is a 2009 snapshot

Districts no longer exist as administrative units, and divisions, locations and sub-locations have been gazetted since.

ASAL is recorded at county level

The underlying reality is sub-county level: some ASAL areas sit inside counties that are otherwise not ASAL.

Two national areas that do not reconcile

kenya.area.totalKm2 is 580,367 km², the internationally cited figure. The gazetted county areas sum to roughly 591,346 km². The two are measured differently, so the build does not assert they match.

No administrative sub-counties

Covered above: the term is ambiguous, so neither set is shipped under that name.