English  |  العربية  |  Français

🇩🇿 algeria-geo

The definitive, zero-runtime-dependency geospatial & administrative dataset for Algeria.
69 Wilayas, 538 Dairas, and 1,541 Communes with historical boundary views (48, 58, 69) and cross-script search.

• Features
• Administrative Coverage
• Installation
• Quick Start
  • TypeScript / JavaScript
  • Python
• API Reference
• Historical Eras (48, 58, 69)
• Data Distributions (JSON, CSV, SQL)
• Data Source & Provenance
• Building from Source
• Contributing
• License

• 🇩🇿 Complete Official Coverage: All 69 wilayas (including the 2026 administrative reform: Wilayas 59–69), 538 dairas, and 1,541 communes.
• ⏳ Historical Boundary Eras: Query administrative boundaries across 48 (1984), 58 (2019), and 69 (2026) wilaya systems.
• 🔍 Cross-Script Fuzzy Search: Intelligent search folding Arabic diacritics/tashkeel, French accents, letter variants, and phonetic transliterations (Warqla = Ouargla = ورقلة).
• ⚡ Zero Runtime Dependencies: Pure standard library implementation with instant in-memory $O(1)$ dictionary lookups.
• 📦 Dual Ecosystem Parity: Identical feature set, function names, and performance in both TypeScript (ESM + CommonJS) and Python (Typed).
• 🗄️ Multi-Format Exports: Ready-to-import SQL dumps (PostgreSQL, SQLite, MySQL / MariaDB), minified JSON, hierarchical tree, and UTF-8 CSVs.

# npm
npm install algeria-geo

# pnpm
pnpm add algeria-geo

# yarn
yarn add algeria-geo

# bun
bun add algeria-geo

# pip
pip install algeria-geo

# uv
uv add algeria-geo

# poetry
poetry add algeria-geo

Works seamlessly across Node.js, Bun, Deno, Next.js, Nuxt, Vite, and browser bundlers:

import {
  getWilaya,
  getDaira,
  getCommune,
  getCommunes,
  getWilayaByPhoneCode,
  getWilayaByCommune,
  search,
  toDropdownOptions,
} from "algeria-geo";

// 1. Direct lookups by code or multilingual name
const alger = getWilaya(16); // or getWilaya("16") or getWilaya("الجزائر")
console.log(alger?.name_fr); // "Alger"
console.log(alger?.communes_count); // 57

// 2. Daira and Commune lookups
const daira = getDaira("0301");
console.log(daira?.name_ar); // "الأغواط"

const commune = getCommune("0319");
console.log(commune?.name_ar); // "أفلو"
console.log(commune?.wilaya_code); // "59" (New wilaya in 2026 reform)

// 3. Reverse lookup (Which wilaya does a commune belong to?)
console.log(getWilayaByCommune("0319", 69)?.name_fr); // "Aflou" (Era 69)
console.log(getWilayaByCommune("0319", 58)?.name_fr); // "Laghouat" (Era 58)

// 4. Telephone area code lookup
console.log(getWilayaByPhoneCode("021")?.name_fr); // "Alger"

// 5. Cross-script fuzzy search
const results = search("Warqla", { limit: 5 });
console.log(results.wilayas[0]?.item.name_ar); // "ورقلة"
console.log(results.wilayas[0]?.score); // 0.85

// 6. UI select dropdown options
const options = toDropdownOptions("ar");
// [{ value: "01", label: "أدرار" }, { value: "02", label: "الشلف" }, ...]

import algeria_geo as geo

# 1. Direct lookups by code or multilingual name
alger = geo.get_wilaya(16)  # accepts int or str: "16", "Alger", "الجزائر"
print(alger.name_ar)         # "الجزائر"
print(alger.communes_count)  # 57

# 2. Daira and Commune lookups
daira = geo.get_daira("0301")
print(daira.name_ar)  # "الأغواط"

commune = geo.get_commune("0319")
print(commune.name_ar)       # "أفلو"
print(commune.wilaya_code)   # "59" (Aflou in era 69)

# 3. Reverse commune lookup across historical eras
print(geo.get_wilaya_by_commune("0319", era=69).name_fr)  # "Aflou"
print(geo.get_wilaya_by_commune("0319", era=58).name_fr)  # "Laghouat"

# 4. Telephone area code lookup
print(geo.get_wilaya_by_phone_code("021").name_fr)  # "Alger"

# 5. Cross-script fuzzy search
res = geo.search("Ouargla")
print(res.wilayas[0].item.name_ar)  # "ورقلة"
print(res.best.score)               # 1.0

# 6. JSON serialization for FastAPI / Django / Flask
import json
print(json.dumps(commune.to_dict(), ensure_ascii=False))

# 7. Dropdown options for web forms
dropdown = geo.to_dropdown_options(lang="fr")
# [{"value": "01", "label": "Adrar"}, {"value": "02", "label": "Chlef"}, ...]

Algeria's administrative map has evolved through three major legislative reorganizations:

flowchart LR
    A["1984 System (Law 84-09)<br/><b>48 Wilayas</b>"] --> B["2019 System (Law 19-12)<br/><b>58 Wilayas</b>"]
    B --> C["2026 System<br/><b>69 Wilayas</b>"]

algeria-geo preserves complete historical lineage. By passing era=48 or era=58, queries reflect past administrative boundaries:

# In the 58-wilaya system, Aflou belonged to Laghouat (03)
communes_58 = geo.get_communes("03", era=58)

# In the current 69-wilaya system, Aflou is its own wilaya (59)
communes_69 = geo.get_communes("59", era=69)

Pre-built distribution files are located in the dist/ folder:

The administrative boundaries, nomenclature, postal codes, and coordinates in algeria-geo are compiled and verified from official legislative records and trusted open-source geographic datasets:

1. Administrative Boundaries & Nomenclature:

   • Transcribed directly from executive decrees and legislative texts published in Algeria's official gazette (Journal officiel de la République algérienne démocratique et populaire), referenced from djazairdev/wilayas.
   • 57 communes belonging to Wilaya 16 (Alger) operate under a special administrative status (circonscriptions administratives) and retain daira_code: null in official statistical records.

2. Postal Codes & Verified Coordinates:

   • Official 5-digit postal codes and municipality center coordinates are derived from the GeoAlgeria project by Yasser Studio, licensed under the MIT License. Copyright (c) 2026 Yasser Studio.

3. OpenStreetMap Data (ODbL 1.0):

   • 323 of the 1,541 commune coordinates are derived from OpenStreetMap administrative relations via GeoAlgeria and are made available under the Open Database License (ODbL) 1.0: © OpenStreetMap contributors.

See NOTICE and LICENSE for full details.

# 1. Validate canonical data integrity
python scripts/build.py --check

# 2. Build distributions (JSON, CSV, SQL, package files)
python scripts/build.py

# 3. Re-import latest upstream data
python scripts/import_source.py
python scripts/build.py

Contributions are welcome! Please check CONTRIBUTING.md for data citation guidelines, local testing instructions, and pull request requirements.

• Code & Libraries: Licensed under the MIT License. Copyright (c) 2026 test-bit-sys.
• Data Compilation & Postal Codes: Derived from GeoAlgeria under the MIT License. Copyright (c) 2025-2026 Yasser's studio (https://yasser.studio).
• OpenStreetMap Coordinates: 323 commune center coordinates are derived from OpenStreetMap relations via GeoAlgeria and are made available under the Open Database License (ODbL) 1.0 (© OpenStreetMap contributors), and are not released under CC0.
• Administrative Nomenclature: Official administrative divisions and names are transcribed from the Official Gazette of the Republic of Algeria.

See the NOTICE file for complete third-party licenses and attribution terms.

Back to top ↑