Localités

Les localités sont le niveau le plus fin de la hiérarchie géographique. Elles représentent des villages ou des quartiers.

Hiérarchie géographique

Région → Secteur → Localité
                   ^^^^^^^^^

GET /api/geo/localites

Récupère la liste des localités avec pagination.

Endpoint

GET /api/geo/localites

Headers

Header	Valeur	Requis
Authorization	Bearer {token}	Oui

Paramètres de requête

Paramètre	Type	Défaut	Description
page	integer	1	Numéro de la page
limit	integer	50	Nombre d'éléments par page (max: 100)
search	string	-	Recherche par nom ou code
regionId	UUID	-	Filtrer par région
region	UUID	-	Alias pour regionId
secteurId	UUID	-	Filtrer par secteur
secteur	UUID	-	Alias pour secteurId

Réponse succès

Code: 200 OK

{
    "success": true,
    "data": [
        {
            "id": "dd0e8400-e29b-41d4-a716-446655440001",
            "nom": "Cuntuboel Centro",
            "code": "CTB-001",
            "type": "village",
            "population": 1250,
            "nbMenages": 180,
            "latitude": 12.3833,
            "longitude": -14.5333,
            "secteurId": "aa0e8400-e29b-41d4-a716-446655440001",
            "secteurNom": "Contuboel",
            "regionId": "990e8400-e29b-41d4-a716-446655440001",
            "regionNom": "Bafatá"
        },
        {
            "id": "dd0e8400-e29b-41d4-a716-446655440002",
            "nom": "Sare Bacar",
            "code": "CTB-002",
            "type": "village",
            "population": 850,
            "nbMenages": 120,
            "latitude": 12.4000,
            "longitude": -14.5500,
            "secteurId": "aa0e8400-e29b-41d4-a716-446655440001",
            "secteurNom": "Contuboel",
            "regionId": "990e8400-e29b-41d4-a716-446655440001",
            "regionNom": "Bafatá"
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 50,
        "total": 245,
        "pages": 5
    }
}

Champs de réponse

Champ	Type	Description
id	UUID	Identifiant unique
nom	string	Nom de la localité
code	string\|null	Code de la localité
type	string\|null	Type : `village` ou `quartier`
population	integer\|null	Population estimée
nbMenages	integer\|null	Nombre de ménages estimés
latitude	float\|null	Latitude
longitude	float\|null	Longitude
secteurId	UUID\|null	Identifiant du secteur parent
secteurNom	string\|null	Nom du secteur parent
regionId	UUID\|null	Identifiant de la région
regionNom	string\|null	Nom de la région

Pagination

Champ	Type	Description
page	integer	Page courante
limit	integer	Éléments par page
total	integer	Nombre total d'éléments
pages	integer	Nombre total de pages

GET /api/geo/localites/{id}

Récupère une localité par son identifiant.

Endpoint

GET /api/geo/localites/{id}

Réponse succès

Code: 200 OK

{
    "success": true,
    "data": {
        "id": "dd0e8400-e29b-41d4-a716-446655440001",
        "nom": "Cuntuboel Centro",
        "code": "CTB-001",
        "type": "village",
        "population": 1250,
        "nbMenages": 180,
        "latitude": 12.3833,
        "longitude": -14.5333,
        "secteurId": "aa0e8400-e29b-41d4-a716-446655440001",
        "secteurNom": "Contuboel",
        "regionId": "990e8400-e29b-41d4-a716-446655440001",
        "regionNom": "Bafatá"
    }
}

Réponse erreur

Code: 404 Not Found

{
    "success": false,
    "error": "Not found"
}

POST /api/geo/localites

Crée une nouvelle localité (ADMIN ou permission localites.create).

Endpoint

POST /api/geo/localites

Corps de la requête

{
    "nom": "Nouveau Village",
    "code": "NV-001",
    "type": "village",
    "population": 500,
    "nbMenages": 75,
    "latitude": 12.45,
    "longitude": -14.62,
    "secteurId": "aa0e8400-e29b-41d4-a716-446655440001"
}

Champs

Champ	Type	Requis	Description
nom	string	Oui	Nom de la localité
secteurId	UUID	Oui	Identifiant du secteur parent
code	string	Non	Code de la localité
type	string	Non	`village` ou `quartier`
population	integer	Non	Population estimée
nbMenages	integer	Non	Nombre de ménages estimés
latitude	number	Non	Latitude
longitude	number	Non	Longitude

Réponse succès

Code: 201 Created

{
    "success": true,
    "data": {
        "id": "dd0e8400-e29b-41d4-a716-446655440003"
    }
}

Erreurs

Code: 400 Bad Request

{
    "success": false,
    "error": "Nom requis"
}

{
    "success": false,
    "error": "Secteur requis"
}

Code: 404 Not Found

{
    "success": false,
    "error": "Secteur introuvable"
}

PUT /api/geo/localites/{id}

Modifie une localité (ADMIN ou permission localites.edit).

Endpoint

PUT /api/geo/localites/{id}
PATCH /api/geo/localites/{id}

Corps de la requête

{
    "nom": "Village Modifié",
    "population": 1500,
    "secteurId": "aa0e8400-e29b-41d4-a716-446655440002"
}

Réponse succès

Code: 200 OK

{
    "success": true
}

DELETE /api/geo/localites/{id}

Supprime une localité (ADMIN ou permission localites.delete).

Endpoint

DELETE /api/geo/localites/{id}

Réponse succès

Code: 200 OK

{
    "success": true
}

Exemples

cURL - Liste avec pagination

# Première page de 20 éléments
curl "https://mariacare.ucp-pch.org/api/geo/localites?page=1&limit=20" \
  -H "Authorization: Bearer TOKEN"

# Localités d'une région
curl "https://mariacare.ucp-pch.org/api/geo/localites?regionId=990e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: Bearer TOKEN"

# Localités d'un secteur
curl "https://mariacare.ucp-pch.org/api/geo/localites?secteurId=aa0e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: Bearer TOKEN"

# Recherche par nom
curl "https://mariacare.ucp-pch.org/api/geo/localites?search=cuntuboel" \
  -H "Authorization: Bearer TOKEN"

# Combinaison de filtres avec pagination
curl "https://mariacare.ucp-pch.org/api/geo/localites?regionId=990e8400-...&page=2&limit=10" \
  -H "Authorization: Bearer TOKEN"

JavaScript

const getLocalites = async (options = {}) => {
    const {
        page = 1,
        limit = 50,
        search = '',
        regionId = null,
        secteurId = null
    } = options;

    const params = new URLSearchParams({
        page: page.toString(),
        limit: limit.toString()
    });

    if (search) params.append('search', search);
    if (regionId) params.append('regionId', regionId);
    if (secteurId) params.append('secteurId', secteurId);

    const response = await fetch(
        `https://mariacare.ucp-pch.org/api/geo/localites?${params}`,
        {
            headers: {
                'Authorization': `Bearer ${localStorage.getItem('token')}`
            }
        }
    );
    return response.json();
};

// Toutes les localités avec pagination
const result = await getLocalites({ page: 1, limit: 20 });
console.log(`Total localités: ${result.pagination.total}`);
console.log(`Pages: ${result.pagination.pages}`);

// Localités d'un secteur
const localitesSecteur = await getLocalites({
    secteurId: 'aa0e8400-e29b-41d4-a716-446655440001'
});

localitesSecteur.data.forEach(loc => {
    const pop = loc.population || 'N/A';
    console.log(`${loc.nom} (${loc.type}) - Pop: ${pop}`);
});

// Pagination avec filtre région
async function getAllLocalitesForRegion(regionId) {
    let allData = [];
    let page = 1;
    let hasMore = true;

    while (hasMore) {
        const result = await getLocalites({ regionId, page, limit: 100 });
        allData = allData.concat(result.data);
        hasMore = page < result.pagination.pages;
        page++;
    }

    return allData;
}

Python

import requests

def get_localites(token, page=1, limit=50, search=None, region_id=None, secteur_id=None):
    params = {'page': page, 'limit': limit}
    if search:
        params['search'] = search
    if region_id:
        params['regionId'] = region_id
    if secteur_id:
        params['secteurId'] = secteur_id

    response = requests.get(
        'https://mariacare.ucp-pch.org/api/geo/localites',
        headers={'Authorization': f'Bearer {token}'},
        params=params
    )
    return response.json()

# Toutes les localités avec pagination
result = get_localites(token, page=1, limit=20)
print(f"Total: {result['pagination']['total']}")
print(f"Pages: {result['pagination']['pages']}")

# Localités d'un secteur
localites_secteur = get_localites(
    token,
    secteur_id='aa0e8400-e29b-41d4-a716-446655440001'
)

for loc in localites_secteur['data']:
    pop = loc.get('population', 'N/A')
    print(f"- {loc['nom']} ({loc.get('type', 'N/A')}) - Pop: {pop}")

# Récupérer toutes les localités d'une région (avec pagination)
def get_all_localites_for_region(token, region_id):
    all_data = []
    page = 1

    while True:
        result = get_localites(token, page=page, limit=100, region_id=region_id)
        all_data.extend(result['data'])

        if page >= result['pagination']['pages']:
            break
        page += 1

    return all_data

Types de localité

Type	Description
village	Zone rurale
quartier	Zone urbaine

Permissions

Action	Permission requise
Lecture	`ROLE_USER` + (`ROLE_ADMIN` ou `localites.view`)
Création	`ROLE_ADMIN` ou `localites.create`
Modification	`ROLE_ADMIN` ou `localites.edit`
Suppression	`ROLE_ADMIN` ou `localites.delete`

Notes

Les localités sont le niveau le plus précis pour la géolocalisation des ménages
Le type permet de distinguer les zones rurales (villages) des zones urbaines (quartiers)
Les champs population et nbMenages sont des estimations
La recherche est insensible à la casse et filtre par nom ou code
Les résultats sont triés par nom de région, puis secteur, puis localité
Une localité doit obligatoirement être rattachée à un secteur

Hiérarchie géographique​

GET /api/geo/localites​

Endpoint​

Headers​

Paramètres de requête​

Réponse succès​

Champs de réponse​

Pagination​

GET /api/geo/localites/{id}​

Endpoint​

Réponse succès​

Réponse erreur​

POST /api/geo/localites​

Endpoint​

Corps de la requête​

Champs​

Réponse succès​

Erreurs​

PUT /api/geo/localites/{id}​

Endpoint​

Corps de la requête​

Réponse succès​

DELETE /api/geo/localites/{id}​

Endpoint​

Réponse succès​

Exemples​

cURL - Liste avec pagination​

JavaScript​

Python​

Types de localité​

Permissions​

Notes​

Hiérarchie géographique

GET /api/geo/localites

Endpoint

Headers

Paramètres de requête

Réponse succès

Champs de réponse

Pagination

GET /api/geo/localites/{id}

Endpoint

Réponse succès

Réponse erreur

POST /api/geo/localites

Endpoint

Corps de la requête

Champs

Réponse succès

Erreurs

PUT /api/geo/localites/{id}

Endpoint

Corps de la requête

Réponse succès

DELETE /api/geo/localites/{id}

Endpoint

Réponse succès

Exemples

cURL - Liste avec pagination

JavaScript

Python

Types de localité

Permissions

Notes