🇧🇼 Botswana Locations

A lightweight NPM package for finding Botswana locations and their districts.

botswana-locations provides a simple, fast, and developer-friendly way to look up Botswana locations and determine the district associated with each location.

It is designed for developers building web applications, mobile applications, APIs, dashboards, delivery platforms, e-commerce systems, registration forms, and other software that needs Botswana location data.

The package works locally and does not require an external API, database, API key, or internet connection for location lookups.

📦 Installation

Install with NPM:

npm install botswana-locations

Using Yarn:

yarn add botswana-locations

Using pnpm:

pnpm add botswana-locations

🚀 Quick Start

Import the functions you need:

const {
  getDistrict,
  findLocation,
  searchLocations,
  getLocations,
} = require("botswana-locations");

Find the district of a location:

const district = getDistrict("Gaborone");

console.log(district);

Output:

Gaborone

That's all that is required to perform a location-to-district lookup.

✨ Features

• 🇧🇼 Botswana-focused location dataset
• 📍 Location-to-district lookup
• 🔎 Location searching
• 🔤 Case-insensitive lookups
• 🔍 Partial text searching
• ⚡ Fast local lookups
• 📴 Offline-friendly
• 🌐 No external API required
• 🔑 No API key required
• 💾 No database required
• 📦 Lightweight
• 🧩 Simple JavaScript API
• ⚛️ React compatible
• 📱 React Native compatible
• 🚀 Expo compatible
• 🖥️ Node.js compatible
• 🌐 Express.js compatible
• ⚡ Next.js compatible
• 🛠️ Vite compatible

🎯 What Does This Package Do?

The main purpose of the package is simple:

Location → District

For example:

getDistrict("Gaborone");

returns:

Gaborone

You can also retrieve the complete location record:

findLocation("Gaborone");

which returns:

{
  name: "Gaborone",
  district: "Gaborone"
}

The package provides a reusable location dataset so developers do not have to manually create and maintain their own Botswana location mappings.

🧩 API Reference

The package currently provides four main functions:

| Function | Description | | ------------------- | ----------------------------------------------- | | getDistrict() | Returns the district associated with a location | | findLocation() | Returns the location and district | | searchLocations() | Searches locations by name | | getLocations() | Returns the complete location dataset |

🗺️ getDistrict()

Returns the district associated with a location.

Syntax

getDistrict(location);

Example

const { getDistrict } = require("botswana-locations");

const district = getDistrict("Gaborone");

console.log(district);

Output:

Gaborone

Case-Insensitive Lookup

The lookup is case-insensitive.

All of the following work:

getDistrict("Gaborone");

getDistrict("gaborone");

getDistrict("GABORONE");

getDistrict("GaBoRoNe");

Each returns:

Gaborone

Location Not Found

If the location does not exist in the dataset, getDistrict() returns null.

const district = getDistrict("Unknown Location");

console.log(district);

Output:

null

This makes it easy to handle locations that are not available in the dataset.

🔎 findLocation()

findLocation() returns the complete location record.

Syntax

findLocation(location);

Example

const { findLocation } = require("botswana-locations");

const location = findLocation("Gaborone");

console.log(location);

Output:

{
  name: "Gaborone",
  district: "Gaborone"
}

Location Not Found

If the location cannot be found:

const location = findLocation("Unknown Location");

console.log(location);

Returns:

null

🔍 searchLocations()

searchLocations() allows developers to search for locations using part of a location name.

Syntax

searchLocations(query);

Example

const { searchLocations } = require("botswana-locations");

const results = searchLocations("gabo");

console.log(results);

Example result:

[
  {
    name: "Gaborone",
    district: "Gaborone",
  },
];

Partial Search

You do not need to provide the complete location name.

For example:

searchLocations("gabo");

can find:

Gaborone

You can also search using another part of a location name:

searchLocations("bor");

Case-Insensitive Search

Searches are case-insensitive.

searchLocations("gabo");

searchLocations("GABO");

searchLocations("Gabo");

These return the same results.

No Results

If no matching locations are found:

const results = searchLocations("xyz");

console.log(results);

Returns:

[];

📚 getLocations()

getLocations() returns all locations included in the package.

Example

const { getLocations } = require("botswana-locations");

const locations = getLocations();

console.log(locations);

Each location follows the same structure:

{
  name: "Gaborone",
  district: "Gaborone"
}

🧱 Data Structure

The package intentionally keeps every location record simple.

Each record contains only two properties:

{
  name: "Location Name",
  district: "District Name"
}

name

The name of the Botswana location.

Example:

{
  name: "Gaborone";
}

district

The district associated with that location.

Example:

{
  district: "Gaborone";
}

A complete record therefore looks like:

{
  name: "Gaborone",
  district: "Gaborone"
}

⚛️ React Applications

botswana-locations can be used directly in React applications.

It is useful for:

• Registration forms
• Address forms
• Location selectors
• District selectors
• Delivery applications
• E-commerce checkout
• Business registration
• Search interfaces
• Dashboards
• Data collection systems

Install the package:

npm install botswana-locations

Import it into your React component:

import { useState } from "react";

import { getDistrict, searchLocations } from "botswana-locations";

function LocationForm() {
  const [location, setLocation] = useState("");
  const [district, setDistrict] = useState("");

  const handleLocationChange = (value) => {
    setLocation(value);
    setDistrict(getDistrict(value) || "");
  };

  return (
    <div>
      <input
        value={location}
        onChange={(e) => handleLocationChange(e.target.value)}
        placeholder="Enter location"
      />

      <p>District: {district}</p>
    </div>
  );
}

export default LocationForm;

If the user enters:

Gaborone

the application can automatically display:

District: Gaborone

🔎 React Location Search

You can also create a location search component.

import { useState } from "react";

import { searchLocations } from "botswana-locations";

function LocationSearch() {
  const [query, setQuery] = useState("");

  const results = query ? searchLocations(query) : [];

  return (
    <div>
      <input
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder="Search Botswana locations"
      />

      {results.map((location) => (
        <div key={location.name}>
          <strong>{location.name}</strong>
          <span> — {location.district}</span>
        </div>
      ))}
    </div>
  );
}

export default LocationSearch;

This can be used to build custom location selectors and autocomplete interfaces.

📱 React Native Applications

The package can also be used in React Native applications.

Install:

npm install botswana-locations

Import:

import { getDistrict, findLocation, searchLocations } from "botswana-locations";

Example:

import { useState } from "react";

import { View, Text, TextInput } from "react-native";

import { getDistrict } from "botswana-locations";

export default function LocationScreen() {
  const [location, setLocation] = useState("");
  const [district, setDistrict] = useState("");

  const handleLocationChange = (value) => {
    setLocation(value);
    setDistrict(getDistrict(value) || "");
  };

  return (
    <View>
      <TextInput
        value={location}
        onChangeText={handleLocationChange}
        placeholder="Enter location"
      />

      <Text>District: {district}</Text>
    </View>
  );
}

Entering:

Gaborone

can automatically produce:

District: Gaborone

📱 Expo Applications

The package can also be installed in Expo and React Native projects.

npm install botswana-locations

Then use the same API:

import { getDistrict } from "botswana-locations";

const district = getDistrict("Gaborone");

console.log(district);

Because the dataset is bundled with the package, a location lookup does not require an API request.

🖥️ Node.js Applications

The package works directly with Node.js.

const { getDistrict } = require("botswana-locations");

console.log(getDistrict("Gaborone"));

Output:

Gaborone

🌐 Express.js Example

The package can be used inside an Express.js API.

const express = require("express");

const { getDistrict, findLocation } = require("botswana-locations");

const app = express();

app.get("/locations/:location/district", (req, res) => {
  const location = req.params.location;

  const district = getDistrict(location);

  if (!district) {
    return res.status(404).json({
      message: "Location not found",
    });
  }

  res.json({
    location,
    district,
  });
});

app.listen(3000, () => {
  console.log("API running on port 3000");
});

Request:

GET /locations/Gaborone/district

Response:

{
  "location": "Gaborone",
  "district": "Gaborone"
}

⚡ Next.js Applications

The package can be used in Next.js applications for:

• Forms
• API routes
• Server-side processing
• Location selectors
• Address systems
• Dashboards

Example:

import { getDistrict } from "botswana-locations";

const district = getDistrict("Gaborone");

🛠️ Vite Applications

The package can be installed in Vite-based applications:

npm install botswana-locations

Then import the functions:

import { getDistrict, searchLocations } from "botswana-locations";

🌐 Supported JavaScript Environments

| Environment | Support | | -------------------- | ------- | | Node.js | ✅ | | React | ✅ | | React Native | ✅ | | Expo | ✅ | | Express.js | ✅ | | Next.js | ✅ | | Vite | ✅ | | Web applications | ✅ | | Mobile applications | ✅ | | Backend applications | ✅ |

💡 Use Cases

📦 Delivery & Logistics

Delivery platforms can determine the district associated with a customer's location.

const { getDistrict } = require("botswana-locations");

const district = getDistrict("Gaborone");

console.log(district);

Possible uses include:

• Delivery zones
• Driver assignment
• Package routing
• Delivery reports
• Location-based pricing
• Delivery statistics

🛒 E-Commerce

Online stores can use the package during checkout.

Example flow:

Customer selects location
        ↓
Gaborone
        ↓
District lookup
        ↓
Gaborone

This can help applications organize orders and customers by district.

📝 Registration Forms

Applications can automatically determine the district when a user selects a location.

const district = getDistrict(selectedLocation);

The result can then be used to populate a district field automatically.

🗺️ Mapping Applications

Applications that work with known Botswana locations can use the package to associate locations with districts.

const { findLocation } = require("botswana-locations");

const location = findLocation("Gaborone");

console.log(location);

Output:

{
  name: "Gaborone",
  district: "Gaborone"
}

📊 Data Analysis

The package can be used to group application data by district.

const { getDistrict } = require("botswana-locations");

const locations = ["Gaborone", "Mahalapye", "Palapye", "Maun"];

const results = locations.map((location) => ({
  location,
  district: getDistrict(location),
}));

console.log(results);

This can be useful for:

• Reports
• Dashboards
• Statistics
• Business analytics
• Geographic analysis

📴 Offline Support

botswana-locations does not depend on an external location API.

The location dataset is bundled directly with the package.

The lookup process is:

Application
     ↓
botswana-locations
     ↓
Local Dataset
     ↓
District

There is no need to make an HTTP request simply to determine the district.

⚡ Performance

Location lookups are performed locally.

For example:

getDistrict("Gaborone");

does not require a network request.

This makes the package suitable for applications that perform frequent location lookups.

🔑 No API Key Required

You do not need an API key.

Install:

npm install botswana-locations

Use:

const { getDistrict } = require("botswana-locations");

getDistrict("Gaborone");

🗄️ No Database Required

The package does not require:

• PostgreSQL
• MySQL
• MongoDB
• SQLite
• Redis
• Firebase

The location data is included directly in the package.

🌐 No External API Required

The package does not require developers to configure:

API_URL
API_KEY
DATABASE_URL
AUTH_TOKEN

It can be installed and used immediately.

🇧🇼 Districts

The package uses the district/local administrative names used for its Botswana location mappings.

The district names include:

• Bobirwa
• Boteti
• Charleshill
• Chobe
• Francistown
• Gaborone
• Ghanzi
• Goodhope
• Hukuntsi
• Kanye
• Kgatleng
• Kweneng
• Letlhakeng
• Mabutsane
• Mahalapye
• Mogoditshane-Thamaga
• Moshupa
• North-East
• North-West
• Okavango
• Palapye
• Ramotswa
• Selebi-Phikwe
• Serowe
• Tlokweng
• Tonota
• Tsabong
• Tutume

🏙️ Locations

The dataset is intended to cover Botswana locations including:

• Cities
• Towns
• Villages
• Other locations contained in the source dataset

Examples include:

Gaborone
Francistown
Maun
Mahalapye
Palapye
Serowe
Molepolole
Kanye
Moshupa
Tsabong
Bobonong
Letlhakane
Kasane
Gumare
Shakawe
Mogoditshane
Thamaga
Tlokweng
Ramotswa

📚 Data Source

The location dataset is based on Statistics Botswana's Population and Housing Census 2022 publications covering Botswana's cities, towns, villages and associated localities.

Statistics Botswana is Botswana's official national statistical agency responsible for producing and disseminating official statistics.

The purpose of this package is to make relevant location information easier for software developers to consume programmatically.

For official statistical, administrative, legal, population, or government purposes, users should refer to the latest official information published by the relevant Botswana government authority.

⚠️ Data Accuracy

Administrative structures, location names, spellings, and district assignments can change over time.

The package is intended to provide a reusable developer dataset based on official source material.

For high-stakes or official purposes, always verify information against the latest authoritative government source.

If you find an incorrect or missing location, please report it so it can be reviewed.

🔄 Future Updates

Future releases may include updates based on new official information.

Potential improvements include:

• Additional locations
• Corrected location names
• Corrected district assignments
• Updated administrative information
• Duplicate removal
• Improved search functionality
• Additional utilities
• TypeScript support
• Improved automated testing

🧪 Testing

Run the package tests:

npm test

You can also run the test file directly:

node test/test.js

📦 Package Structure

botswana-locations/
│
├── src/
│   ├── index.js
│   └── locations.js
│
├── test/
│   └── test.js
│
├── README.md
├── package.json
└── LICENSE

src/index.js

Contains the package's public functions.

src/locations.js

Contains the Botswana location dataset.

test/test.js

Contains package tests.

README.md

Contains package documentation.

package.json

Contains NPM package metadata and configuration.

🤝 Contributing

Contributions are welcome.

You can contribute by:

• Adding missing locations
• Correcting location names
• Correcting district assignments
• Reporting duplicate locations
• Improving search functionality
• Improving tests
• Improving documentation
• Suggesting new features

When reporting a correction, please provide a reliable source supporting the proposed change.

🐛 Reporting Issues

When reporting a location or district issue, please provide:

1. Location name
2. Current district returned by the package
3. Expected district
4. Reliable source supporting the correction

Example:

Location:
Example Location

Current district:
District A

Expected district:
District B

Source:
Official source confirming the correct district.

👨🏽‍💻 Development

Clone the repository:

git clone <repository-url>

Enter the project directory:

cd botswana-locations

Install dependencies:

npm install

Run tests:

npm test

Check the package before publishing:

npm pack --dry-run

📦 NPM

Install the latest published version:

npm install botswana-locations

Check the installed version:

npm list botswana-locations

Check the package on NPM:

npm view botswana-locations

📜 License

This project is released under the MIT License.

You are free to use, modify, and distribute the software according to the terms of the MIT License.

See the LICENSE file for the complete license text.

👤 Author

Tlotlo Kgotlafela

Creator and maintainer of botswana-locations.

🇧🇼 Built for Botswana Developers

Botswana developers often need location data when building applications.

Instead of creating and maintaining a separate location list for every project, developers can install botswana-locations and use a simple API.

┌─────────────────────┐
│  Botswana Location  │
│      Gaborone       │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│      District       │
│      Gaborone       │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│   Your Application  │
└─────────────────────┘

Simple. Fast. Offline. Developer-friendly.

🇧🇼 Built for Botswana.