Régions

Les régions sont le niveau supérieur de la hiérarchie géographique.

Hiérarchie géographique

Région → Secteur → Localité

GET /api/geo/regions

Récupère la liste des régions avec pagination.

Endpoint

GET /api/geo/regions

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

Réponse succès

Code: 200 OK

{
    "success": true,
    "data": [
        {
            "id": "990e8400-e29b-41d4-a716-446655440001",
            "nom": "Bafatá",
            "code": "BA",
            "latitude": 12.1667,
            "longitude": -14.6667,
            "nbMenages": 1250
        },
        {
            "id": "990e8400-e29b-41d4-a716-446655440002",
            "nom": "Oio",
            "code": "OI",
            "latitude": 12.2833,
            "longitude": -15.1167,
            "nbMenages": 980
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 50,
        "total": 9,
        "pages": 1
    }
}

Champs de réponse

Champ	Type	Description
id	UUID	Identifiant unique
nom	string	Nom de la région
code	string	Code de la région
latitude	float|null	Latitude du centroïde
longitude	float|null	Longitude du centroïde
nbMenages	integer	Nombre de ménages dans 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/regions/{id}

Récupère une région par son identifiant.

Endpoint

GET /api/geo/regions/{id}

Réponse succès

Code: 200 OK

{
    "success": true,
    "data": {
        "id": "990e8400-e29b-41d4-a716-446655440001",
        "nom": "Bafatá",
        "code": "BA",
        "latitude": 12.1667,
        "longitude": -14.6667
    }
}

Réponse erreur

Code: 404 Not Found

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

---

POST /api/geo/regions

Crée une nouvelle région (ADMIN ou permission regions.create).

Endpoint

POST /api/geo/regions

Corps de la requête

{
    "nom": "Nouvelle Région",
    "code": "NR",
    "latitude": 12.5,
    "longitude": -15.0
}

Champs

Champ	Type	Requis	Description
nom	string	Oui	Nom de la région
code	string	Non	Code de la région
latitude	number	Non	Latitude du centroïde
longitude	number	Non	Longitude du centroïde

Réponse succès

Code: 201 Created

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

---

PUT /api/geo/regions/{id}

Modifie une région (ADMIN ou permission regions.edit).

Endpoint

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

Corps de la requête

{
    "nom": "Région Modifiée",
    "code": "RM"
}

Réponse succès

Code: 200 OK

{
    "success": true
}

---

DELETE /api/geo/regions/{id}

Supprime une région (ADMIN ou permission regions.delete).

Endpoint

DELETE /api/geo/regions/{id}

Réponse succès

Code: 200 OK

{
    "success": true
}

---

Exemples

cURL - Liste avec pagination

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

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

cURL - Région par ID

curl "https://mariacare.ucp-pch.org/api/geo/regions/990e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: Bearer TOKEN"

JavaScript

const getRegions = async (page = 1, limit = 50, search = '') => {
    const params = new URLSearchParams({
        page: page.toString(),
        limit: limit.toString()
    });

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

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

// Utilisation avec pagination
const result = await getRegions(1, 10);
console.log(`Total régions: ${result.pagination.total}`);
console.log(`Pages: ${result.pagination.pages}`);

result.data.forEach(region => {
    console.log(`${region.code}: ${region.nom} (${region.nbMenages} ménages)`);
});

Python

import requests

def get_regions(token, page=1, limit=50, search=None):
    params = {'page': page, 'limit': limit}
    if search:
        params['search'] = search

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

# Utilisation avec pagination
result = get_regions(token, page=1, limit=10)
print(f"Total: {result['pagination']['total']}")
print(f"Pages: {result['pagination']['pages']}")

for region in result['data']:
    print(f"{region['code']}: {region['nom']} ({region['nbMenages']} ménages)")

Permissions

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

Notes

• Les coordonnées GPS (latitude/longitude) représentent le centroïde de la région
• Le champ nbMenages compte les ménages directement associés à cette région
• La recherche est insensible à la casse et filtre par nom ou code