Pular para o conteúdo principal

Localidades

As localidades são o nível mais fino da hierarquia geográfica. Representam aldeias ou bairros.

Hierarquia geográfica​

Região → Setor → Município → Localidade
                              ^^^^^^^^^^

GET /api/localites​

Obtém a lista das localidades.

Endpoint​

GET /api/localites

Headers​

HeaderValorObrigatório
AuthorizationBearer {token}Sim

Parâmetros de filtro​

ParâmetroTipoDescrição
typestringFiltrar por tipo (village ou quartier)
secteur.idUUIDFiltrar por setor
secteur.commune.idUUIDFiltrar por município

Resposta de sucesso​

Código: 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}​

Obtém uma localidade pelo seu identificador.

Endpoint​

GET /api/localites/{id}

Resposta de sucesso​

Código: 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​

Cria uma nova localidade (apenas ADMIN).

Endpoint​

POST /api/localites

Corpo do pedido​

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

Campos​

CampoTipoObrigatórioDescrição
nomstringSimNome da localidade
codestringNãoCódigo da localidade
typestringNãoTipo: village (padrão) ou quartier
populationintegerNãoPopulação estimada
secteurIRISimReferência ao setor

Resposta de sucesso​

Código: 201 Created

PUT /api/localites/{id}​

Modifica uma localidade (apenas ADMIN).

Endpoint​

PUT /api/localites/{id}

Corpo do pedido​

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

DELETE /api/localites/{id}​

Elimina uma localidade (apenas ADMIN).

Endpoint​

DELETE /api/localites/{id}

Resposta de sucesso​

Código: 204 No Content

Exemplos​

cURL - Filtrar por tipo​

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

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

cURL - Filtrar por setor​

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();
};

// Aldeias de um setor
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()

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

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

Tipos de localidade​

TipoDescrição
villageZona rural
quartierZona urbana

Campos​

CampoTipoObrigatórioDescrição
idUUID-Identificador único
nomstringSimNome da localidade
codestringNãoCódigo da localidade
typestringNãovillage ou quartier (padrão: village)
populationintegerNãoPopulação estimada
secteurIRISimReferência ao setor pai

Notas​

  • As localidades são o nível mais preciso para a geolocalização dos agregados familiares
  • O tipo permite distinguir as zonas rurais (aldeias) das zonas urbanas (bairros)
  • A população é uma estimativa utilizada para as estatísticas
  • A criação/modificação/eliminação requer o papel ADMIN