geoalgeria
Version:
69 wilayas, 551 dairas, 1541 communes of Algeria: bilingual names, postal codes, coordinates, plus 3908 post offices & 2026 ATMs. JSON, CSV, GeoJSON, SQL, TypeScript.
419 lines (391 loc) • 17.4 kB
TypeScript
// `geoalgeria` is a CommonJS module (`module.exports = {…}`), so its types use
// `export = algeriaGeodata`. An export assignment cannot coexist with other
// top-level `export` statements (TS2309), so every public type lives inside the
// `algeriaGeodata` namespace and merges with the value of the same name. Consumers
// reach them through the import: e.g. `import geo = require("geoalgeria")` then
// `geo.Wilaya`, or with esModuleInterop `import geo from "geoalgeria"`.
declare namespace algeriaGeodata {
export interface Wilaya {
code: number;
name_fr: string;
name_ar: string;
phone_code: string | null;
/** The postal code of the wilaya's capital commune
* (`capital_commune_code`), the same value that commune carries: a wilaya
* has no postal code of its own. Its two-digit prefix is the issuing
* office's wilaya, so it need not equal `code`; wilaya 59 reads `03001`,
* its chef-lieu Aflou's own code, and 11 of the 69 are in that case. */
postal_code: string;
/** The wilaya's point: the centre of its capital commune
* (`capital_commune_code`), the same value that commune carries and not a
* second reading of it. A wilaya has no point of its own. */
latitude: number;
/** See `latitude`: the capital commune's own longitude. */
longitude: number;
/** The year the wilaya became official, i.e. the year the law creating it
* took effect: `"original"` for the 48 of Law 84-09 (1984), `"2019"` for
* 49-58 (Law 19-12), `"2026"` for 59-69 (Law n° 26-06, *JO* n° 25 of
* 5 April 2026). Never the year a reform was announced: the 59-69 cohort
* was announced on 2025-11-16 and is still `"2026"`. */
created: "original" | "2019" | "2026";
/** The `code_commune` of the wilaya's Capital (chef-lieu), as fixed by the
* decrees that name the chefs-lieux of the wilayas: décret n° 84-79 of
* 3 April 1984 for 1-48, décret présidentiel n° 21-117 of 22 March 2021
* for 49-58, décret présidentiel n° 26-206 of 25 May 2026 for 59-69.
* Join it to `Commune.code_commune` for the capital's names, postal code
* and coordinates; the wilaya does not duplicate them. Never derived from
* `name_fr`: wilaya 16's capital is `1601` (Alger Centre), and 53, 54 and
* 57 spell their capital commune differently from the wilaya. A commune
* promoted into wilayas 59-69 keeps its 2021 mother-wilaya ONS prefix, so
* a capital code need not start with `code`: wilaya 59 reads `319`.
* Per-wilaya provenance: `data/wilaya-capitals.metadata.json`. */
capital_commune_code: number;
/** The id of this record's own OpenStreetMap administrative relation:
* `admin_level=8` for a commune, `admin_level=4` for a wilaya. Harvested from
* the Overpass capture the commune-centre audit fetched, `timestamp_osm_base`
* 2026-09-29T12:54:47Z, through the linkage that audit decided: the relation's
* `ref:ONS` (commune) or `ref` (wilaya) tag, then a pre-2019-reform ONS code
* scoped to the mother wilaya, then six reviewed per-relation pins. Never a
* name match. `null` on the 4 communes the capture has no relation for (630,
* 1634, 2110, 4703). No id repeats across records, and a wilaya's relation is
* its own, not its capital commune's. ODbL 1.0, (c) OpenStreetMap
* contributors; see the package NOTICE. */
osm_relation_id: number | null;
/** The Wikidata item (`Q` then digits) that the same relation is tagged with,
* read as published and never resolved from a name. `null` where the relation
* carries no `wikidata` tag, and always `null` where `osm_relation_id` is.
* Same terms as `osm_relation_id`. */
wikidata: string | null;
parent_wilaya?: string;
}
export interface WilayaDetailed {
code: number;
name_fr: string;
name_ar: string;
name_en: string;
/** The year the wilaya became official, as a number: `1984`, `2019` or
* `2026`. Same meaning as `Wilaya.created`, which spells the 1984 cohort
* `"original"`. */
created: number;
/** Same value and meaning as `Wilaya.capital_commune_code`. */
capital_commune_code: number;
dairas_count: number;
communes_count: number;
/** The id of this record's own OpenStreetMap administrative relation:
* `admin_level=8` for a commune, `admin_level=4` for a wilaya. Harvested from
* the Overpass capture the commune-centre audit fetched, `timestamp_osm_base`
* 2026-09-29T12:54:47Z, through the linkage that audit decided: the relation's
* `ref:ONS` (commune) or `ref` (wilaya) tag, then a pre-2019-reform ONS code
* scoped to the mother wilaya, then six reviewed per-relation pins. Never a
* name match. `null` on the 4 communes the capture has no relation for (630,
* 1634, 2110, 4703). No id repeats across records, and a wilaya's relation is
* its own, not its capital commune's. ODbL 1.0, (c) OpenStreetMap
* contributors; see the package NOTICE. */
osm_relation_id: number | null;
/** The Wikidata item (`Q` then digits) that the same relation is tagged with,
* read as published and never resolved from a name. `null` where the relation
* carries no `wikidata` tag, and always `null` where `osm_relation_id` is.
* Same terms as `osm_relation_id`. */
wikidata: string | null;
law?: string;
mother_wilaya_code?: number;
note?: string;
dairas_source?: string;
dairas?: DairaDetail[];
communes?: CommuneBasic[];
}
export interface DairaDetail {
name_ar: string;
name_fr: string;
communes?: CommuneBasic[];
}
export interface CommuneBasic {
name_ar: string;
name_fr: string;
}
export interface WilayaDataset {
metadata: DatasetMetadata;
wilayas: WilayaDetailed[];
}
export interface DatasetMetadata {
title: string;
total_wilayas: number;
total_communes: number;
total_dairas: number;
reforms: Reform[];
sources: string[];
last_updated: string;
notes: string[];
}
export interface Reform {
/** The year the reform took effect, matching the `created` of the wilayas
* it added. The 59-69 reform is `2026` (Law n° 26-06 of 4 April 2026),
* not 2025, the year it was announced. */
year: number;
law: string;
journal_officiel?: string;
description: string;
wilayas_added?: string;
}
export interface Commune {
name_fr: string;
name_ar: string;
wilaya_code: number;
daira: string | null;
/** The postal code of the commune's principal Algérie Poste office. Its first
* two digits are that office's wilaya at the time the code was issued, so like
* `code_commune` the prefix does not necessarily equal `wilaya_code`: Algérie
* Poste kept the old numbering through the 2026 reform, so Aflou is `03001` in
* wilaya 59. 108 of the 1,540 coded communes are in that case, all of them in
* wilayas 59-69. `null` on the 1 commune for which no citable code was found. */
postal_code: string | null;
latitude: number | null;
longitude: number | null;
/** Unique ONS 2021 WWCC commune code. Communes promoted into wilayas
* 59-69 retain their 2021 mother-wilaya prefix, so the prefix does not
* necessarily equal `wilaya_code`. */
code_commune: number;
/** The id of this record's own OpenStreetMap administrative relation:
* `admin_level=8` for a commune, `admin_level=4` for a wilaya. Harvested from
* the Overpass capture the commune-centre audit fetched, `timestamp_osm_base`
* 2026-09-29T12:54:47Z, through the linkage that audit decided: the relation's
* `ref:ONS` (commune) or `ref` (wilaya) tag, then a pre-2019-reform ONS code
* scoped to the mother wilaya, then six reviewed per-relation pins. Never a
* name match. `null` on the 4 communes the capture has no relation for (630,
* 1634, 2110, 4703). No id repeats across records, and a wilaya's relation is
* its own, not its capital commune's. ODbL 1.0, (c) OpenStreetMap
* contributors; see the package NOTICE. */
osm_relation_id: number | null;
/** The Wikidata item (`Q` then digits) that the same relation is tagged with,
* read as published and never resolved from a name. `null` where the relation
* carries no `wikidata` tag, and always `null` where `osm_relation_id` is.
* Same terms as `osm_relation_id`. */
wikidata: string | null;
}
/** One record's former names, kept so an older spelling still finds it. */
export interface NameHistoryEntry {
/** Present on a commune entry; absent on a wilaya entry. */
code_commune?: number;
/** Present on a wilaya entry; absent on a commune entry. */
code?: number;
wilaya_code?: number;
name_fr: string;
name_ar: string;
/** Earlier French spellings. Empty when only the Arabic name moved. */
former_names_fr: string[];
/** Earlier Arabic spellings. Empty when only the French name moved. */
former_names_ar: string[];
/** The official text that replaced each former name, one line per source. */
sources: string[];
}
export interface NameHistory {
metadata: {
title: string;
description: string;
updated: string;
sources: { key: string; name: string; url: string; evidence_type: string }[];
};
wilayas: NameHistoryEntry[];
communes: NameHistoryEntry[];
}
/** One official text the phone-code ledger relies on. */
export interface PhoneCodeSource {
key: string;
/** The document's own title. */
name: string;
url: string;
/** The document's own date, or null when it carries none, with `date_note`. */
document_date: string | null;
date_note?: string;
/** The date the document was read. */
retrieved: string;
evidence_type: "official";
}
/** Which declared document, where in it, and what it said there. */
export interface PhoneCodeCitation {
/** A key in `metadata.sources`. */
source_key: string;
/** Where in the document: an article, item, page, annex, table or section. */
article: string;
finding: string;
}
/** Why a wilaya of the cohort has no code: the authorities searched and the
* texts read, so the null is auditable rather than bare. */
export interface PhoneCodeReason {
statement: string;
searched_on: string;
searched: {
authority: string;
looked_for: string;
citations: PhoneCodeCitation[];
}[];
note?: string;
}
/** One wilaya's `phone_code` and the evidence for it: either a value with its
* citations, or null with `reason` naming an entry in `metadata.reasons`. */
export interface PhoneCodeProvenanceEntry {
code: number;
name_fr: string;
name_ar: string;
phone_code: string | null;
/** Present when `phone_code` is null. */
reason?: string;
/** Present when `phone_code` is a value. */
citations?: PhoneCodeCitation[];
/** Set when the code equals the one carried by the wilaya this was split from,
* which must be declared rather than left to look like a copy. */
same_as_mother_wilaya?: true;
mother_note?: string;
}
/** Why each wilaya of the 2026 cohort (codes 59 to 69) carries the `phone_code`
* it carries. A code enters it only with an official citation. */
export interface PhoneCodeProvenance {
metadata: {
title: string;
description: string;
scope: string;
rule: string;
updated: string;
sources: PhoneCodeSource[];
reasons: Record<string, PhoneCodeReason>;
note?: string;
};
wilayas: PhoneCodeProvenanceEntry[];
}
export interface Daira {
id: number;
wilaya_code: number;
name_fr: string;
commune_count: number;
}
export interface CommuneEcommerce {
id: number;
commune_name_fr: string;
commune_name_ar: string;
daira_name_fr: string | null;
wilaya_code: number;
wilaya_name_fr: string;
wilaya_name_ar: string;
/** `null` on the same 1 commune as `Commune.postal_code`. */
postal_code: string | null;
}
export interface WilayaWithCommunes extends Wilaya {
communes: Commune[];
}
export interface DeliveryZone {
wilaya_code: number;
wilaya_name_fr: string;
zone: string | null;
home_delivery: boolean | null;
desk_delivery: boolean | null;
estimated_days: number | null;
}
export interface DeliveryProvider {
provider: string;
provider_name: string;
last_updated: string | null;
zones: DeliveryZone[];
}
/** Coordinate provenance, coarse-grained. Detail lives in `geo_method`.
* `null` when the record has no coordinate at all. */
export type GeoPrecision = "exact" | "approximate" | null;
/** How the coordinate was obtained. `null` on an ungeocoded record: no
* method produced a point, so none can be named. */
export type GeoMethod = "baridimap" | null;
/** Office class/category as published by Algérie Poste. */
export type OfficeClass = "CE" | "GA" | "HC" | "R1" | "R2" | "R3" | "R4";
/** ATM operational status as published by Algérie Poste. `"1"` is an
* undocumented source value carried through verbatim rather than guessed at. */
export type AtmStatus = "OPEN" | "CLOSED (OFFLINE)" | "1";
/** A post office (bureau de poste). Mirrored from @geoalgeria/poste. */
export interface PostOffice {
/** Stable id, unique within this file. Opaque: do not parse. */
id: string;
name: string;
name_ar: string;
/** Wilaya code, zero-padded 2-digit string ("01".."69"). */
wilaya_code: string;
/** Commune (ONS) code as a 4-digit string. */
commune_code: string;
/** Algérie Poste's provider-native commune code when it differs from the
* normalized ONS join. Omitted when both values agree. */
source_commune_code?: string;
/** Commune name (French). */
commune: string;
/** Commune name in Arabic. */
commune_ar: string;
/** Latitude, or null when the office is not geocoded. */
lat: number | null;
/** Longitude, or null. Both coordinates are set, or both are null. */
lng: number | null;
/** `null` when `lat`/`lng` are null: a record with no point asserts no
* precision. */
geo_precision: GeoPrecision;
/** How `lat`/`lng` were obtained; null when there are none. */
geo_method: GeoMethod;
source: "baridimap";
class: OfficeClass;
postal_code: string;
/** Previous postal code, or null when the office was never renumbered. */
postal_code_old: string | null;
address: string;
}
/** An ATM (GAB). Mirrored from @geoalgeria/poste. */
export interface Atm {
/** Stable id, unique within this file. Opaque: do not parse. */
id: string;
name: string;
/** Wilaya code, zero-padded 2-digit string ("01".."69"). */
wilaya_code: string;
/** BaridiMap's own wilaya code, when the ATM's commune has since moved to
* one of the new wilayas and the published code is the current one. */
source_wilaya_code?: string;
/** Commune (ONS) code. Null unless the wilaya was reconciled or a reviewed
* correction filled it; BaridiMap itself resolves ATMs to a commune name. */
commune_code: string | null;
/** Commune name (French). */
commune: string;
/** Commune name in Arabic. */
commune_ar: string;
/** Latitude, or null when the ATM is not geocoded. */
lat: number | null;
/** Longitude, or null. Both coordinates are set, or both are null. */
lng: number | null;
/** `null` when `lat`/`lng` are null. */
geo_precision: GeoPrecision;
/** How `lat`/`lng` were obtained; null when there are none. */
geo_method: GeoMethod;
source: "baridimap";
status: AtmStatus;
postal_code: string;
/** Previous postal code, or null when never renumbered. */
postal_code_old: string | null;
/** Street address. Currently null for every ATM (the source omits it);
* typed as `string | null` so a future value is not a breaking change. */
address: string | null;
/** Present when a versioned evidence review corrected this record
* (quality/overrides/poste.json). */
review_status?: "corrected";
reviewed_at?: string;
reviewed_by?: string;
review_evidence?: string[];
}
}
declare const algeriaGeodata: {
readonly wilayas: algeriaGeodata.Wilaya[];
readonly communes: algeriaGeodata.Commune[];
readonly dairas: algeriaGeodata.Daira[];
readonly ecommerce: algeriaGeodata.CommuneEcommerce[];
readonly all: algeriaGeodata.WilayaWithCommunes[];
readonly nameHistory: algeriaGeodata.NameHistory;
readonly phoneCodeProvenance: algeriaGeodata.PhoneCodeProvenance;
readonly postOffices: algeriaGeodata.PostOffice[];
readonly atms: algeriaGeodata.Atm[];
getWilaya(code: number): algeriaGeodata.Wilaya | undefined;
getCommunesByWilaya(wilayaCode: number): algeriaGeodata.Commune[];
getDairasByWilaya(wilayaCode: number): algeriaGeodata.Daira[];
findCommune(name: string): algeriaGeodata.Commune[];
findByPostalCode(postalCode: string): algeriaGeodata.Commune[];
getPostOfficesByCommune(codeCommune: number | string): algeriaGeodata.PostOffice[];
};
export = algeriaGeodata;