Skip to main content

Localities

Localities are the finest level of the geographic hierarchy. They represent villages or neighborhoods.

Geographic hierarchy​

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

GET /api/localites​

Retrieves the list of localities.

Endpoint​

GET /api/localites

Headers​

HeaderValueRequired
AuthorizationBearer {token}Yes

Filter parameters​

ParameterTypeDescription
typestringFilter by type (village or quartier)
secteur.idUUIDFilter by sector
secteur.commune.idUUIDFilter by municipality

Success response​

Code: 200 OK

{
    "@context": "/api/contexts/Localite",
    "@id": "/api/localites",
    "@type": "hydra:Collection",
    "hydra:totalItems": 2450,
    "hydra:member": [
        {
            "@id": "/api/localites/dd0e8400-e29b-41d4-a716-446655440001",
            "@type": "Localite",
            "id": "dd0e8400-e29b-41d4-a716-446655440001",
            "nom": "Village de Ndiaye",
            "code": "VIL-001",
            "type": "village",
            "population": 1250,
            "secteur": {
                "@id": "/api/secteurs/aa0e8400-e29b-41d4-a716-446655440001",
                "nom": "Secteur 1"
            }
        },
        {
            "@id": "/api/localites/dd0e8400-e29b-41d4-a716-446655440002",
            "@type": "Localite",
            "id": "dd0e8400-e29b-41d4-a716-446655440002",
            "nom": "Quartier Médina",
            "code": "QUA-001",
            "type": "quartier",
            "population": 8500,
            "secteur": {
                "@id": "/api/secteurs/aa0e8400-e29b-41d4-a716-446655440002",
                "nom": "Secteur 2"
            }
        }
    ],
    "hydra:view": {
        "@id": "/api/localites?page=1",
        "hydra:first": "/api/localites?page=1",
        "hydra:last": "/api/localites?page=82"
    }
}

GET /api/localites/{id}​

Retrieves a locality by its identifier.

Endpoint​

GET /api/localites/{id}

Success response​

Code: 200 OK

{
    "@context": "/api/contexts/Localite",
    "@id": "/api/localites/dd0e8400-e29b-41d4-a716-446655440001",
    "@type": "Localite",
    "id": "dd0e8400-e29b-41d4-a716-446655440001",
    "nom": "Village de Ndiaye",
    "code": "VIL-001",
    "type": "village",
    "population": 1250,
    "secteur": {
        "@id": "/api/secteurs/aa0e8400-e29b-41d4-a716-446655440001",
        "@type": "Secteur",
        "nom": "Secteur 1",
        "commune": {
            "@id": "/api/communes/bb0e8400-e29b-41d4-a716-446655440001",
            "nom": "Commune 1"
        }
    }
}

POST /api/localites​

Creates a new locality (ADMIN only).

Endpoint​

POST /api/localites

Request body​

{
    "nom": "Nouveau Village",
    "code": "NV-001",
    "type": "village",
    "population": 500,
    "secteur": "/api/secteurs/aa0e8400-e29b-41d4-a716-446655440001"
}

Fields​

FieldTypeRequiredDescription
nomstringYesLocality name
codestringNoLocality code
typestringNoType: village (default) or quartier
populationintegerNoEstimated population
secteurIRIYesReference to the sector

Success response​

Code: 201 Created

PUT /api/localites/{id}​

Updates a locality (ADMIN only).

Endpoint​

PUT /api/localites/{id}

Request body​

{
    "nom": "Village de Ndiaye Modifié",
    "population": 1500
}

DELETE /api/localites/{id}​

Deletes a locality (ADMIN only).

Endpoint​

DELETE /api/localites/{id}

Success response​

Code: 204 No Content

Examples​

cURL - Filter by type​

# Villages only
curl "https://sig.ucp-pch.org/api/localites?type=village" \
  -H "Authorization: Bearer TOKEN"

# Neighborhoods only
curl "https://sig.ucp-pch.org/api/localites?type=quartier" \
  -H "Authorization: Bearer TOKEN"

cURL - Filter by sector​

curl "https://sig.ucp-pch.org/api/localites?secteur.id=aa0e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: Bearer TOKEN"

JavaScript​

const getLocalites = async (filters = {}) => {
    const params = new URLSearchParams();

    if (filters.type) params.append('type', filters.type);
    if (filters.secteurId) params.append('secteur.id', filters.secteurId);
    if (filters.communeId) params.append('secteur.commune.id', filters.communeId);

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

// Villages of a sector
const villages = await getLocalites({
    type: 'village',
    secteurId: 'aa0e8400-e29b-41d4-a716-446655440001'
});

villages['hydra:member'].forEach(loc => {
    console.log(`${loc.nom} - Pop: ${loc.population || 'N/A'}`);
});

Python​

import requests

def get_localites(token, **filters):
    params = {}
    if 'type' in filters:
        params['type'] = filters['type']
    if 'secteur_id' in filters:
        params['secteur.id'] = filters['secteur_id']
    if 'commune_id' in filters:
        params['secteur.commune.id'] = filters['commune_id']

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

# Villages only
villages = get_localites(token, type='village')
print(f"Total villages: {villages['hydra:totalItems']}")

for v in villages['hydra:member']:
    pop = v.get('population', 'N/A')
    print(f"- {v['nom']} ({v['secteur']['nom']}) - Pop: {pop}")

Locality types​

TypeDescription
villageRural area
quartierUrban area

Fields​

FieldTypeRequiredDescription
idUUID-Unique identifier
nomstringYesLocality name
codestringNoLocality code
typestringNovillage or quartier (default: village)
populationintegerNoEstimated population
secteurIRIYesReference to the parent sector

Notes​

  • Localities are the most precise level for geolocating households
  • The type allows distinguishing rural areas (villages) from urban areas (neighborhoods)
  • The population is an estimate used for statistics
  • Creation/modification/deletion requires the ADMIN role