algeria-geo README

The project's README from github.com/test-bit-sys/algeria-geo. As one markdown file: README.md.

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

algeria-geo logo



🇩🇿 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.


CI PyPI npm License: MIT Python TypeScript Runtime Dependencies


Telegram Channel Telegram Discord

Table of Contents

Features

Administrative Coverage

Level Count Identifiers Available Names
Wilayas (ولاية) 69 01 – 69 (ONS 2-digit) Arabic, French, ASCII romanized
Dairas (دائرة) 538 0101 – 6912 (4-digit) Arabic, French, ASCII romanized
Communes (بلدية) 1,541 0101 – 6912 (ONS 4-digit) Arabic, French, ASCII romanized

[!NOTE] Names are provided in Arabic (name_ar) and French (name_fr). The name_en attribute contains an ASCII-safe representation derived from official romanization. Official 5-digit postal codes (post_code) and GPS coordinates (latitude, longitude) are verified and available across all 1,541 communes. Telephone area codes (phone_code) are provided for all 69 wilayas.

Installation

Node.js / TypeScript

# npm
npm install algeria-geo

# pnpm
pnpm add algeria-geo

# yarn
yarn add algeria-geo

# bun
bun add algeria-geo

Python

# pip
pip install algeria-geo

# uv
uv add algeria-geo

# poetry
poetry add algeria-geo

Quick Start

TypeScript / JavaScript

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: "الشلف" }, ...]

Python

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"}, ...]

API Reference

Unified Query Functions

Python API TypeScript API Description
get_wilaya(id, era=69) getWilaya(id, era = 69) Look up wilaya by code (16, "16") or name in Ar/Fr/En
get_wilayas(era=69) getWilayas(era = 69) List all wilayas active in the given boundary era
get_daira(code) getDaira(code) Look up a single daira by its 4-digit code
get_dairas(wilaya_code, era=69) getDairas(wilayaCode, era = 69) List all dairas belonging to a wilaya
get_all_dairas(era=69) getAllDairas(era = 69) List all dairas across Algeria for an era
get_commune(code) getCommune(code) Look up a single commune by its 4-digit ONS code
get_communes(wilaya_code, era=69) getCommunes(wilayaCode, era = 69) List all communes belonging to a wilaya
get_all_communes(era=69) getAllCommunes(era = 69) List all communes across Algeria for an era
get_communes_by_daira(daira_code) getCommunesByDaira(dairaCode) List all communes within a specific daira
get_wilaya_by_commune(code, era=69) getWilayaByCommune(code, era = 69) Reverse lookup: find the wilaya of a commune
get_wilaya_by_phone_code(phone) getWilayaByPhoneCode(phone) Look up wilaya by phone area code (e.g. "021")
search(query, lang, limit) search(query, langOrOptions, limit) Multi-lingual fuzzy search across all divisions
get_postal_code(name, wilaya) getPostalCode(name, wilaya) Look up postal code (when populated)
to_dropdown_options(lang, era) toDropdownOptions(lang, era) Prepare { value, label } options for HTML selects

Historical Eras (48, 58, 69)

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)

Data Distributions

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

File Format Description
dist/wilayas.min.json JSON Minified array of all 69 wilayas with daira/commune counts
dist/dairas.min.json JSON Minified array of all 538 dairas with historical wilaya codes
dist/communes.min.json JSON Minified array of all 1,541 communes with lineage
dist/tree.min.json JSON Nested tree: Wilayas ➔ Dairas ➔ Communes
dist/csv/*.csv CSV UTF-8 with BOM CSV exports for Excel and data pipelines
dist/algeria_geo.sql SQL Ready-to-run DDL and INSERT statements for PostgreSQL & SQLite
dist/algeria_geo.mysql.sql SQL Optimized SQL script for MySQL 8 and MariaDB (utf8mb4)

Data Sources & Attributions

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.

Building from Source

# 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

Contributing

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

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

Back to top ↑

algeria-geo (test-bit-sys/algeria-geo)

Searching Database…

135 ·GitHub
Algeria-geo

Algeria's 69 wilayas, 538 dairas and 1,541 communes with Arabic/French search and historical administrative boundaries. Python and TypeScript libraries.

Creator
test-bit-sys
Size
0.6 MB
Stars
135
Updated
CommitOct 31
Age
1d
Commits · 90 Days