zw-places

Zimbabwe administrative places for developers.

zw-places provides provinces and districts by default, with wards available from a separate entry point so apps do not load the larger ward dataset unless they need it.

Install

npm install zw-places

Python and Flutter packages are also available from this repository:

pip install zw-places

dependencies:
  zw_places: ^0.1.0

Usage

ESM

import { getDistrict, getDistricts, getProvince, searchPlaces } from "zw-places";

getProvince("ZW12");
getDistricts("Manicaland");
getDistrict("Centenary");
searchPlaces("Muzarabani", { levels: ["admin2"] });

CommonJS

const { getDistricts, getProvince } = require("zw-places");

getProvince("12");
getDistricts("Mashonaland Central");

Wards

Wards are intentionally separate because wards.json is much larger than the province and district data.

import { getWards } from "zw-places/wards";

getWards("Harare");

const { getWards } = require("zw-places/wards");

getWards("ZW19");

Data Included

• 10 provinces
• 91 districts
• 1961 wards
• official PCodes
• center coordinates
• area in square kilometers
• aliases for common alternate names

API

Default lightweight entry point:

import {
  metadata,
  provinces,
  districts,
  getMetadata,
  getProvinces,
  getProvince,
  getDistricts,
  getDistrict,
  getPlace,
  getProvinceForDistrict,
  getDistrictForWard,
  getChildren,
  getAncestors,
  searchPlaces,
  formatAddress,
  validateAddress,
  isValidProvince,
  isValidDistrict,
  normalize,
} from "zw-places";

getPlace("ZW1209");
getChildren("ZW12");
getAncestors("ZW1209");
searchPlaces("muzarab", { levels: ["admin2", "admin3"], limit: 10 });
formatAddress({ province: "ZW12", district: "ZW1209" });
validateAddress({ province: "ZW12", district: "ZW1209" });

Ward entry point:

import { wards, getWards, getWard, searchWards, isValidWard } from "zw-places/wards";

Other Packages

• Python package source: packages/python
• Flutter package source: packages/flutter

Validation commands:

PYTHONPATH=packages/python/src python3 -m unittest discover -s packages/python/tests
cd packages/flutter && flutter pub get && flutter analyze && flutter test

Raw JSON entry points for CommonJS or bundlers:

const provinces = require("zw-places/data/provinces.json");
const districts = require("zw-places/data/districts.json");
const wards = require("zw-places/data/wards.json");

CLI

Run locally from this repository:

npm run cli -- provinces
npm run cli -- province ZW12
npm run cli -- districts Manicaland
npm run cli -- district Mvurwi --json
npm run cli -- search muzarabani
npm run cli -- place ZW1209 --json
npm run cli -- children ZW12
npm run cli -- ancestors ZW1209
npm run cli -- validate ZW12 ZW1209
npm run cli -- wards Harare --limit 5

After package installation, the binary is:

zw-places province ZW12
zw-places wards Harare --json --limit 5

Bundle Size Warning

The default package entry point does not export or load wards. Import from zw-places/wards only when ward-level data is needed.

Approximate generated file sizes:

• data/provinces.json: small
• data/districts.json: medium
• data/wards.json: large
• data/all.json: large and intended for direct data users

License

CC BY 3.0 IGO. See LICENSE.