@geoalgeria/poste 1.0.2 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (14) hide show
  1. package/LICENSE +1 -1
  2. package/README.ar.md +147 -0
  3. package/README.fr.md +148 -0
  4. package/README.md +37 -14
  5. package/data/atms.json +26602 -22550
  6. package/data/csv/atms.csv +2027 -0
  7. package/data/csv/postoffices.csv +3909 -0
  8. package/data/geojson/atms.geojson +54572 -0
  9. package/data/geojson/postoffices.geojson +108981 -0
  10. package/data/metadata.json +45 -7
  11. package/data/postoffices.json +57324 -53416
  12. package/dataset-metadata.json +68 -0
  13. package/package.json +12 -3
  14. package/types/index.d.ts +153 -0
package/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2025 Yasser's Studio (https://yasser.studio)
3
+ Copyright (c) 2025-2026 Yasser's Studio (https://yasser.studio)
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
package/README.ar.md ADDED
@@ -0,0 +1,147 @@
1
+ [English](README.md) | [Français](README.fr.md) | **العربية**
2
+
3
+ <div align="center">
4
+
5
+ # @geoalgeria/poste
6
+
7
+ **كل مكاتب بريد وأجهزة الصراف الآلي لبريد الجزائر — كبيانات قابلة للتثبيت.**
8
+
9
+ [![npm](https://img.shields.io/npm/v/@geoalgeria/poste)](https://www.npmjs.com/package/@geoalgeria/poste)
10
+ [![npm downloads](https://img.shields.io/npm/dm/@geoalgeria/poste)](https://www.npmjs.com/package/@geoalgeria/poste)
11
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
12
+
13
+ </div>
14
+
15
+ 3,908 مكتب بريد و2,026 جهاز صراف آلي عبر الجزائر — مع **أكواد بريدية حقيقية**، وأسماء ثنائية اللغة (فرنسية / عربية)، وإحداثيات GPS، وربط بالبلدية/الولاية. مصدرها بريد الجزائر، متوفرة بصيغ JSON وCSV وGeoJSON. جزء من [GeoAlgeria](https://github.com/yasserstudio/geoalgeria).
16
+
17
+ ```bash
18
+ npm install @geoalgeria/poste
19
+ ```
20
+
21
+ ```js
22
+ import poste from "@geoalgeria/poste";
23
+
24
+ const offices = poste.postOffices(); // 3,908
25
+ const atms = poste.atms(); // 2,026
26
+
27
+ // مكاتب البريد في بلدية (ربط عبر code_commune الخاص بـ GeoAlgeria)
28
+ const inAdrar = offices.filter((o) => o.commune_code === "0101");
29
+
30
+ // أقرب صراف آلي؟ كل سجل يحتوي على lat/lng للحسابات.
31
+ ```
32
+
33
+ ## ما يمكنك بناؤه
34
+
35
+ - **التحقق من الأكواد البريدية والبحث عنها** — كل مكتب يحمل `postal_code` الحقيقي الخاص به.
36
+ - **محددات مواقع المكاتب / أجهزة الصراف الآلي** — إحداثيات على (تقريبًا) كل سجل، جاهزة للترتيب حسب المسافة أو العرض على الخريطة.
37
+ - **التكنولوجيا المالية والخدمات اللوجستية** — مطابقة العناوين مع أقرب مكتب بريد أو صراف آلي.
38
+ - **خرائط** — طبقات نقاط GeoJSON جاهزة للاستخدام لشبكة البريد بالكامل.
39
+
40
+ ## المحتوى
41
+
42
+ | مجموعة البيانات | العدد | ملاحظات |
43
+ | --- | --- | --- |
44
+ | مكاتب البريد | **3,908** | كل مكتب بكوده البريدي الخاص (`postal_code`) |
45
+ | أجهزة الصراف الآلي | **2,026** | شبكة GAB لبريد الجزائر |
46
+
47
+ ## الصيغ
48
+
49
+ حزمة npm تحتوي على **JSON** (قابلة للاستيراد مباشرة):
50
+
51
+ ```js
52
+ import offices from "@geoalgeria/poste/data/postoffices.json" with { type: "json" };
53
+ // أو عبر CDN، بدون تثبيت:
54
+ // https://cdn.jsdelivr.net/npm/@geoalgeria/poste/data/postoffices.json
55
+ ```
56
+
57
+ المحمّلات وأشكال السجلات **مُنمّطة** بالكامل — تعريفات TypeScript مضمنة في الحزمة:
58
+
59
+ ```ts
60
+ import poste, { type PostOffice, type Atm } from "@geoalgeria/poste";
61
+ const offices: PostOffice[] = poste.postOffices();
62
+ ```
63
+
64
+ ملفات **CSV وGeoJSON** موجودة في المستودع تحت [`data/`](data) ومضمنة في كل
65
+ [إصدار على GitHub](https://github.com/yasserstudio/geoalgeria/releases):
66
+
67
+ ```
68
+ data/
69
+ postoffices.json # 3,908 مكتب (مصفوفة)
70
+ atms.json # 2,026 صراف آلي (مصفوفة)
71
+ metadata.json # الأعداد، المصادر، الترخيص، updated
72
+ csv/postoffices.csv # المستودع + حزمة الإصدار (غير مضمن في حزمة npm)
73
+ csv/atms.csv
74
+ geojson/postoffices.geojson # كيانات نقطية (سجلات ذات إحداثيات)
75
+ geojson/atms.geojson
76
+ ```
77
+
78
+ > GeoJSON يتضمن فقط السجلات التي تحتوي على إحداثيات — 16 مكتبًا و5 أجهزة صراف
79
+ > آلي لا تُبلّغ عن `lat`/`lng` وتُحذف منه (لكنها تبقى في JSON/CSV، مع
80
+ > `geo_precision`/`geo_method` بقيمة `null`). سجلات أجهزة الصراف الآلي تحمل
81
+ > `commune_code` بقيمة `null` (واجهة API المصدر لا تحلّ كود بلدية لأجهزة
82
+ > الصراف الآلي).
83
+
84
+ ## أشكال السجلات
85
+
86
+ **مكتب بريد**
87
+
88
+ ```json
89
+ {
90
+ "id": "1",
91
+ "name": "ADRAR RP",
92
+ "name_ar": "أدرار م ر",
93
+ "wilaya_code": "01",
94
+ "commune_code": "0101",
95
+ "commune": "ADRAR",
96
+ "commune_ar": "أدرار",
97
+ "lat": 27.8708439,
98
+ "lng": -0.2871417,
99
+ "geo_precision": "exact",
100
+ "geo_method": "baridimap",
101
+ "source": "baridimap",
102
+ "class": "CE",
103
+ "postal_code": "01000",
104
+ "postal_code_old": null,
105
+ "address": "ADRAR CENTRE RUE DES MARYTIM"
106
+ }
107
+ ```
108
+
109
+ `class` هو تصنيف المكتب (`CE`، `R1`–`R4`، `HC`، `GA`). `commune_code` هو
110
+ كود البلدية المكون من 4 أرقام الخاص ببريد الجزائر، والذي يرتبط بـ `code_commune`
111
+ الخاص بـ GeoAlgeria. `geo_precision` تكون `"exact"` (أو `null` إلى جانب
112
+ `lat`/`lng` عندما لا يكون المكتب مُرمّزًا جغرافيًا)؛ `geo_method` يحدد كيفية
113
+ الحصول على الإحداثية.
114
+
115
+ **جهاز صراف آلي** — نفس الشكل، مُعرّف بـ `id`/`name`/`wilaya_code`/`postal_code`
116
+ مع `lat`/`lng`، بالإضافة إلى حقل `status` (‏`"OPEN"`، ‏`"CLOSED (OFFLINE)"`، أو
117
+ قيمة المصدر غير الموثقة `"1"`)؛ `commune_code` و`address` تكون دائمًا `null`
118
+ (المصدر لا يحلّهما لأجهزة الصراف الآلي).
119
+
120
+ ## هل تحتاج التقسيمات الإدارية أيضًا؟
121
+
122
+ إذا كنت تحتاج أيضًا الولايات والدوائر والبلديات، استخدم الحزمة الرئيسية
123
+ **[`geoalgeria`](https://www.npmjs.com/package/geoalgeria)** — فهي تدمج
124
+ بيانات البريد هذه وتوفر `postOffices` / `atms` إلى جانب مجموعة بيانات
125
+ التقسيمات الكاملة. استخدم `@geoalgeria/poste` عندما تحتاج *فقط* البيانات
126
+ البريدية/المصرفية.
127
+
128
+ ## المصدر
129
+
130
+ البيانات مصدرها **بريد الجزائر** عبر واجهة API العامة لـ BaridiMap
131
+ (<https://baridimap.poste.dz>). نفّذ `npm run fetch` لإعادة توليد جميع
132
+ المخرجات من واجهة API المباشرة؛ نفس العملية تعكس البيانات في حزمة `geoalgeria`
133
+ حتى لا يحدث اختلاف بينهما أبدًا (هذه الحزمة هي المصدر المرجعي). أعد التشغيل
134
+ دوريًا — BaridiMap لا يزال يصنف المكاتب وفق نظام 58 ولاية، لذا الولايات
135
+ الجديدة 59–69 تظهر حاليًا تحت ولاياتها الأم.
136
+
137
+ ## الترخيص والإسناد
138
+
139
+ الشفرة البرمجية مرخصة بموجب [MIT](LICENSE). البيانات الأساسية © **بريد الجزائر**،
140
+ أُعيد توزيعها كمرجع ولتشغيل [GeoAlgeria](https://geoalgeria.com). تحقق من
141
+ بريد الجزائر للحصول على معلومات رسمية ومحدّثة.
142
+
143
+ [توثيق API ومرجع الحقول →](https://geoalgeria.com/data/docs/poste) · [تصفح جميع الحزم →](https://geoalgeria.com/data)
144
+
145
+ ---
146
+
147
+ من تطوير [Yasser's Studio](https://yasser.studio) · [LinkedIn](https://www.linkedin.com/in/yasserberrehail/) · [X](https://x.com/yassersstudio) · [hello@yasser.studio](mailto:hello@yasser.studio)
package/README.fr.md ADDED
@@ -0,0 +1,148 @@
1
+ [English](README.md) | **Français** | [العربية](README.ar.md)
2
+
3
+ <div align="center">
4
+
5
+ # @geoalgeria/poste
6
+
7
+ **Chaque bureau et distributeur d'Algérie Poste — sous forme de données installables.**
8
+
9
+ [![npm](https://img.shields.io/npm/v/@geoalgeria/poste)](https://www.npmjs.com/package/@geoalgeria/poste)
10
+ [![npm downloads](https://img.shields.io/npm/dm/@geoalgeria/poste)](https://www.npmjs.com/package/@geoalgeria/poste)
11
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
12
+
13
+ </div>
14
+
15
+ 3 908 bureaux de poste et 2 026 distributeurs automatiques (DAB) à travers l'Algérie — avec de **vrais codes postaux**, des noms bilingues (français / arabe), des coordonnées GPS et un rattachement commune/wilaya. Données issues d'Algérie Poste, distribuées en JSON, CSV et GeoJSON. Fait partie de [GeoAlgeria](https://github.com/yasserstudio/geoalgeria).
16
+
17
+ ```bash
18
+ npm install @geoalgeria/poste
19
+ ```
20
+
21
+ ```js
22
+ import poste from "@geoalgeria/poste";
23
+
24
+ const offices = poste.postOffices(); // 3 908
25
+ const atms = poste.atms(); // 2 026
26
+
27
+ // Bureaux de poste dans une commune (jointure sur code_commune de GeoAlgeria)
28
+ const inAdrar = offices.filter((o) => o.commune_code === "0101");
29
+
30
+ // Le DAB le plus proche ? Chaque enregistrement a lat/lng pour vos calculs.
31
+ ```
32
+
33
+ ## Ce que vous pouvez construire
34
+
35
+ - **Validation et recherche de codes postaux** — chaque bureau porte son vrai `postal_code`.
36
+ - **Localisateurs de bureaux / DAB** — coordonnées sur (presque) chaque enregistrement, prêtes pour le tri par distance ou l'affichage sur carte.
37
+ - **Fintech et logistique** — faites correspondre les adresses au bureau de poste ou au GAB le plus proche.
38
+ - **Cartes** — couches de points GeoJSON prêtes à l'emploi pour l'ensemble du réseau postal.
39
+
40
+ ## Contenu
41
+
42
+ | Jeu de données | Nombre | Notes |
43
+ | --- | --- | --- |
44
+ | Bureaux de poste | **3 908** | chacun avec son propre code postal (`postal_code`) |
45
+ | DAB | **2 026** | Réseau GAB d'Algérie Poste |
46
+
47
+ ## Formats
48
+
49
+ Le paquet npm contient le **JSON** (importable directement) :
50
+
51
+ ```js
52
+ import offices from "@geoalgeria/poste/data/postoffices.json" with { type: "json" };
53
+ // ou via CDN, sans installation :
54
+ // https://cdn.jsdelivr.net/npm/@geoalgeria/poste/data/postoffices.json
55
+ ```
56
+
57
+ Les chargeurs et les structures d'enregistrements sont entièrement **typés** — les définitions TypeScript sont incluses dans le paquet :
58
+
59
+ ```ts
60
+ import poste, { type PostOffice, type Atm } from "@geoalgeria/poste";
61
+ const offices: PostOffice[] = poste.postOffices();
62
+ ```
63
+
64
+ Les fichiers **CSV et GeoJSON** sont dans le dépôt sous [`data/`](data) et inclus dans chaque
65
+ [Release GitHub](https://github.com/yasserstudio/geoalgeria/releases) :
66
+
67
+ ```
68
+ data/
69
+ postoffices.json # 3 908 bureaux (tableau)
70
+ atms.json # 2 026 DAB (tableau)
71
+ metadata.json # comptages, sources, licence, updated
72
+ csv/postoffices.csv # dépôt + bundle Release (pas dans le tarball npm)
73
+ csv/atms.csv
74
+ geojson/postoffices.geojson # Entités Point (enregistrements avec coordonnées)
75
+ geojson/atms.geojson
76
+ ```
77
+
78
+ > Le GeoJSON n'inclut que les enregistrements ayant des coordonnées — 16
79
+ > bureaux et 5 DAB ne rapportent pas de `lat`/`lng` et en sont absents (mais
80
+ > restent dans JSON/CSV, avec `geo_precision`/`geo_method` à `null`). Les
81
+ > enregistrements de DAB portent `commune_code` à `null` (l'API source ne
82
+ > résout pas de code commune pour les DAB).
83
+
84
+ ## Structure des enregistrements
85
+
86
+ **Bureau de poste**
87
+
88
+ ```json
89
+ {
90
+ "id": "1",
91
+ "name": "ADRAR RP",
92
+ "name_ar": "أدرار م ر",
93
+ "wilaya_code": "01",
94
+ "commune_code": "0101",
95
+ "commune": "ADRAR",
96
+ "commune_ar": "أدرار",
97
+ "lat": 27.8708439,
98
+ "lng": -0.2871417,
99
+ "geo_precision": "exact",
100
+ "geo_method": "baridimap",
101
+ "source": "baridimap",
102
+ "class": "CE",
103
+ "postal_code": "01000",
104
+ "postal_code_old": null,
105
+ "address": "ADRAR CENTRE RUE DES MARYTIM"
106
+ }
107
+ ```
108
+
109
+ `class` est la catégorie du bureau (`CE`, `R1`–`R4`, `HC`, `GA`). `commune_code`
110
+ est le code commune à 4 chiffres d'Algérie Poste, qui se joint au `code_commune`
111
+ de GeoAlgeria. `geo_precision` vaut `"exact"` (ou `null` avec `lat`/`lng` quand
112
+ le bureau n'est pas géocodé) ; `geo_method` indique comment le point a été obtenu.
113
+
114
+ **DAB** — même structure, identifié par `id`/`name`/`wilaya_code`/`postal_code`
115
+ avec `lat`/`lng`, plus un champ `status` (`"OPEN"`, `"CLOSED (OFFLINE)"`, ou la
116
+ valeur source non documentée `"1"`) ; `commune_code` et `address` sont toujours
117
+ `null` (la source ne les résout pas pour les DAB).
118
+
119
+ ## Besoin des divisions administratives ?
120
+
121
+ Si vous avez aussi besoin des wilayas, dairas et communes, utilisez le paquet
122
+ principal **[`geoalgeria`](https://www.npmjs.com/package/geoalgeria)** — il
123
+ intègre ces données postales et expose `postOffices` / `atms` aux côtés du jeu
124
+ de données complet des divisions. Utilisez `@geoalgeria/poste` quand vous
125
+ n'avez besoin *que* des données postales/bancaires.
126
+
127
+ ## Source
128
+
129
+ Les données proviennent d'**Algérie Poste** via l'API publique BaridiMap
130
+ (<https://baridimap.poste.dz>). Exécutez `npm run fetch` pour régénérer toutes
131
+ les sorties à partir de l'API en direct ; la même exécution reflète les données
132
+ dans le paquet `geoalgeria` pour que les deux ne divergent jamais (ce paquet est
133
+ la source canonique). Relancez périodiquement — BaridiMap classe toujours les
134
+ bureaux selon le schéma à 58 wilayas, donc les nouvelles wilayas 59–69
135
+ apparaissent actuellement sous leur wilaya mère.
136
+
137
+ ## Licence et attribution
138
+
139
+ Le code est sous [MIT](LICENSE). Les données sous-jacentes sont © **Algérie Poste**,
140
+ redistribuées à titre de référence et pour alimenter
141
+ [GeoAlgeria](https://geoalgeria.com). Vérifiez auprès d'Algérie Poste pour des
142
+ informations officielles et en temps réel.
143
+
144
+ [Documentation API et référence des champs →](https://geoalgeria.com/data/docs/poste) · [Parcourir tous les paquets →](https://geoalgeria.com/data)
145
+
146
+ ---
147
+
148
+ Réalisé par [Yasser's Studio](https://yasser.studio) · [LinkedIn](https://www.linkedin.com/in/yasserberrehail/) · [X](https://x.com/yassersstudio) · [hello@yasser.studio](mailto:hello@yasser.studio)
package/README.md CHANGED
@@ -1,3 +1,5 @@
1
+ **English** | [Français](README.fr.md) | [العربية](README.ar.md)
2
+
1
3
  <div align="center">
2
4
 
3
5
  # @geoalgeria/poste
@@ -52,6 +54,13 @@ import offices from "@geoalgeria/poste/data/postoffices.json" with { type: "json
52
54
  // https://cdn.jsdelivr.net/npm/@geoalgeria/poste/data/postoffices.json
53
55
  ```
54
56
 
57
+ The loaders and record shapes are fully **typed** — TypeScript definitions ship in the package:
58
+
59
+ ```ts
60
+ import poste, { type PostOffice, type Atm } from "@geoalgeria/poste";
61
+ const offices: PostOffice[] = poste.postOffices();
62
+ ```
63
+
55
64
  **CSV and GeoJSON** are in the repo under [`data/`](data) and bundled in every
56
65
  [GitHub Release](https://github.com/yasserstudio/geoalgeria/releases):
57
66
 
@@ -59,16 +68,17 @@ import offices from "@geoalgeria/poste/data/postoffices.json" with { type: "json
59
68
  data/
60
69
  postoffices.json # 3,908 offices (array)
61
70
  atms.json # 2,026 ATMs (array)
62
- metadata.json # source, counts, generated_at
71
+ metadata.json # counts, sources, license, updated
63
72
  csv/postoffices.csv # repo + Release bundle (not in npm tarball)
64
73
  csv/atms.csv
65
74
  geojson/postoffices.geojson # Point features (records with coordinates)
66
75
  geojson/atms.geojson
67
76
  ```
68
77
 
69
- > GeoJSON includes only records that have coordinates — a handful of offices and
70
- > ATMs report no `lat`/`lng` and are omitted there (but remain in JSON/CSV). ATM
71
- > records have no `commune_code` (the source API doesn't provide one).
78
+ > GeoJSON includes only records that have coordinates — 16 offices and 5 ATMs
79
+ > report no `lat`/`lng` and are omitted there (but remain in JSON/CSV, with
80
+ > `geo_precision`/`geo_method` both `null`). ATM records carry `commune_code`
81
+ > as `null` (the source API doesn't resolve ATMs to a commune code).
72
82
 
73
83
  ## Record shapes
74
84
 
@@ -76,27 +86,34 @@ data/
76
86
 
77
87
  ```json
78
88
  {
79
- "id": 1,
89
+ "id": "1",
80
90
  "name": "ADRAR RP",
81
91
  "name_ar": "أدرار م ر",
82
- "class": "CE",
83
- "postal_code": "01000",
84
- "address": "ADRAR CENTRE RUE DES MARYTIM",
92
+ "wilaya_code": "01",
85
93
  "commune_code": "0101",
86
- "commune_fr": "ADRAR",
94
+ "commune": "ADRAR",
87
95
  "commune_ar": "أدرار",
88
- "wilaya_code": "01",
89
- "wilaya_fr": "ADRAR",
90
- "wilaya_ar": "أدرار",
91
96
  "lat": 27.8708439,
92
- "lng": -0.2871417
97
+ "lng": -0.2871417,
98
+ "geo_precision": "exact",
99
+ "geo_method": "baridimap",
100
+ "source": "baridimap",
101
+ "class": "CE",
102
+ "postal_code": "01000",
103
+ "postal_code_old": null,
104
+ "address": "ADRAR CENTRE RUE DES MARYTIM"
93
105
  }
94
106
  ```
95
107
 
96
108
  `class` is the office category (`CE`, `R1`–`R4`, `HC`, `GA`). `commune_code` is
97
109
  Algérie Poste's 4-digit commune code, which joins to GeoAlgeria's `code_commune`.
110
+ `geo_precision` is `"exact"` (or `null` alongside `lat`/`lng` when the office
111
+ isn't geocoded); `geo_method` names how the point was obtained.
98
112
 
99
- **ATM** — same shape, keyed by `id`/`name`/`postal_code`/`wilaya_*` with `lat`/`lng`; no `commune_code`.
113
+ **ATM** — same shape, keyed by `id`/`name`/`wilaya_code`/`postal_code` with
114
+ `lat`/`lng`, plus a `status` field (`"OPEN"`, `"CLOSED (OFFLINE)"`, or the
115
+ undocumented source value `"1"`); `commune_code` and `address` are always
116
+ `null` (the source doesn't resolve them for ATMs).
100
117
 
101
118
  ## Need the administrative divisions too?
102
119
 
@@ -119,3 +136,9 @@ currently appear under their mother wilaya.
119
136
  Code is [MIT](LICENSE). The underlying data is © **Algérie Poste**, redistributed
120
137
  for reference and to power [GeoAlgeria](https://geoalgeria.com). Verify against
121
138
  Algérie Poste for authoritative, real-time information.
139
+
140
+ [API docs & field reference →](https://geoalgeria.com/data/docs/poste) · [Browse all packages →](https://geoalgeria.com/data)
141
+
142
+ ---
143
+
144
+ Made by [Yasser's Studio](https://yasser.studio) · [LinkedIn](https://www.linkedin.com/in/yasserberrehail/) · [X](https://x.com/yassersstudio) · [hello@yasser.studio](mailto:hello@yasser.studio)