syscohada-registry-geo

Package compagnon de syscohada-registry avec données géographiques complètes pour les 14 pays SYSCOHADA

📦 Installation

npm install syscohada-registry-geo

# Ou avec yarn
yarn add syscohada-registry-geo

# Ou avec pnpm
pnpm add syscohada-registry-geo

Note : Ce package nécessite syscohada-registry version 2.1.0 ou supérieure.

✨ Fonctionnalités

Phase 1 (v0.1.0) - Projet pilote SN + ML ✅

• ✅ Données complètes Sénégal : 14 régions, 45 départements, ~557 communes
• ✅ Données complètes Mali : 10 régions, 56 cercles, ~703 communes
• ✅ Moteur de recherche avec fuzzy matching
• ✅ Validation stricte des hiérarchies
• ✅ API riche pour accès aux données

Phases futures

• Phase 2 (v0.5.0) : Extension UEMOA (BF, CI, BJ, TG, NE, GW)
• Phase 3 (v1.0.0) : Extension CEMAC (CM, CF, TD, CG, GA, GQ)

🚀 Utilisation rapide

import { searchVilles, findVilleByName, getHierarchieComplete } from 'syscohada-registry-geo';

// Recherche fuzzy de villes
const results = searchVilles({
  query: 'Dakar',
  country: 'SN',
  limit: 10
});

console.log(results[0]);
// {
//   ville: {
//     code: 'SN-DK-DAK-001',
//     name: 'Dakar-Plateau',
//     departementCode: 'SN-DK-DAK',
//     regionCode: 'SN-DK',
//     country: 'SN',
//     population: 25000,
//     isCapital: false,
//     isRegionalCapital: false,
//     isDepartementalCapital: true
//   },
//   score: 0.95
// }

// Recherche exacte
const dakar = findVilleByName('Dakar', 'SN');

// Hiérarchie complète d'un pays
const hierarchieSN = getHierarchieComplete('SN');
console.log(hierarchieSN.regions.length); // 14
console.log(hierarchieSN.villes.length);  // ~557

📚 API

Recherche

searchVilles(options: VilleSearchOptions): VilleSearchResult[]

Recherche fuzzy de villes avec score de pertinence.

interface VilleSearchOptions {
  query: string;
  country?: SyscohadaCountry;
  region?: string;
  departement?: string;
  limit?: number;
  threshold?: number; // Score minimum (0-1)
}

findVilleByName(name: string, country?: SyscohadaCountry): VilleInfo | null

Recherche exacte d'une ville par nom.

Accès hiérarchique

// Récupération par pays
getVillesByPays(country: SyscohadaCountry): VilleInfo[]
getRegionsByPays(country: SyscohadaCountry): RegionInfo[]
getHierarchieComplete(country: SyscohadaCountry): HierarchieAdministrative

// Récupération par région
getVillesByRegion(regionCode: string): VilleInfo[]
getDepartementsByRegion(regionCode: string): DepartementInfo[]

// Récupération par département
getVillesByDepartement(departementCode: string): VilleInfo[]

Validation

validateCommune(commune: string, country: SyscohadaCountry): ValidationResult

Validation stricte avec vérification d'existence réelle.

const result = validateCommune('Dakar-Plateau', 'SN');
// result.isValid === true (existe réellement)

const result2 = validateCommune('VilleInexistante', 'SN');
// result2.isValid === false
// result2.errors === ['La commune "VilleInexistante" n\'existe pas au Sénégal']

validateHierarchie(data: {...}): ValidationResult

Validation de cohérence hiérarchique.

const result = validateHierarchie({
  region: 'Dakar',
  departement: 'Dakar',
  commune: 'Dakar-Plateau',
  country: 'SN'
});
// result.isValid === true (cohérence vérifiée)

Métadonnées

// Principales villes d'un pays
getPrincipalesVilles(country: SyscohadaCountry, limit?: number): VilleInfo[]

// Statistiques
getGeoStats(country: SyscohadaCountry): GeoStats
isCountryDataAvailable(country: SyscohadaCountry): boolean

🌍 Couverture géographique

Phase 1 (v0.1.0)

| Pays | Régions | Départements | Villes | |------|---------|--------------|--------| | 🇸🇳 Sénégal | 14 | 45 | ~557 | | 🇲🇱 Mali | 10 | 56 | ~703 | | Total | 24 | 101 | ~1260 |

Objectif final (v1.0.0)

14 pays SYSCOHADA : ~142 régions, ~605 départements, ~3358 villes

🏗️ Architecture

Ce package utilise :

• Lazy loading : Chargement des données par pays uniquement quand nécessaire
• Format compact : Optimisation de la taille des données
• Tree-shaking : Imports granulaires par pays
• Fuzzy matching : Recherche tolérante aux fautes de frappe

📊 Taille du package

• Compressé (gzip) : ~150-200KB (Phase 1 avec 2 pays)
• Objectif final : < 1MB pour les 14 pays

🤝 Contribution

Les contributions sont les bienvenues ! Voir CONTRIBUTING.md.

📄 Licence

MIT © Hypnoz Team

🔗 Liens utiles

• syscohada-registry - Package principal
• Documentation complète
• Issues