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 包,内含查找和搜索函数;同时在 dist 文件夹中提供预构建的 JSON、CSV 和 SQL 文件,无需使用库代码即可直接导入。
怎样把它添加到我的项目中?安装 TypeScript/JavaScript 的 npm 包(适用于 Node.js、Bun、Deno,以及 Vite/Next.js 等浏览器打包工具),或安装 Python 的 pip 包,然后调用 getWilaya()、getCommunes() 或 search() 等函数。
使用它还需要安装其他东西吗?不需要。它没有任何运行时依赖,仅使用纯标准库代码,并通过内存中的字典实现即时查找。
所有数据是否都采用与代码相同的许可证发布?不是。代码采用 MIT 许可证,但 1,541 个市镇坐标中有 323 个来自 OpenStreetMap,采用 ODbL 1.0 许可证,既不是 CC0,也不是 MIT。
我能查询旧的行政区划边界,而不仅仅是当前的吗?可以。向查询函数传入 era=48、58 或 69,即可分别获取 1984 年、2019 年或 2026 年省级重组后的数据,其中包括 2026 年新增的 59 至 69 省扩展。
搜索如何处理同一地名的阿拉伯文和法文拼写?search() 函数会统一处理阿拉伯文变音符号、法文重音符号、字母变体和音译差异,因此 'Warqla'、'Ouargla' 和 'ورقلة' 都会匹配到同一个省。
除了库的 API,还有哪些导出格式?dist 文件夹包含每个层级的压缩版 JSON、省-县-市镇嵌套树状结构、UTF-8 编码的 CSV,以及可直接运行的 PostgreSQL/SQLite 和 MySQL 8/MariaDB 的 SQL 转储文件。
底层数据来自哪里?边界和名称转录自阿尔及利亚官方公报;邮政编码和大部分坐标来自 GeoAlgeria 项目,部分市镇坐标来自 OpenStreetMap。
大小
0.9 MB
星标
231
更新
提交Nov 03
时长
19天
提交 · 90 天