> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wethehivers.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Données géographiques

> Régions, villes et quartiers du Cameroun utilisés par l'API

# Données géographiques

THE HIVE utilise un référentiel **Cameroun-first** : 10 régions, \~50 villes principales, et les quartiers pour les grandes métropoles.

## Modèle

```mermaid theme={null}
classDiagram
    class Region {
        Long id
        String nom
        String code
        String chefLieu
    }
    class Ville {
        Long id
        Long regionId
        String nom
        String slug
        Double latitude
        Double longitude
        int population
    }
    class Quartier {
        Long id
        Long villeId
        String nom
        String slug
    }
    Region "1" --> "*" Ville
    Ville "1" --> "*" Quartier
```

## Endpoints

```http theme={null}
GET /v1/api/regions                       → 10 régions
GET /v1/api/regions/{id}/villes          → villes d'une région
GET /v1/api/villes                        → toutes les villes (~50)
GET /v1/api/villes/{id}                   → détail ville
GET /v1/api/villes/{id}/quartiers        → quartiers d'une ville
GET /v1/api/villes/search?q=dou          → autocomplete
```

Toutes ces données sont **publiques** (pas de token nécessaire) et peuvent être cachées **24 h**.

## Les 10 régions

| Code | Nom          | Chef-lieu  | Villes principales                  |
| ---- | ------------ | ---------- | ----------------------------------- |
| `AD` | Adamaoua     | Ngaoundéré | Ngaoundéré, Meiganga, Tibati        |
| `CE` | Centre       | Yaoundé    | Yaoundé, Mbalmayo, Bafia, Obala     |
| `ES` | Est          | Bertoua    | Bertoua, Batouri, Abong-Mbang       |
| `EN` | Extrême-Nord | Maroua     | Maroua, Kousséri, Mokolo            |
| `LT` | Littoral     | Douala     | Douala, Nkongsamba, Édéa            |
| `NO` | Nord         | Garoua     | Garoua, Guider, Figuil              |
| `NW` | Nord-Ouest   | Bamenda    | Bamenda, Kumbo, Wum                 |
| `OU` | Ouest        | Bafoussam  | Bafoussam, Dschang, Foumban, Mbouda |
| `SU` | Sud          | Ebolowa    | Ebolowa, Kribi, Sangmélima          |
| `SW` | Sud-Ouest    | Buéa       | Buéa, Limbé, Kumba                  |

```mermaid theme={null}
flowchart TB
    CMR[Cameroun] --> N[Nord]
    CMR --> S[Sud]
    N --> AD[Adamaoua]
    N --> NO[Nord]
    N --> EN[Extrême-Nord]
    S --> CE[Centre]
    S --> LT[Littoral]
    S --> OU[Ouest]
    S --> NW[Nord-Ouest]
    S --> SW[Sud-Ouest]
    S --> ES[Est]
    S --> SU[Sud]
```

## Villes principales

```mermaid theme={null}
flowchart LR
    LT[Littoral] --> DLA[Douala - 3.6M hab]
    LT --> NKS[Nkongsamba]
    LT --> EDE[Édéa]
    CE[Centre] --> YDE[Yaoundé - 2.8M hab]
    CE --> MBA[Mbalmayo]
    OU[Ouest] --> BAF[Bafoussam]
    OU --> DSC[Dschang]
    SW[Sud-Ouest] --> BUE[Buéa]
    SW --> LIM[Limbé]
    NO[Nord] --> GAR[Garoua]
    EN[Extrême-Nord] --> MAR[Maroua]
    AD[Adamaoua] --> NGA[Ngaoundéré]
    SU[Sud] --> KRI[Kribi]
    NW[Nord-Ouest] --> BAM[Bamenda]
    ES[Est] --> BER[Bertoua]
```

## Exemple de réponse `/regions`

```json theme={null}
[
  { "id": 1, "code": "LT", "nom": "Littoral", "chefLieu": "Douala" },
  { "id": 2, "code": "CE", "nom": "Centre", "chefLieu": "Yaoundé" },
  { "id": 3, "code": "OU", "nom": "Ouest", "chefLieu": "Bafoussam" },
  { "id": 4, "code": "NW", "nom": "Nord-Ouest", "chefLieu": "Bamenda" },
  { "id": 5, "code": "SW", "nom": "Sud-Ouest", "chefLieu": "Buéa" },
  { "id": 6, "code": "NO", "nom": "Nord", "chefLieu": "Garoua" },
  { "id": 7, "code": "EN", "nom": "Extrême-Nord", "chefLieu": "Maroua" },
  { "id": 8, "code": "AD", "nom": "Adamaoua", "chefLieu": "Ngaoundéré" },
  { "id": 9, "code": "SU", "nom": "Sud", "chefLieu": "Ebolowa" },
  { "id": 10, "code": "ES", "nom": "Est", "chefLieu": "Bertoua" }
]
```

## Exemple `/villes/{id}`

```json theme={null}
{
  "id": 55,
  "regionId": 1,
  "nom": "Douala",
  "slug": "douala",
  "latitude": 4.0511,
  "longitude": 9.7679,
  "population": 3600000,
  "quartiers": 42
}
```

## Quartiers (grandes villes)

Disponible pour : **Douala** (\~42 quartiers), **Yaoundé** (\~38), **Bafoussam** (\~12), **Garoua** (\~10), **Bamenda** (\~15), **Maroua** (\~8), **Buéa** (\~8).

```mermaid theme={null}
flowchart LR
    DLA[Douala] --> AK[Akwa]
    DLA --> BO[Bonapriso]
    DLA --> BS[Bonanjo]
    DLA --> MA[Makepe]
    DLA --> DE[Deido]
    DLA --> NB[New Bell]
    DLA --> BEP[Bépanda]
    DLA --> KO[Kotto]
    DLA --> LO[Logbaba]
    DLA --> PK[PK-14 / PK-17]
```

Exemple JSON :

```json theme={null}
{
  "villeId": 55,
  "quartiers": [
    { "id": 101, "nom": "Akwa", "slug": "akwa" },
    { "id": 102, "nom": "Bonapriso", "slug": "bonapriso" },
    { "id": 103, "nom": "Bonanjo", "slug": "bonanjo" },
    { "id": 104, "nom": "Makepe", "slug": "makepe" }
  ]
}
```

## Autocomplete

```http theme={null}
GET /v1/api/villes/search?q=dou
```

```json theme={null}
{
  "suggestions": [
    { "id": 55, "nom": "Douala", "regionNom": "Littoral" },
    { "id": 72, "nom": "Doumé", "regionNom": "Est" }
  ]
}
```

```mermaid theme={null}
flowchart LR
    Q[Query "dou"] --> PGTRG[pg_trgm similarity]
    PGTRG --> RANK[Ranking + population boost]
    RANK --> TOP[Top 10]
    TOP --> JSON[Réponse]
```

## Géolocalisation inversée

Pour convertir lat/lng en ville :

```http theme={null}
POST /v1/api/geo/reverse
{ "latitude": 4.05, "longitude": 9.77 }
```

```json theme={null}
{
  "ville": { "id": 55, "nom": "Douala" },
  "quartier": { "id": 101, "nom": "Akwa" },
  "distance": 1.2
}
```

Implémenté via requête PostGIS `ST_DWithin` sur index `GIST` des centroïdes quartier.

## Source des données

```mermaid theme={null}
flowchart LR
    INS[INS Cameroun] --> IMP[Import CSV]
    OSM[OpenStreetMap] --> IMP
    UN[UN-LOCODE] --> IMP
    IMP --> SEED[Flyway seed V20260101120000__001_geo_seed.sql]
    SEED --> DB[(PostgreSQL)]
    DB --> API[API GET /regions]
```

* **Population** : estimations INS 2023
* **Coordonnées** : centroïdes OpenStreetMap
* **Quartiers** : compilation manuelle + validation locale

## Mise à jour

Le référentiel est **en lecture seule** côté API. Les modifications passent par une migration Flyway (ex. ajout d'une nouvelle ville lors d'un recensement).

```mermaid theme={null}
flowchart LR
    DEMAND[Demande d'ajout ville] --> PR[Merge Request backend]
    PR --> REVIEW[Review data team]
    REVIEW --> MIG[Migration Flyway V{ts}__geo_add.sql]
    MIG --> DEPLOY[Déploiement backend]
    DEPLOY --> LIVE[Disponible API]
```

## Utilisation typique

```mermaid theme={null}
sequenceDiagram
    participant C as Client
    participant API as Backend

    C->>API: GET /regions
    API-->>C: [10 régions]
    C->>API: GET /regions/1/villes
    API-->>C: [villes Littoral]
    C->>API: GET /villes/55/quartiers
    API-->>C: [quartiers Douala]
    C->>C: Afficher cascade Region → Ville → Quartier
```

## Voir aussi

* [Modèle Entreprise](/models/entreprise)
* [Modèle Offre](/models/offre)
* [Recherche d'offres](/guides/recherche-offres)