https://github.com/knowbee/rwanda
🇷🇼This is a simple npm package that returns provinces, districts, sectors, villages and cells from Rwanda
https://github.com/knowbee/rwanda
rwanda
Last synced: 5 months ago
JSON representation
🇷🇼This is a simple npm package that returns provinces, districts, sectors, villages and cells from Rwanda
- Host: GitHub
- URL: https://github.com/knowbee/rwanda
- Owner: knowbee
- License: mit
- Created: 2019-11-30T10:30:29.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2025-08-08T10:37:31.000Z (11 months ago)
- Last Synced: 2025-10-23T21:11:44.101Z (8 months ago)
- Topics: rwanda
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/rwanda
- Size: 851 KB
- Stars: 48
- Watchers: 4
- Forks: 21
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# rwanda
[](https://www.npmjs.com/package/rwanda)
[](https://www.npmjs.com/package/rwanda)
[](https://opensource.org/licenses/MIT)
[](http://www.typescriptlang.org/)
A comprehensive TypeScript/JavaScript library for accessing administrative divisions of Rwanda. This package provides type-safe access to provinces, districts, sectors, cells, and villages in Rwanda.
Rwanda is administratively organized into:
- 5 Provinces (including Kigali City)
- 30 Districts
- 416 Sectors
- 2,148 Cells
- 14,837 Villages
## Installation
```bash
# Using npm
npm install rwanda
# Using yarn
yarn add rwanda
# Using pnpm
pnpm add rwanda
```
## Usage
### JavaScript (CommonJS)
```javascript
const { Provinces, Districts } = require('rwanda');
console.log(Provinces());
// Output: ['East', 'Kigali', 'North', 'South', 'West']
console.log(Districts('kigali'));
// Output: ['Gasabo', 'Kicukiro', 'Nyarugenge']
```
### TypeScript / ES Modules
```typescript
import { Provinces, Districts, Sectors } from 'rwanda';
// Get all provinces
const provinces: string[] = Provinces();
// Get districts in Kigali
const kigaliDistricts: string[] = Districts('kigali');
// Get sectors in Gasabo district
const gasaboSectors: string[] = Sectors('kigali', 'gasabo');
```
## API Reference
### `Provinces(): string[]`
Returns an array of all provinces in Rwanda.
```typescript
import { Provinces } from 'rwanda';
const provinces = Provinces();
// Returns: ['East', 'Kigali', 'North', 'South', 'West']
```
### `Districts(province?: string): string[] | undefined`
- `province` (optional): Name of the province to filter districts
Returns an array of districts. If a province is provided, returns only districts in that province.
```typescript
import { Districts } from 'rwanda';
// Get all districts in Rwanda
const allDistricts = Districts();
// Get districts in Kigali
const kigaliDistricts = Districts('kigali');
// Returns: ['Gasabo', 'Kicukiro', 'Nyarugenge']
```
### `Sectors(province?: string, district?: string): string[] | undefined`
- `province` (optional): Name of the province
- `district` (optional): Name of the district to filter sectors
Returns sectors based on the provided filters.
```typescript
import { Sectors } from 'rwanda';
// Get all sectors in Rwanda
const allSectors = Sectors();
// Get sectors in Gasabo district, Kigali
const gasaboSectors = Sectors('kigali', 'gasabo');
```
### `Cells(province?: string, district?: string, sector?: string): string[] | undefined`
- `province` (optional): Name of the province
- `district` (optional): Name of the district
- `sector` (optional): Name of the sector to filter cells
Returns cells based on the provided filters.
### `Villages(province?: string, district?: string, sector?: string, cell?: string): string[] | undefined`
- `province` (optional): Name of the province
- `district` (optional): Name of the district
- `sector` (optional): Name of the sector
- `cell` (optional): Name of the cell to filter villages
Returns villages based on the provided filters.
## Type Safety
The package includes TypeScript type definitions out of the box. All functions are properly typed:
```typescript
// TypeScript will infer the return type as string[]
const districts: string[] = Districts('kigali');
// TypeScript will show an error for invalid province names
const invalid = Districts('invalid'); // TypeScript error
```
## Case Insensitivity
All input parameters are case-insensitive:
```typescript
// All these are equivalent
Districts('kigali');
Districts('Kigali');
Districts('KIGALI');
```
## Error Handling
When invalid parameters are provided, the functions return `undefined`:
```typescript
const result = Districts('Nonexistent Province');
console.log(result); // undefined
```
```cli
yarn add rwanda
```
# Contributors
Shyaka Davis
Karl MUSINGO
Yves Iraguha
Abayo Luc
Olivier Esuka
Igwaneza Bruce