@geoalgeria/poste 1.0.0 → 1.0.2

package/README.md

@@ -1,47 +1,74 @@
+<div align="center">
+
 # @geoalgeria/poste
 
-Algeria **post offices** and **ATMs** with real postal codes, bilingual
-(French / Arabic) names, geographic coordinates, and commune/wilaya linkage.
+**Every Algérie Poste office and ATM — as data you can install.**
+
+[![npm](https://img.shields.io/npm/v/@geoalgeria/poste)](https://www.npmjs.com/package/@geoalgeria/poste)
+[![npm downloads](https://img.shields.io/npm/dm/@geoalgeria/poste)](https://www.npmjs.com/package/@geoalgeria/poste)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+</div>
+
+3,908 post offices and 2,026 ATMs across Algeria — with **real postal codes**, bilingual (French / Arabic) names, GPS coordinates, and commune/wilaya linkage. Sourced from Algérie Poste, shipped as JSON, CSV, and GeoJSON. Part of [GeoAlgeria](https://github.com/yasserstudio/geoalgeria).
+
+```bash
+npm install @geoalgeria/poste
+```
+
+```js
+import poste from "@geoalgeria/poste";
+
+const offices = poste.postOffices();   // 3,908
+const atms = poste.atms();             // 2,026
+
+// Post offices in a commune (joins GeoAlgeria's code_commune)
+const inAdrar = offices.filter((o) => o.commune_code === "0101");
+
+// Nearest ATM? Everything has lat/lng to compute against.
+```
+
+## What you can build
+
+- **Postal-code validation & lookup** — every office carries its real `postal_code`.
+- **Branch / ATM locators** — coordinates on (almost) every record, ready for distance sorting or a map.
+- **Fintech & logistics** — match addresses to the nearest post office or GAB.
+- **Maps** — drop-in GeoJSON point layers for the whole postal network.
+
+## What's inside
 
 | Dataset | Count | Notes |
 | --- | --- | --- |
-| Post offices | **3,908** | each with its own postal code (`cp`) |
+| Post offices | **3,908** | each with its own postal code (`postal_code`) |
 | ATMs | **2,026** | Algérie Poste GAB network |
-| Distinct postal codes | **3,908** | one per office |
 
-## Source
+## Formats
 
-Data is sourced from **Algérie Poste** via the public BaridiMap API
-(<https://baridimap.poste.dz>):
+The npm package ships the **JSON** (importable directly):
 
-- `GET https://baridimap-api.poste.dz/api/postoffices`
-- `GET https://baridimap-api.poste.dz/api/atms`
-
-Run `npm run fetch` (or `node scripts/fetch.mjs`) to regenerate every output
-from the live API. The same run also mirrors the data into the sibling
-`geoalgeria` package at `packages/dataset/data/poste/`, so the two never drift —
-this package is the canonical source. Re-fetch periodically — Algérie Poste
-updates offices and, eventually, the post-2025 wilaya reorganization (BaridiMap
-currently still files offices under the 58-wilaya scheme, so new wilayas 59–69
-appear under their mother wilaya).
+```js
+import offices from "@geoalgeria/poste/data/postoffices.json" with { type: "json" };
+// or via CDN, no install:
+// https://cdn.jsdelivr.net/npm/@geoalgeria/poste/data/postoffices.json
+```
 
-## Files
+**CSV and GeoJSON** are in the repo under [`data/`](data) and bundled in every
+[GitHub Release](https://github.com/yasserstudio/geoalgeria/releases):
 
 ```
 data/
-  postoffices.json          # 3908 offices (array)
-  atms.json                 # 2026 ATMs (array)
-  metadata.json             # source, counts, generated_at
-  csv/postoffices.csv
+  postoffices.json            # 3,908 offices (array)
+  atms.json                   # 2,026 ATMs (array)
+  metadata.json               # source, counts, generated_at
+  csv/postoffices.csv         # repo + Release bundle (not in npm tarball)
   csv/atms.csv
-  geojson/postoffices.geojson   # Point features (offices with coordinates)
+  geojson/postoffices.geojson # Point features (records with coordinates)
   geojson/atms.geojson
 ```
 
-> GeoJSON files include only records that have coordinates — a handful of
-> offices and ATMs report no `lat`/`lng` and are omitted from the GeoJSON
-> outputs (but remain in the JSON/CSV). ATM records have no `commune_code`
-> (the source API does not provide one).
+> GeoJSON includes only records that have coordinates — a handful of offices and
+> ATMs report no `lat`/`lng` and are omitted there (but remain in JSON/CSV). ATM
+> records have no `commune_code` (the source API doesn't provide one).
 
 ## Record shapes
 
@@ -54,7 +81,6 @@ data/
   "name_ar": "أدرار م ر",
   "class": "CE",
   "postal_code": "01000",
-  "postal_code_old": null,
   "address": "ADRAR CENTRE RUE DES MARYTIM",
   "commune_code": "0101",
   "commune_fr": "ADRAR",
@@ -67,46 +93,29 @@ data/
 }
 ```
 
-`class` is the office category (`CE`, `R1`–`R4`, `HC`, `GA`). `commune_code`
-is Algérie Poste's 4-digit commune code, which joins to GeoAlgeria's
-`code_commune` field.
-
-**ATM**
-
-```json
-{
-  "id": "1165",
-  "name": "AOULEF",
-  "status": "1",
-  "postal_code": "01003",
-  "postal_code_old": null,
-  "address": null,
-  "commune_fr": "AOULEF",
-  "commune_ar": "أولف",
-  "wilaya_code": "01",
-  "wilaya_fr": "ADRAR",
-  "wilaya_ar": "أدرار",
-  "lat": 26.9728317,
-  "lng": 1.07709
-}
-```
+`class` is the office category (`CE`, `R1`–`R4`, `HC`, `GA`). `commune_code` is
+Algérie Poste's 4-digit commune code, which joins to GeoAlgeria's `code_commune`.
 
-## Usage
+**ATM** — same shape, keyed by `id`/`name`/`postal_code`/`wilaya_*` with `lat`/`lng`; no `commune_code`.
 
-```js
-import poste from "@geoalgeria/poste";
+## Need the administrative divisions too?
 
-const offices = poste.postOffices();      // 3908
-const banks = poste.atms();               // 2026
+If you also need wilayas, dairas, and communes, use the main
+**[`geoalgeria`](https://www.npmjs.com/package/geoalgeria)** package — it mirrors
+this postal data in and exposes `postOffices` / `atms` alongside the full
+division dataset. Use `@geoalgeria/poste` when you *only* need postal/banking data.
 
-// All post offices in a commune (joins GeoAlgeria code_commune -> commune_code)
-const inCommune = offices.filter((o) => o.commune_code === "1731");
-```
+## Source
 
-Or load a specific format directly: `@geoalgeria/poste/data/geojson/atms.geojson`.
+Data comes from **Algérie Poste** via the public BaridiMap API
+(<https://baridimap.poste.dz>). Run `npm run fetch` to regenerate every output
+from the live API; the same run mirrors the data into the `geoalgeria` package so
+the two never drift (this package is the canonical source). Re-fetch periodically
+— BaridiMap still files offices under the 58-wilaya scheme, so new wilayas 59–69
+currently appear under their mother wilaya.
 
 ## License & attribution
 
-Code is MIT. The underlying data is © **Algérie Poste** and is redistributed
-here for reference and to power [GeoAlgeria](https://geoalgeria.com). Verify
-against Algérie Poste for authoritative, real-time information.
+Code is [MIT](LICENSE). The underlying data is © **Algérie Poste**, redistributed
+for reference and to power [GeoAlgeria](https://geoalgeria.com). Verify against
+Algérie Poste for authoritative, real-time information.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geoalgeria/poste",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "type": "module",
   "description": "Algeria post offices (3908) and ATMs (2026) — real postal codes, bilingual names, coordinates, commune/wilaya linkage. Sourced from Algérie Poste (baridimap.poste.dz). JSON, CSV, GeoJSON.",
   "main": "index.js",
@@ -35,11 +35,11 @@
     "access": "public"
   },
   "bugs": {
-    "url": "https://github.com/yasserstudio/geoalgeria.com/issues"
+    "url": "https://github.com/yasserstudio/geoalgeria/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/yasserstudio/geoalgeria.com.git",
+    "url": "git+https://github.com/yasserstudio/geoalgeria.git",
     "directory": "packages/poste"
   },
   "homepage": "https://geoalgeria.com",