Municipalities

Municipalities are the third level of the geographic hierarchy, linked to a department.

Geographic hierarchy

Region → Sector → Municipality → Locality
                  ^^^^^^^^^^^^

GET /api/communes

Retrieves the list of municipalities.

Endpoint

GET /api/communes

Headers

Header	Value	Required
Authorization	Bearer {token}	Yes

Success response

Code: 200 OK

{
    "@context": "/api/contexts/Commune",
    "@id": "/api/communes",
    "@type": "hydra:Collection",
    "hydra:totalItems": 552,
    "hydra:member": [
        {
            "@id": "/api/communes/bb0e8400-e29b-41d4-a716-446655440001",
            "@type": "Commune",
            "id": "bb0e8400-e29b-41d4-a716-446655440001",
            "nom": "Commune de Dakar",
            "code": "COM-DK-001",
            "departement": {
                "@id": "/api/departements/cc0e8400-e29b-41d4-a716-446655440001",
                "nom": "Département de Dakar"
            }
        },
        {
            "@id": "/api/communes/bb0e8400-e29b-41d4-a716-446655440002",
            "@type": "Commune",
            "id": "bb0e8400-e29b-41d4-a716-446655440002",
            "nom": "Commune de Pikine",
            "code": "COM-DK-002",
            "departement": {
                "@id": "/api/departements/cc0e8400-e29b-41d4-a716-446655440002",
                "nom": "Département de Pikine"
            }
        }
    ],
    "hydra:view": {
        "@id": "/api/communes?page=1",
        "hydra:first": "/api/communes?page=1",
        "hydra:last": "/api/communes?page=19"
    }
}

---

GET /api/communes/{id}

Retrieves a municipality by its identifier.

Endpoint

GET /api/communes/{id}

Success response

Code: 200 OK

{
    "@context": "/api/contexts/Commune",
    "@id": "/api/communes/bb0e8400-e29b-41d4-a716-446655440001",
    "@type": "Commune",
    "id": "bb0e8400-e29b-41d4-a716-446655440001",
    "nom": "Commune de Dakar",
    "code": "COM-DK-001",
    "departement": {
        "@id": "/api/departements/cc0e8400-e29b-41d4-a716-446655440001",
        "@type": "Departement",
        "nom": "Département de Dakar"
    }
}

---

Examples

cURL

# List of municipalities
curl https://sig.ucp-pch.org/api/communes \
  -H "Authorization: Bearer TOKEN"

# Municipality by ID
curl https://sig.ucp-pch.org/api/communes/bb0e8400-e29b-41d4-a716-446655440001 \
  -H "Authorization: Bearer TOKEN"

JavaScript

const getCommunes = async () => {
    const response = await fetch(
        'https://sig.ucp-pch.org/api/communes',
        {
            headers: {
                'Authorization': `Bearer ${localStorage.getItem('token')}`
            }
        }
    );
    return response.json();
};

// Usage
const communes = await getCommunes();
console.log(`${communes['hydra:totalItems']} municipalities`);

communes['hydra:member'].forEach(commune => {
    console.log(`${commune.nom} - ${commune.departement?.nom || 'N/A'}`);
});

Python

import requests

def get_communes(token):
    response = requests.get(
        'https://sig.ucp-pch.org/api/communes',
        headers={'Authorization': f'Bearer {token}'}
    )
    return response.json()

# Usage
communes = get_communes(token)
print(f"Total: {communes['hydra:totalItems']} municipalities")

for commune in communes['hydra:member']:
    dept = commune.get('departement', {}).get('nom', 'N/A')
    print(f"- {commune['nom']} ({dept})")

Fields

Field	Type	Description
id	UUID	Unique identifier
nom	string	Municipality name
code	string	Municipality code
departement	object	Parent department (nullable)

Notes

• Municipalities are linked to a department (optional)
• Used as reference for households
• Creation/modification requires the ADMIN role