@geoalgeria/ecoles 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Yasser's Studio (https://yasser.studio)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ar.md

@@ -0,0 +1,199 @@
+[English](README.md) | [Français](README.fr.md) | **العربية**
+
+<div align="center">
+
+# @geoalgeria/ecoles
+
+**مدارس الجزائر — كبيانات قابلة للتثبيت.**
+
+[![npm](https://img.shields.io/npm/v/@geoalgeria/ecoles)](https://www.npmjs.com/package/@geoalgeria/ecoles)
+[![npm downloads](https://img.shields.io/npm/dm/@geoalgeria/ecoles)](https://www.npmjs.com/package/@geoalgeria/ecoles)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+</div>
+
+**11٬830 مدرسة بإحداثيات جغرافية** عبر **69 ولاية** في الجزائر — كلٌّ بإحداثياته،
+مُصنَّفة حسب **الطور** (ابتدائي · متوسط/CEM · ثانوي/lycée · تحضيري)، ومعظمها باسمٍ
+عربي و/أو فرنسي، مع ربطٍ بالبلدية والولاية. مُستخرَجة من **OpenStreetMap**
+ومُقدَّمة بصدقٍ مقابل نحو 28٬000 مؤسسة في الشبكة المدرسية الوطنية. متوفرة بصيغ JSON
+وCSV وGeoJSON وTypeScript. جزء من
+[GeoAlgeria](https://github.com/yasserstudio/geoalgeria).
+
+```bash
+npm install @geoalgeria/ecoles
+```
+
+```js
+import ecoles from "@geoalgeria/ecoles";
+
+const all = ecoles.ecoles();   // 11٬830 مدرسة بإحداثيات
+
+// ثانويات ولاية معيّنة (ربطٌ على wilaya_code من GeoAlgeria)
+const lyceesSetif = all.filter((e) => e.wilaya_code === "19" && e.cycle === "secondaire");
+
+// المدارس المُسمّاة فقط، باسمٍ فرنسي
+const named = all.filter((e) => e.name_fr);
+```
+
+## ماذا يمكنك أن تبني
+
+- **خرائط وأدلّة المدارس** — إحداثيات على كامل السجلّات الـ11٬830، جاهزة لخريطة أو
+  لترتيبٍ حسب أقرب مدرسة.
+- **تفصيلٌ حسب الطور** — رشِّح الابتدائي / المتوسط / الثانوي / التحضيري، أو رتِّب
+  كثافة المدارس حسب البلدية/الولاية.
+- **أدلّة ثنائية اللغة** — آلاف الأسماء بالعربية والفرنسية جنبًا إلى جنب.
+
+## المحتوى
+
+| مجموعة البيانات | العدد | الإحداثيات | ملاحظات |
+| --- | --- | --- | --- |
+| المدارس | **11٬830** | ✅ الكل | 8٬640 مُسمّاة، 69 ولاية |
+
+**حسب الطور**
+
+| الطور | العدد | المعنى |
+| --- | --- | --- |
+| `primaire` | 4٬020 | مدرسة ابتدائية (ISCED 1) |
+| `moyen` | 2٬377 | متوسطة / CEM (ISCED 2) |
+| `secondaire` | 1٬574 | ثانوية / lycée (ISCED 3) |
+| `prescolaire` | 268 | تحضيري / روضة (ISCED 0) |
+| `autre` | 3٬591 | مدرسة غير محدّدة الطور (بلا اسم، أو اسمٌ بلا كلمة طور) |
+
+> **هذا استخراجٌ من OpenStreetMap، وليس سجلًّا رسميًّا.** التغطية جزئية ومتفاوتة
+> بين الولايات — نحو 11.8 ألف مدرسة مُخرَّطة مقابل ~28٬000 في الشبكة الوطنية
+> (ابتدائي + متوسط + ثانوي، وزارة التربية الوطنية، تقريبيًّا). تتغيّر الأعداد مع
+> تعديل OpenStreetMap.
+
+**الطور مُستنتَج.** يأتي من `isced:level` ومن الاسم الفرنسي/العربي — فالمتوسطة
+تحمل دائمًا متوسطة/collège، والثانوية ثانوية/lycée، والروضة روضة/préscolaire. أمّا
+«مدرسة»/«école» المجرّدة بلا كلمة طور فتُصنَّف `primaire` بحكم العُرف الجزائري؛ وما
+تبقّى دون حسمٍ فهو `autre`. تحصل 93٪ من المدارس *المُسمّاة* على طورٍ محدّد.
+
+**حسب النوع (`kind`)** — الـ`kind` هو نوع المؤسسة، *مستقلٌّ* عن الطور، ليتيح ترشيح
+(أو عزل) الأماكن الخاصة التي يصنّفها OpenStreetMap تحت `amenity=school`:
+
+| النوع | العدد | المعنى | الطور |
+| --- | --- | --- | --- |
+| `regular` | 11٬640 | مدرسة/متوسطة/ثانوية/روضة عادية | طورها الحقيقي |
+| `formation` | 91 | مركز تكوين مهني | `autre` |
+| `coranique` | 40 | مدرسة قرآنية | `autre` |
+| `langues` | 24 | مدرسة/معهد لغات | `autre` |
+| `special` | 30 | مدرسة للتربية الخاصة (الصم، المكفوفين…) | يحتفظ بطوره |
+| `conduite` | 5 | مدرسة تعليم السياقة | `autre` |
+
+الأنواع الأربعة خارج التعليم الأساسي (`formation`/`coranique`/`langues`/`conduite`)
+تحمل الطور `autre` — فهي ليست مدارس ابتدائية رغم احتواء اسمها على «école»؛ الـ`kind`
+يجعلها قابلة للعثور بدل ضياعها في `autre`.
+
+**كذلك في كل سجلّ:** `isced_levels` (مستويات `isced:level` من OSM، مُطبَّعة كقائمة
+مرتّبة مثل `"1;2"` — في 2٬037 سجلًّا)، و`address` (من وسوم `addr:*` — في 2٬625)،
+و`sector` (`public`/`private` حيث تشير الخريطة).
+
+## الصيغ
+
+يوفّر حزمة npm صيغة **JSON** (قابلة للاستيراد مباشرة):
+
+```js
+import ecoles from "@geoalgeria/ecoles/data/ecoles.json" with { type: "json" };
+// أو عبر CDN، دون تثبيت:
+// https://cdn.jsdelivr.net/npm/@geoalgeria/ecoles/data/ecoles.json
+```
+
+المُحمِّلات وأشكال السجلّات مُنمّطة بالكامل — تعريفات TypeScript مُضمَّنة في الحزمة:
+
+```ts
+import ecoles, { type Ecole } from "@geoalgeria/ecoles";
+const all: Ecole[] = ecoles.ecoles();
+```
+
+صيغتا **CSV وGeoJSON** موجودتان في المستودع ضمن [`data/`](data) ومُضمَّنتان في كل
+[إصدار على GitHub](https://github.com/yasserstudio/geoalgeria/releases):
+
+```
+data/
+  ecoles.json              # 11٬830 مدرسة (مصفوفة)
+  metadata.json            # المصدر، الأعداد، التغطية، generated_at
+  csv/ecoles.csv           # المستودع + حزمة الإصدار (ليست في حزمة npm)
+  geojson/ecoles.geojson   # معالم نقطية
+```
+
+## شكل السجلّ
+
+```json
+{
+  "id": "16-00042",
+  "source": "osm",
+  "osm_id": "way/292876445",
+  "name": "Lycée El Idrissi",
+  "name_ar": "ثانوية الإدريسي",
+  "name_fr": "Lycée El Idrissi",
+  "cycle": "secondaire",
+  "cycle_label_fr": "Lycée",
+  "cycle_label_ar": "ثانوية",
+  "kind": "regular",
+  "kind_label_fr": "École ordinaire",
+  "kind_label_ar": "مدرسة عادية",
+  "isced_levels": "3",
+  "sector": null,
+  "wilaya": "Alger",
+  "wilaya_ar": "الجزائر",
+  "wilaya_code": "16",
+  "commune": "Casbah",
+  "commune_code": 1607,
+  "address": null,
+  "lat": 36.779365,
+  "lng": 3.05949,
+  "geo_precision": "osm_centroid"
+}
+```
+
+`id` مفتاحٌ ثابت `{wilaya_code}-{seq}` يُوَلِّده GeoAlgeria؛ و`osm_id` يعود إلى
+الكائن المصدر. `name` يكون `null` للنقاط غير المُسمّاة. `cycle` هو الطور و`kind`
+نوع المؤسسة (انظر أعلاه)، ولكلٍّ منهما تسميتان ثنائيتا اللغة. `isced_levels`
+و`address` يأتيان مباشرةً من OSM (`null` عند غياب الوسوم). `sector` يكون
+`"public"`/`"private"` فقط عند وجود إشارةٍ صريحة، وإلّا `null`. `geo_precision`
+يكون `osm_node` (نقطة مسحية) أو `osm_centroid` (مركز مُخطَّط مبنى). ويُربَط
+`wilaya_code` بِـ`wilaya_code` من GeoAlgeria.
+
+> **ربط البلدية/الولاية مُستنتَج، لا يأتي من المصدر.** لا يحمل OpenStreetMap الرموز
+> الإدارية الجزائرية. يُلحِق GeoAlgeria `wilaya_code` و`commune_code` و`commune`
+> عبر **ربطٍ بأقرب مركز ثقل** مقابل مجموعة بلديات
+> [`geoalgeria`](https://www.npmjs.com/package/geoalgeria). إسناد الولاية دقيقٌ
+> عمليًّا؛ أمّا البلدية فأفضل تقدير (قرب المركز، لا الاحتواء المضلَّعي).
+
+## أتحتاج إلى التقسيمات الإدارية أيضًا؟
+
+للولايات والدوائر والبلديات، استخدم الحزمة الرئيسية
+**[`geoalgeria`](https://www.npmjs.com/package/geoalgeria)** — بها تُحوِّل
+`commune_code` لمدرسةٍ إلى مُضلَّعٍ أو مركز ثقل. استخدم `@geoalgeria/ecoles` حين
+تحتاج إلى المدارس *فقط*.
+
+## المصدر والمنهجية
+
+شغّل `npm run fetch` لإعادة توليد كل المخرجات. يقوم السكربت بِـ:
+
+1. الاستعلام من **OpenStreetMap** (Overpass) عن `amenity=school` و
+   `amenity=kindergarten` داخل الجزائر؛
+2. **تصنيف الطور** من `isced:level` والاسم الفرنسي/العربي؛
+3. إزالة تكرار المدرسة نفسها المُخرَّطة كنقطةٍ ومبنى معًا؛
+4. إلحاق البلدية/الولاية بأقرب مركز ثقل بلدية.
+
+تُخزَّن الاستخراجات الخام مؤقتًا ضمن
+[`research/ecoles/`](https://github.com/yasserstudio/geoalgeria/tree/main/research/ecoles).
+
+## الرخصة والإسناد
+
+**كود** الحزمة تحت رخصة [MIT](LICENSE). أمّا **البيانات** فمن **OpenStreetMap** —
+**© مساهمو OpenStreetMap**، تحت رخصة
+**[ODbL 1.0](https://www.openstreetmap.org/copyright)**. إذا استخدمت هذه البيانات
+أو أعدت توزيعها، فعليك **إسناد الفضل لمساهمي OpenStreetMap** وإبقاء قواعد البيانات
+المُشتقّة تحت رخصةٍ متوافقة.
+
+تحقّق من المصادر الرسمية للحصول على معلوماتٍ موثوقة. تُقدَّم هذه البيانات للاستئناس
+ولتشغيل [GeoAlgeria](https://geoalgeria.com).
+
+[توثيق الـAPI والحقول →](https://geoalgeria.com/data/docs/ecoles) · [تصفّح كل الحزم →](https://geoalgeria.com/data)
+
+---
+
+من إنجاز [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

@@ -0,0 +1,210 @@
+[English](README.md) | **Français** | [العربية](README.ar.md)
+
+<div align="center">
+
+# @geoalgeria/ecoles
+
+**Les écoles d'Algérie — sous forme de données prêtes à installer.**
+
+[![npm](https://img.shields.io/npm/v/@geoalgeria/ecoles)](https://www.npmjs.com/package/@geoalgeria/ecoles)
+[![npm downloads](https://img.shields.io/npm/dm/@geoalgeria/ecoles)](https://www.npmjs.com/package/@geoalgeria/ecoles)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+</div>
+
+**11 830 écoles géolocalisées** dans les **69 wilayas** d'Algérie — chacune avec
+ses coordonnées, classée par **cycle** (primaire · moyen/CEM · secondaire/lycée ·
+préscolaire), la plupart avec un nom en arabe et/ou en français, et un
+rattachement commune/wilaya. Extraites d'**OpenStreetMap** et présentées
+honnêtement face aux ~28 000 établissements du réseau scolaire national. Livré en
+JSON, CSV, GeoJSON et TypeScript. Fait partie de
+[GeoAlgeria](https://github.com/yasserstudio/geoalgeria).
+
+```bash
+npm install @geoalgeria/ecoles
+```
+
+```js
+import ecoles from "@geoalgeria/ecoles";
+
+const all = ecoles.ecoles();   // 11 830 écoles géolocalisées
+
+// Lycées d'une wilaya (jointure sur wilaya_code de GeoAlgeria)
+const lyceesSetif = all.filter((e) => e.wilaya_code === "19" && e.cycle === "secondaire");
+
+// Uniquement les écoles nommées, avec un libellé français
+const named = all.filter((e) => e.name_fr);
+```
+
+## Ce que vous pouvez construire
+
+- **Cartes & annuaires d'écoles** — coordonnées sur les 11 830 enregistrements,
+  prêtes pour une carte ou un tri par école la plus proche.
+- **Répartitions par cycle** — filtrez primaire / moyen / secondaire /
+  préscolaire, ou classez la densité scolaire par commune/wilaya.
+- **Annuaires bilingues** — des milliers de noms en arabe et en français, côte à côte.
+
+## Contenu
+
+| Jeu de données | Nombre | Coordonnées | Notes |
+| --- | --- | --- | --- |
+| Écoles | **11 830** | ✅ toutes | 8 640 nommées, 69 wilayas |
+
+**Par cycle**
+
+| Cycle | Nombre | Signification |
+| --- | --- | --- |
+| `primaire` | 4 020 | école primaire (CITE 1) |
+| `moyen` | 2 377 | collège d'enseignement moyen / CEM (CITE 2) |
+| `secondaire` | 1 574 | lycée (CITE 3) |
+| `prescolaire` | 268 | préscolaire / maternelle / روضة (CITE 0) |
+| `autre` | 3 591 | école de cycle indéterminé (non nommée, ou nom sans mot de cycle) |
+
+> **Il s'agit d'un extrait OpenStreetMap, pas d'un registre officiel.** La
+> couverture est partielle et inégale selon les wilayas — ~11,8k écoles
+> cartographiées face aux ~28 000 du réseau national (primaire + moyen +
+> secondaire, Ministère de l'Éducation Nationale, approximatif). Les nombres
+> évoluent au fil des contributions à OpenStreetMap.
+
+**Le cycle est déduit.** Il provient d'`isced:level` et du nom français/arabe —
+un CEM se nomme toujours متوسطة/collège, un lycée ثانوية/lycée, une maternelle
+روضة/préscolaire. Une simple « école »/« مدرسة » sans mot de cycle est classée
+`primaire` par convention algérienne ; le reste est `autre`. 93 % des écoles
+*nommées* obtiennent un cycle précis.
+
+**Par type (`kind`)** — le `kind` est le type d'établissement, *orthogonal* au
+cycle, pour filtrer (ou isoler) les lieux particuliers qu'OSM classe sous
+`amenity=school` :
+
+| Type | Nombre | Signification | Cycle |
+| --- | --- | --- | --- |
+| `regular` | 11 640 | école / CEM / lycée / maternelle ordinaire | son cycle réel |
+| `formation` | 91 | centre de formation professionnelle | `autre` |
+| `coranique` | 40 | école coranique | `autre` |
+| `langues` | 24 | école / institut de langues | `autre` |
+| `special` | 30 | école spécialisée (sourds, aveugles…) | garde son cycle |
+| `conduite` | 5 | auto-école | `autre` |
+
+Les quatre types hors K-12 (`formation`/`coranique`/`langues`/`conduite`) portent
+le cycle `autre` — ce ne sont pas des écoles primaires même si leur nom contient
+« école » ; le `kind` les rend repérables au lieu de les noyer dans `autre`.
+
+**Aussi sur chaque enregistrement :** `isced_levels` (les niveaux `isced:level`
+d'OSM, normalisés en liste triée comme `"1;2"` — sur 2 037 enregistrements),
+`address` (depuis les tags OSM `addr:*` — sur 2 625) et `sector`
+(`public`/`private` là où la carte le signale).
+
+## Formats
+
+Le paquet npm fournit le **JSON** (importable directement) :
+
+```js
+import ecoles from "@geoalgeria/ecoles/data/ecoles.json" with { type: "json" };
+// ou via CDN, sans installation :
+// https://cdn.jsdelivr.net/npm/@geoalgeria/ecoles/data/ecoles.json
+```
+
+Les chargeurs et les formes d'enregistrement sont entièrement **typés** — les
+définitions TypeScript sont incluses dans le paquet :
+
+```ts
+import ecoles, { type Ecole } from "@geoalgeria/ecoles";
+const all: Ecole[] = ecoles.ecoles();
+```
+
+Les fichiers **CSV et GeoJSON** sont dans le dépôt sous [`data/`](data) et
+inclus dans chaque
+[Release GitHub](https://github.com/yasserstudio/geoalgeria/releases) :
+
+```
+data/
+  ecoles.json              # 11 830 écoles (tableau)
+  metadata.json            # source, décomptes, couverture, generated_at
+  csv/ecoles.csv           # dépôt + bundle Release (pas dans le tarball npm)
+  geojson/ecoles.geojson   # entités Point
+```
+
+## Forme d'un enregistrement
+
+```json
+{
+  "id": "16-00042",
+  "source": "osm",
+  "osm_id": "way/292876445",
+  "name": "Lycée El Idrissi",
+  "name_ar": "ثانوية الإدريسي",
+  "name_fr": "Lycée El Idrissi",
+  "cycle": "secondaire",
+  "cycle_label_fr": "Lycée",
+  "cycle_label_ar": "ثانوية",
+  "kind": "regular",
+  "kind_label_fr": "École ordinaire",
+  "kind_label_ar": "مدرسة عادية",
+  "isced_levels": "3",
+  "sector": null,
+  "wilaya": "Alger",
+  "wilaya_ar": "الجزائر",
+  "wilaya_code": "16",
+  "commune": "Casbah",
+  "commune_code": 1607,
+  "address": null,
+  "lat": 36.779365,
+  "lng": 3.05949,
+  "geo_precision": "osm_centroid"
+}
+```
+
+`id` est une clé stable `{wilaya_code}-{seq}` synthétisée par GeoAlgeria ;
+`osm_id` renvoie à l'objet source. `name` est `null` pour les points non nommés.
+`cycle` est le niveau et `kind` le type d'établissement (voir ci-dessus), chacun
+avec des libellés bilingues. `isced_levels` et `address` proviennent directement
+d'OSM (`null` si les tags sont absents). `sector` vaut `"public"`/`"private"`
+uniquement en présence d'un signal explicite, sinon `null`. `geo_precision` vaut
+`osm_node` (point relevé) ou `osm_centroid` (centre d'un contour de bâtiment).
+`wilaya_code` se joint au `wilaya_code` de GeoAlgeria.
+
+> **Le rattachement commune/wilaya est déduit, pas issu de la source.**
+> OpenStreetMap ne porte pas les codes administratifs algériens. GeoAlgeria
+> attache `wilaya_code`, `commune_code` et `commune` par une **jointure au
+> centroïde le plus proche** contre le jeu de communes
+> [`geoalgeria`](https://www.npmjs.com/package/geoalgeria). La wilaya est
+> quasi exacte ; la commune est au mieux (proximité de centroïde, pas
+> d'inclusion polygonale).
+
+## Besoin aussi des divisions administratives ?
+
+Pour les wilayas, daïras et communes, utilisez le paquet principal
+**[`geoalgeria`](https://www.npmjs.com/package/geoalgeria)** — c'est ainsi que
+vous transformez le `commune_code` d'une école en polygone ou centroïde. Utilisez
+`@geoalgeria/ecoles` lorsque vous ne voulez *que* les écoles.
+
+## Source & méthode
+
+Lancez `npm run fetch` pour régénérer toutes les sorties. Le script :
+
+1. interroge **OpenStreetMap** (Overpass) pour `amenity=school` et
+   `amenity=kindergarten` en Algérie ;
+2. **classe le cycle** à partir d'`isced:level` et du nom français/arabe ;
+3. déduplique la même école cartographiée à la fois comme nœud et comme bâtiment ;
+4. attache commune/wilaya par centroïde de commune le plus proche.
+
+Les extractions brutes sont mises en cache sous
+[`research/ecoles/`](https://github.com/yasserstudio/geoalgeria/tree/main/research/ecoles).
+
+## Licence & attribution
+
+Le **code** du paquet est sous [MIT](LICENSE). Les **données** proviennent
+d'**OpenStreetMap** — **© les contributeurs d'OpenStreetMap**, sous licence
+**[ODbL 1.0](https://www.openstreetmap.org/copyright)**. Si vous utilisez ou
+redistribuez ce jeu de données, vous devez **attribuer les contributeurs
+d'OpenStreetMap** et conserver les bases dérivées sous une licence compatible.
+
+Vérifiez auprès des sources officielles pour toute information faisant autorité.
+Ce jeu de données est fourni à titre de référence et pour alimenter
+[GeoAlgeria](https://geoalgeria.com).
+
+[Docs API & champs →](https://geoalgeria.com/data/docs/ecoles) · [Voir tous les paquets →](https://geoalgeria.com/data)
+
+---
+
+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

@@ -0,0 +1,203 @@
+**English** | [Français](README.fr.md) | [العربية](README.ar.md)
+
+<div align="center">
+
+# @geoalgeria/ecoles
+
+**The schools of Algeria — as data you can install.**
+
+[![npm](https://img.shields.io/npm/v/@geoalgeria/ecoles)](https://www.npmjs.com/package/@geoalgeria/ecoles)
+[![npm downloads](https://img.shields.io/npm/dm/@geoalgeria/ecoles)](https://www.npmjs.com/package/@geoalgeria/ecoles)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+</div>
+
+**11,830 geocoded schools** across all **69 wilayas** of Algeria — every one with
+coordinates, classified by **cycle** (primaire · moyen/CEM · secondaire/lycée ·
+préscolaire), most with Arabic and/or French names, and commune/wilaya linkage.
+Extracted from **OpenStreetMap** and framed honestly against the ~28,000
+establishments of the national school network. Shipped as JSON, CSV, GeoJSON, and
+TypeScript. Part of [GeoAlgeria](https://github.com/yasserstudio/geoalgeria).
+
+```bash
+npm install @geoalgeria/ecoles
+```
+
+```js
+import ecoles from "@geoalgeria/ecoles";
+
+const all = ecoles.ecoles();   // 11,830 geocoded schools
+
+// Lycées in a wilaya (joins GeoAlgeria's wilaya_code)
+const lyceesSetif = all.filter((e) => e.wilaya_code === "19" && e.cycle === "secondaire");
+
+// Only the named ones, with a French label
+const named = all.filter((e) => e.name_fr);
+```
+
+## What you can build
+
+- **School maps & locators** — coordinates on all 11,830 records, ready for a map
+  or nearest-school distance sorting.
+- **Cycle breakdowns** — filter primaire / moyen / secondaire / préscolaire, or
+  rank school density per commune/wilaya across the country.
+- **Bilingual directories** — thousands of Arabic and French names, side by side.
+
+## What's inside
+
+| Dataset | Count | Coordinates | Notes |
+| --- | --- | --- | --- |
+| Schools | **11,830** | ✅ all | 8,640 named, 69 wilayas |
+
+**By cycle**
+
+| Cycle | Count | Meaning |
+| --- | --- | --- |
+| `primaire` | 4,020 | école primaire (ISCED 1) |
+| `moyen` | 2,377 | collège d'enseignement moyen / CEM (ISCED 2) |
+| `secondaire` | 1,574 | lycée (ISCED 3) |
+| `prescolaire` | 268 | préscolaire / maternelle / روضة (ISCED 0) |
+| `autre` | 3,591 | school of undetermined cycle (unnamed, or a name with no cycle word) |
+
+> **This is an OpenStreetMap extract, not an official registry.** Coverage is
+> partial and uneven by wilaya — ~11.8k schools mapped against the ~28,000 in the
+> national network (primaire + moyen + secondaire, Ministry of National
+> Education, approximate). Counts move as OpenStreetMap is edited; each rebuild
+> reflects the current state of the map.
+
+**Cycle is inferred.** It comes from `isced:level` and the French/Arabic name — a
+CEM always names itself متوسطة/collège, a lycée ثانوية/lycée, a maternelle
+روضة/préscolaire. A bare "école"/"مدرسة" with no cycle word is classified
+`primaire` by Algerian convention (a standalone school is a primary school);
+anything unresolved is `autre`. 93% of *named* schools resolve to a specific cycle.
+
+**By kind** — `kind` is the establishment type, *orthogonal* to cycle, so you can
+filter out (or in) the special-purpose places OSM files under `amenity=school`:
+
+| Kind | Count | Meaning | Cycle |
+| --- | --- | --- | --- |
+| `regular` | 11,640 | a standard école / CEM / lycée / maternelle | its real cycle |
+| `formation` | 91 | vocational / training centre | `autre` |
+| `coranique` | 40 | Quranic school | `autre` |
+| `langues` | 24 | language school / institute | `autre` |
+| `special` | 30 | adapted / special-needs school (deaf, blind…) | keeps its cycle |
+| `conduite` | 5 | driving school (auto-école) | `autre` |
+
+The four non-K-12 kinds (`formation`/`coranique`/`langues`/`conduite`) carry
+cycle `autre` — they're *not* primary schools even though their name contains
+"école"; `kind` is what makes them findable instead of buried in `autre`.
+
+**Also on each record:** `isced_levels` (the OSM `isced:level` served, normalized
+to a sorted list like `"1;2"` — on 2,037 records), `address` (from OSM `addr:*`
+tags — on 2,625), and `sector` (`public`/`private` where the map signals it).
+
+## Formats
+
+The npm package ships the **JSON** (importable directly):
+
+```js
+import ecoles from "@geoalgeria/ecoles/data/ecoles.json" with { type: "json" };
+// or via CDN, no install:
+// https://cdn.jsdelivr.net/npm/@geoalgeria/ecoles/data/ecoles.json
+```
+
+The loaders and record shapes are fully **typed** — TypeScript definitions ship in the package:
+
+```ts
+import ecoles, { type Ecole } from "@geoalgeria/ecoles";
+const all: Ecole[] = ecoles.ecoles();
+```
+
+**CSV and GeoJSON** are in the repo under [`data/`](data) and bundled in every
+[GitHub Release](https://github.com/yasserstudio/geoalgeria/releases):
+
+```
+data/
+  ecoles.json              # 11,830 schools (array)
+  metadata.json            # source, counts, coverage, generated_at
+  csv/ecoles.csv           # repo + Release bundle (not in npm tarball)
+  geojson/ecoles.geojson   # Point features
+```
+
+## Record shape
+
+```json
+{
+  "id": "16-00042",
+  "source": "osm",
+  "osm_id": "way/292876445",
+  "name": "Lycée El Idrissi",
+  "name_ar": "ثانوية الإدريسي",
+  "name_fr": "Lycée El Idrissi",
+  "cycle": "secondaire",
+  "cycle_label_fr": "Lycée",
+  "cycle_label_ar": "ثانوية",
+  "kind": "regular",
+  "kind_label_fr": "École ordinaire",
+  "kind_label_ar": "مدرسة عادية",
+  "isced_levels": "3",
+  "sector": null,
+  "wilaya": "Alger",
+  "wilaya_ar": "الجزائر",
+  "wilaya_code": "16",
+  "commune": "Casbah",
+  "commune_code": 1607,
+  "address": null,
+  "lat": 36.779365,
+  "lng": 3.05949,
+  "geo_precision": "osm_centroid"
+}
+```
+
+`id` is a stable `{wilaya_code}-{seq}` key synthesized by GeoAlgeria; `osm_id`
+links back to the upstream object. `name` is the best available display name and
+is `null` for unnamed points. `cycle` is the education level and `kind` the
+establishment type (see above), each with bilingual labels. `isced_levels` and
+`address` come straight from OSM (`null` when the tags are absent). `sector` is
+`"public"`/`"private"` only when the map carries an explicit signal, else `null`.
+`geo_precision` is `osm_node` (a surveyed point) or `osm_centroid` (a building
+outline's centre). `wilaya_code` joins to GeoAlgeria's `wilaya_code`.
+
+> **Commune/wilaya linkage is derived, not from the source.** OpenStreetMap does
+> not carry Algerian administrative codes. GeoAlgeria attaches `wilaya_code`,
+> `commune_code`, and `commune` by a **nearest-centroid join** against the
+> [`geoalgeria`](https://www.npmjs.com/package/geoalgeria) commune set. Wilaya
+> assignment is effectively exact; commune is best-effort (centroid proximity,
+> not polygon containment).
+
+## Need the administrative divisions too?
+
+For wilayas, dairas, and communes, use the main
+**[`geoalgeria`](https://www.npmjs.com/package/geoalgeria)** package — it's how
+you turn a school's `commune_code` into a polygon or centroid. Use
+`@geoalgeria/ecoles` when you *only* need the schools.
+
+## Source & method
+
+Run `npm run fetch` to regenerate every output. It:
+
+1. queries **OpenStreetMap** (Overpass) for `amenity=school` and
+   `amenity=kindergarten` inside Algeria;
+2. **classifies the cycle** from `isced:level` and the French/Arabic name;
+3. de-duplicates the same school mapped as both a node and a building;
+4. attaches commune/wilaya by nearest commune centroid.
+
+Raw source pulls are cached under
+[`research/ecoles/`](https://github.com/yasserstudio/geoalgeria/tree/main/research/ecoles).
+
+## License & attribution
+
+Package **code** is [MIT](LICENSE). The **data** is from **OpenStreetMap** —
+**© OpenStreetMap contributors**, licensed under the
+**[ODbL 1.0](https://www.openstreetmap.org/copyright)**. If you use or
+redistribute this dataset, you must **attribute OpenStreetMap contributors** and
+keep derived databases under a compatible license.
+
+Verify against official sources for authoritative information. This dataset is
+provided for reference and to power [GeoAlgeria](https://geoalgeria.com).
+
+[API docs & field reference →](https://geoalgeria.com/data/docs/ecoles) · [Browse all packages →](https://geoalgeria.com/data)
+
+---
+
+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)