algeria-geo README

README проекта с github.com/test-bit-sys/algeria-geo. Одним файлом markdown: 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
get_map_svg(era=69, ...) getMapSvg(options?) Generate standalone SVG map of Algeria
get_wilaya_svg_path(code) getWilayaSvgPath(code) Return SVG path geometry for a wilaya (d attribute)
WILAYA_SVG_PATHS WILAYA_SVG_PATHS Dictionary/Record mapping wilaya code to SVG path d

Interactive SVG Map & GeoJSON

algeria-geo includes a precision vector map (Web Mercator projection) covering all 69 wilayas, with matching boundaries and semantic attributes (id="wilaya-XX", data-code="XX", data-name-ar, data-name-fr, data-phone-code, data-era, data-dairas, data-communes).

Pre-Built Vector Distributions

Located in dist/maps/:

TypeScript / JavaScript Usage

import { getMapSvg, getWilayaSvgPath, WILAYA_SVG_PATHS } from "algeria-geo";
// Subpath import also supported:
// import { getMapSvg } from "algeria-geo/map";

// 1. Generate full SVG string (supports era: 48, 58, 69)
const svg = getMapSvg({ era: 69 });

// 2. Or query path geometry for a wilaya
const algerPath = getWilayaSvgPath(16); // "M5752 253l6-1..."

React / Next.js Component Example

import { getWilayas, WILAYA_SVG_PATHS } from "algeria-geo";

export function AlgeriaMap({ onSelect }: { onSelect: (code: string) => void }) {
  const wilayas = getWilayas();

  return (
    <svg viewBox="0 0 10000 9999" width="100%" height="100%">
      {wilayas.map((w) => (
        <path
          key={w.code}
          id={`wilaya-${w.code}`}
          d={WILAYA_SVG_PATHS[w.code]}
          className="fill-slate-200 stroke-white stroke-[1.5] hover:fill-emerald-500 cursor-pointer transition-colors"
          onClick={() => onSelect(w.code)}
        >
          <title>{w.name_ar} - {w.name_fr}</title>
        </path>
      ))}
    </svg>
  );
}

Python Usage

import algeria_geo as geo

# 1. Generate standalone SVG map string
svg_map = geo.get_map_svg(era=69)

# 2. Extract path geometry for any wilaya
alger_d = geo.get_wilaya_svg_path(16)

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)

Star History

Star History Chart ## 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)
dist/maps/algeria-69.svg SVG Vector SVG map with all 69 wilayas and semantic data attributes
dist/maps/algeria-69.min.svg SVG Minified SVG map for fast frontend loading
dist/maps/algeria-69.geojson GeoJSON Polygons in Web Mercator / WGS84 for Leaflet, Mapbox, D3 & QGIS

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.
  4. Vector SVG & GeoJSON Boundaries:

    • Wilaya boundary geometries and vector coordinates are derived from OpenStreetMap administrative relations via the Algeria69WilayaMap project, licensed under the MIT License. Boundaries © OpenStreetMap contributors under ODbL 1.0.

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)

Ищем в базе…

Что это такое?Это библиотека географических и административных данных Алжира без внешних зависимостей. Она охватывает все 69 wilaya, 538 daira и 1 541 commune с названиями на арабском, французском и в романизированной записи, а также данные об исторических границах.
Это библиотека, которую я подключаю в проект, или просто набор сырых данных, с которым я работаю вручную?И то, и другое: в комплекте есть типизированные пакеты для TypeScript и Python с функциями поиска и выборки, а также готовые файлы JSON, CSV и SQL в папке dist, которые можно подключать напрямую, не используя код библиотеки.
Как мне добавить её в свой проект?Установите npm-пакет для TypeScript/JavaScript (работает в Node.js, Bun, Deno и сборщиках для браузера вроде Vite/Next.js) или pip-пакет для Python, затем вызывайте функции вроде getWilaya(), getCommunes() или search().
Нужно ли устанавливать что-то ещё, чтобы её использовать?Нет, у библиотеки нет зависимостей времени выполнения. Она написана на чистом коде на основе стандартной библиотеки и использует мгновенный поиск по словарям в памяти.
Все ли данные распространяются под той же лицензией, что и код?Нет. Код распространяется по лицензии MIT, но 323 из 1 541 координат коммун взяты из OpenStreetMap и распространяются по лицензии ODbL 1.0, которая не является CC0 или MIT.
Можно ли запрашивать старые административные границы, а не только текущие?Да. Если передать в функции поиска era=48, 58 или 69, они покажут состояние на 1984, 2019 или 2026 год, включая расширение до 69 wilaya, добавленное в 2026 году.
Как поиск работает с арабским и французским написанием одного и того же места?Функция search() приводит к единому виду арабские диакритические знаки, французские акценты, варианты написания букв и фонетическую транслитерацию, поэтому «Warqla», «Ouargla» и «ورقلة» определяются как одна и та же wilaya.
Какие форматы экспорта есть помимо API библиотеки?В папке dist есть минифицированный JSON для каждого уровня, вложенное дерево wilaya-daira-commune, CSV в кодировке UTF-8 и готовые к запуску SQL-дампы для PostgreSQL/SQLite и MySQL 8/MariaDB.
Откуда берутся исходные данные?Границы и названия переписаны из официального вестника Алжира. Почтовые индексы и большинство координат взяты из проекта GeoAlgeria, а координаты некоторых коммун взяты из OpenStreetMap.
Автор
test-bit-sys
Размер
0.9 MB
Звёзды
231
Обновлён
КоммитNov 03
Возраст
19 д
Коммиты · 90 дней