项目的 README,来自 github.com/test-bit-sys/algeria-geo。合并为一个 markdown 文件:README.md。
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.
Warqla = Ouargla = ورقلة).data-code, data-name-ar, data-name-fr) and GeoJSON polygons for Leaflet/Mapbox/D3.| 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). Thename_enattribute 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.
# 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"}, ...]
| 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 |
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).
Located in dist/maps/:
dist/maps/algeria-69.svg: Clean, responsive SVG with default styles and hover effects.dist/maps/algeria-69.min.svg: Minified SVG for production web applications and delivery dashboards.dist/maps/algeria-69.geojson: GeoJSON polygons compatible with Leaflet, Mapbox, D3, and QGIS.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..."
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>
);
}
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)
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:
| 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 |
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:
Administrative Boundaries & Nomenclature:
daira_code: null in official statistical records.Postal Codes & Verified Coordinates:
OpenStreetMap Data (ODbL 1.0):
Vector SVG & GeoJSON Boundaries:
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.
See the NOTICE file for complete third-party licenses and attribution terms.