rwanda-geo-structure Documentation

Introduction

rwanda-geo-structure is a comprehensive JavaScript package that provides easy access to Rwanda's administrative divisions. It allows developers to retrieve and work with data about provinces, districts, sectors, cells, and villages in Rwanda, streamlining the process of collecting and managing location-based data for applications focused on Rwanda.

This package is essential for developers working on projects that require accurate and up-to-date information about Rwanda's geographical structure. It can be used in various applications, including but not limited to:

Installation

To install the Rwanda Geo Structure package, run the following command in your project directory: 

npm install rwanda-geo-structure

or if you're using Yarn:

yarn add rwanda-geo-structure

After installation, you can import the package in your JavaScript or TypeScript files and start using its functions immediately.

Usage

After installation, you can import and use the functions provided by the package. Here's a basic example of how to use some of the core functions: 

import { getProvinces, getDistrictsByProvince, getSectorsByDistrict } from 'rwanda-geo-structure'; // Get all provinces const provinces = getProvinces(); console.log('Provinces:', provinces); // Get districts in a specific province const kigaliDistricts = getDistrictsByProvince('Kigali City'); console.log('Districts in Kigali City:', kigaliDistricts); // Get sectors in a specific district const sectors = getSectorsByDistrict('Kigali City', 'Gasabo'); console.log('Sectors in Gasabo district:', sectors);

This package provides a hierarchical structure of Rwanda's administrative divisions, allowing you to navigate from the country level down to individual villages.

API Reference

getCountry()

Returns the country name.

Returns: string - Always returns "Rwanda"

This function is useful when you need to explicitly specify the country in your application or when you're extending the package to potentially include other countries in the future. 

import { getCountry } from 'rwanda-geo-structure'; const country = getCountry(); console.log(country); // Output: "Rwanda"

getProvinces()

Retrieves all provinces in Rwanda.

Returns: string[] - An array of province names

This function is crucial for applications that need to display or process data at the provincial level. It provides a comprehensive list of all provinces in Rwanda. 

import { getProvinces } from 'rwanda-geo-structure'; const provinces = getProvinces(); console.log(provinces); // Output: ['Eastern Province', 'Kigali City', 'Northern Province', 'Southern Province', 'Western Province']

getDistricts()

Retrieves all districts in Rwanda.

Returns: string[] - An array of district names

This function provides a complete list of all districts in Rwanda, regardless of their province. It's useful when you need a comprehensive view of all districts in the country. 

import { getDistricts } from 'rwanda-geo-structure'; const allDistricts = getDistricts(); console.log(allDistricts); // Output: ['Bugesera', 'Gatsibo', 'Kayonza', 'Kirehe', 'Ngoma', 'Nyagatare', 'Rwamagana', 'Gasabo', 'Kicukiro', 'Nyarugenge', ...]

getDistrictsByProvince(province: string)

Retrieves all districts within a specified province.

Parameters:

Returns: string[] - An array of district names within the specified province

This function is essential when you need to display or process districts within a specific province. It's particularly useful for creating cascading dropdown menus or filtering data by province and district. 

import { getDistrictsByProvince } from 'rwanda-geo-structure'; const kigaliDistricts = getDistrictsByProvince('Kigali City'); console.log(kigaliDistricts); // Output: ['Gasabo', 'Kicukiro', 'Nyarugenge'] const westernDistricts = getDistrictsByProvince('Western Province'); console.log(westernDistricts); // Output: ['Karongi', 'Ngororero', 'Nyabihu', 'Nyamasheke', 'Rubavu', 'Rutsiro', 'Rusizi']

getSectors()

Retrieves all sectors in Rwanda.

Returns: string[] - An array of sector names

This function provides a comprehensive list of all sectors in Rwanda, regardless of their district or province. It's useful when you need an overview of all sectors in the country. 

import { getSectors } from 'rwanda-geo-structure'; const allSectors = getSectors(); console.log(allSectors); // Output: ['Gitega', 'Kanyinya', 'Kigali', 'Kimisagara', 'Mageragere', 'Muhima', ...]

getSectorsByDistrict(province: string, district: string)

Retrieves all sectors within a specified district.

Parameters:

Returns: string[] - An array of sector names within the specified district

This function is crucial for applications that need to display or process data at the sector level within a specific district. It's particularly useful for creating multi-level dropdown menus or for data analysis at the district and sector level. 

import { getSectorsByDistrict } from 'rwanda-geo-structure'; const gasaboSectors = getSectorsByDistrict('Kigali City', 'Gasabo'); console.log(gasaboSectors); // Output: ['Bumbogo', 'Gatsata', 'Gikomero', 'Gisozi', 'Jabana', 'Jali', 'Kacyiru', 'Kimihurura', 'Kimironko', 'Kinyinya', 'Ndera', 'Nduba', 'Remera', 'Rusororo', 'Rutunga']

getCells()

Retrieves all cells in Rwanda.

Returns: string[] - An array of cell names

This function provides a complete list of all cells in Rwanda, regardless of their sector, district, or province. It's useful when you need a comprehensive view of all cells in the country. 

import { getCells } from 'rwanda-geo-structure'; const allCells = getCells(); console.log(allCells); // Output: ['Agatare', 'Biryogo', 'Kiyovu', 'Nyarugenge', 'Rwampara', 'Umujyi wa Huye', ...]

getCellsBySector(province: string, district: string, sector: string)

Retrieves all cells within a specified sector.

Parameters:

Returns: string[] - An array of cell names within the specified sector

This function is essential for applications that need to display or process data at the cell level within a specific sector. It's particularly useful for creating detailed geographical selections or for analyzing data at a granular level. 

import { getCellsBySector } from 'rwanda-geo-structure'; const remeraCells = getCellsBySector('Kigali City', 'Gasabo', 'Remera'); console.log(remeraCells); // Output: ['Nyabisindu', 'Nyarutarama', 'Rukiri I', 'Rukiri II', 'Rusororo']

getVillages()

Retrieves all villages in Rwanda.

Returns: string[] - An array of village names

This function provides a comprehensive list of all villages in Rwanda, regardless of their cell, sector, district, or province. It's useful when you need an overview of all villages in the country, but be aware that this list can be quite extensive. 

import { getVillages } from 'rwanda-geo-structure'; const allVillages = getVillages(); console.log(allVillages); // Output: ['Abatarushwa', 'Abizerwa', 'Agatare', 'Akabahizi', 'Akabeza', ...]

getVillagesByCell(province: string, district: string, sector: string, cell: string)

Retrieves all villages within a specified cell.

Parameters:

Returns: string[] - An array of village names within the specified cell

This function is crucial for applications that require the most detailed level of geographical data in Rwanda. It's particularly useful for applications dealing with very specific locations, such as delivery services or detailed demographic studies. 

import { getVillagesByCell } from 'rwanda-geo-structure'; const nyabisinduVillages = getVillagesByCell('Kigali City', 'Gasabo', 'Remera', 'Nyabisindu'); console.log(nyabisinduVillages); // Output: ['Amarembo I', 'Amarembo II', 'Gihogere', 'Kagara', 'Kinunga', 'Nyabisindu']

getRandomLocation()

Generates a random location in Rwanda, including province, district, sector, cell, and village.

Returns: Object - An object containing randomly selected location data

This function is particularly useful for generating test data, creating mock scenarios, or for educational purposes to explore Rwanda's administrative divisions. It provides a complete, randomly selected location from province down to village level. 

import { getRandomLocation } from 'rwanda-geo-structure'; const randomLocation = getRandomLocation(); console.log(randomLocation); // Output example: // { // province: 'Southern Province', // district: 'Huye', // sector: 'Ngoma', // cell: 'Butare', // village: 'Akabuye' // }

countLocations()

Counts the number of administrative divisions at each level in Rwanda.

Returns: Object - An object containing the count of each administrative division

This function provides a quick overview of the number of administrative divisions at each level in Rwanda. It's useful for understanding the scale of the geographical data and for statistical purposes. 

import { countLocations } from 'rwanda-geo-structure'; const locationCounts = countLocations(); console.log(locationCounts); // Output example: // { // provinces: 5, // districts: 30, // sectors: 416, // cells: 2148, // villages: 14837 // }

Examples

Here are some more detailed examples of how to use the Rwanda Geo Structure package in your projects:

Creating a Cascading Dropdown for Location Selection

import React, { useState, useEffect } from 'react'; import { getProvinces, getDistrictsByProvince, getSectorsByDistrict, getCellsBySector, getVillagesByCell } from 'rwanda-geo-structure'; function LocationSelector() { const [provinces, setProvinces] = useState([]); const [districts, setDistricts] = useState([]); const [sectors, setSectors] = useState([]); const [cells, setCells] = useState([]); const [villages, setVillages] = useState([]); const [selectedProvince, setSelectedProvince] = useState(''); const [selectedDistrict, setSelectedDistrict] = useState(''); const [selectedSector, setSelectedSector] = useState(''); const [selectedCell, setSelectedCell] = useState(''); const [selectedVillage, setSelectedVillage] = useState(''); useEffect(() => { setProvinces(getProvinces()); }, []); useEffect(() => { if (selectedProvince) { setDistricts(getDistrictsByProvince(selectedProvince)); setSelectedDistrict(''); setSelectedSector(''); setSelectedCell(''); setSelectedVillage(''); } }, [selectedProvince]); useEffect(() => { if (selectedDistrict) { setSectors(getSectorsByDistrict(selectedProvince, selectedDistrict)); setSelectedSector(''); setSelectedCell(''); setSelectedVillage(''); } }, [selectedProvince, selectedDistrict]); useEffect(() => { if (selectedSector) { setCells(getCellsBySector(selectedProvince, selectedDistrict, selectedSector)); setSelectedCell(''); setSelectedVillage(''); } }, [selectedProvince, selectedDistrict, selectedSector]); useEffect(() => { if (selectedCell) { setVillages(getVillagesByCell(selectedProvince, selectedDistrict, selectedSector, selectedCell)); setSelectedVillage(''); } }, [selectedProvince, selectedDistrict, selectedSector, selectedCell]); return ( <div> <select value={selectedProvince} onChange={(e) => setSelectedProvince(e.target.value)}> <option value="">Select Province</option> {provinces.map(province => ( <option key={province} value={province}>{province}</option> ))} </select> <select value={selectedDistrict} onChange={(e) => setSelectedDistrict(e.target.value)} disabled={!selectedProvince}> <option value="">Select District</option> {districts.map(district => ( <option key={district} value={district}>{district}</option> ))} </select> <select value={selectedSector} onChange={(e) => setSelectedSector(e.target.value)} disabled={!selectedDistrict}> <option value="">Select Sector</option> {sectors.map(sector => ( <option key={sector} value={sector}>{sector}</option> ))} </select> <select value={selectedCell} onChange={(e) => setSelectedCell(e.target.value)} disabled={!selectedSector}> <option value="">Select Cell</option> {cells.map(cell => ( <option key={cell} value={cell}>{cell}</option> ))} </select> <select value={selectedVillage} onChange={(e) => setSelectedVillage(e.target.value)} disabled={!selectedCell}> <option value="">Select Village</option> {villages.map(village => ( <option key={village} value={village}>{village}</option> ))} </select> </div> ); } export default LocationSelector;

Generating Random Test Data

import { getRandomLocation, countLocations } from 'rwanda-geo-structure'; function generateTestData(count) { const testData = []; const locationCounts = countLocations(); for (let i = 0; i < count; i++) { const location = getRandomLocation(); testData.push({ id: i + 1, name: `Test User ${i + 1}`, ...location }); } console.log(`Generated ${count} test users`); console.log(`Total locations in Rwanda: `, locationCounts); return testData; } const testUsers = generateTestData(10); console.log(testUsers);

Creating a Location Statistics Dashboard

import { countLocations, getProvinces, getDistrictsByProvince } from 'rwanda-geo-structure'; function LocationStatistics() { const stats = countLocations(); const provinces = getProvinces(); const provinceStats = provinces.map(province => ({ name: province, districts: getDistrictsByProvince(province).length })); return ( <div> <h1>Rwanda Location Statistics</h1> <h2>Overall Statistics</h2> <ul> <li>Total Provinces: {stats.provinces}</li> <li>Total Districts: {stats.districts}</li> <li>Total Sectors: {stats.sectors}</li> <li>Total Cells: {stats.cells}</li> <li>Total Villages: {stats.villages}</li> </ul> <h2>Province-wise Statistics</h2> <ul> {provinceStats.map(province => ( <li key={province.name}> {province.name}: {province.districts} districts </li> ))} </ul> </div> ); } export default LocationStatistics;

Contributing

Contributions to the Rwanda Geo Structure package are welcome! Here are some ways you can contribute:

  1. Report bugs or request features by opening an issue on the GitHub repository.
  2. Submit pull requests to fix bugs or add new features. Please ensure your code adheres to the existing style and that all tests pass.
  3. Improve documentation or add usage examples to help other developers understand and use the package more effectively.
  4. Share your experience using the package and suggest improvements based on real-world usage scenarios.

Before making significant changes, please open an issue to discuss your proposed changes. This helps ensure that your contribution aligns with the project's goals and direction.

License

This project is licensed under the MIT License. This means you are free to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the software, subject to the following conditions:

For the full license text, please see the LICENSE file in the project repository.