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.
264 lines (241 loc) • 9.17 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;
postal_code: string;
latitude: number;
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";
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;
dairas_count: number;
communes_count: number;
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;
/** `null` on the 5 communes for which no citable postal 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;
}
/** 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[];
}
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 5 communes 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;
/** Commune (ONS) code. Currently null for every ATM (the source resolves
* ATMs to a commune name only); typed as `string | null` for the future. */
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;
}
}
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 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;