GET /api/menages

Retrieves the paginated list of households.

Endpoint

GET /api/menages

Headers

Header	Value	Required
Authorization	Bearer {token}	Yes

Query Parameters

Pagination

Parameter	Type	Default	Description
page	integer	1	Page number
itemsPerPage	integer	30	Items per page (max: 100)

Filters

Parameter	Type	Description
region	IRI	Filter by region (/api/regions/1)
secteur	IRI	Filter by sector
commune	IRI	Filter by municipality
localite	IRI	Filter by locality
statut	string	Filter by status (actif, inactif, en_attente)
search	string	Text search (code, head name)

Sorting

Parameter	Values	Description
order[createdAt]	asc, desc	Sort by creation date
order[codeMenage]	asc, desc	Sort by household code
order[scorePmt]	asc, desc	Sort by PMT score

Success Response

Code: 200 OK

{
    "@context": "/api/contexts/Menage",
    "@id": "/api/menages",
    "@type": "hydra:Collection",
    "hydra:totalItems": 1234,
    "hydra:member": [
        {
            "@id": "/api/menages/1",
            "@type": "Menage",
            "id": 1,
            "codeMenage": "MEN-2024-00001",
            "tailleMenage": 5,
            "scorePmt": "45.67",
            "statut": "actif",
            "chefMenage": {
                "@id": "/api/chef_menages/1",
                "nomComplet": "Mamadou Diallo",
                "sexe": "M",
                "telephone": "771234567"
            },
            "region": {
                "@id": "/api/regions/1",
                "nom": "Dakar"
            },
            "secteur": {
                "@id": "/api/secteurs/1",
                "nom": "Secteur 1"
            },
            "commune": {
                "@id": "/api/communes/1",
                "nom": "Commune 1"
            },
            "createdAt": "2024-01-15T10:30:00+00:00"
        }
    ],
    "hydra:view": {
        "@id": "/api/menages?page=1",
        "@type": "hydra:PartialCollectionView",
        "hydra:first": "/api/menages?page=1",
        "hydra:last": "/api/menages?page=42",
        "hydra:next": "/api/menages?page=2"
    },
    "hydra:search": {
        "@type": "hydra:IriTemplate",
        "hydra:template": "/api/menages{?search,region,secteur,commune,localite,statut}",
        "hydra:variableRepresentation": "BasicRepresentation",
        "hydra:mapping": [
            {"@type": "IriTemplateMapping", "variable": "search", "property": "search"}
        ]
    }
}

Examples

cURL - Simple list

curl https://sig.ucp-pch.org/api/menages \
  -H "Authorization: Bearer TOKEN"

cURL - With filters

curl "https://sig.ucp-pch.org/api/menages?region=/api/regions/1&statut=actif&page=2" \
  -H "Authorization: Bearer TOKEN"

cURL - With search

curl "https://sig.ucp-pch.org/api/menages?search=Diallo" \
  -H "Authorization: Bearer TOKEN"

JavaScript

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

    if (filters.region) params.append('region', filters.region);
    if (filters.statut) params.append('statut', filters.statut);
    if (filters.search) params.append('search', filters.search);
    if (filters.page) params.append('page', filters.page);

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

    return response.json();
};

// Usage
const data = await getMenages({
    region: '/api/regions/1',
    statut: 'actif',
    page: 1
});

console.log(`Total: ${data['hydra:totalItems']} households`);
data['hydra:member'].forEach(menage => {
    console.log(menage.codeMenage, menage.chefMenage.nomComplet);
});

Python

import requests

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

# Simple list
menages = get_menages(token)
print(f"Total: {menages['hydra:totalItems']}")

# With filters
menages = get_menages(
    token,
    region='/api/regions/1',
    statut='actif',
    page=2
)

Notes

• Results are paginated by default (30 items)
• Text search (search) searches in household code and head name
• Geographic filters use IRIs (e.g., /api/regions/1)
• Relations (chefMenage, region) are included in the response