The barangay package provides three distinct data model formats, each optimized for specific use cases.
BARANGAY
A compact nested structure ideal for quick lookups and simple hierarchical access. Organizes barangays by region, province/HUC, and municipality/city.
{
"Bangsamoro Autonomous Region In Muslim Mindanao (BARMM)": {
"Basilan": {
"City of Lamitan": [
"Arco",
"Ba-as",
"Baimbing"
]
}
}
}
BARANGAY_EXTENDED
A fully hierarchical tree structure that preserves the complete administrative lineage. Each node contains its PSGC identifier, parent reference, type, and optional nicknames.
{
"name": "Philippines",
"type": "country",
"psgc_id": "0000000000",
"parent_psgc_id": "n/a",
"nicknames": null,
"components": [
{
"name": "Bangsamoro Autonomous Region In Muslim Mindanao (BARMM)",
"type": "region",
"psgc_id": "1900000000",
"parent_psgc_id": "0000000000",
"nicknames": null,
"components": [
{
"name": "Basilan",
"type": "province",
"psgc_id": "1900700000",
"parent_psgc_id": "1900000000",
"nicknames": null,
"components": [
{
"name": "City of Lamitan",
"type": "city",
"psgc_id": "1900702000",
"parent_psgc_id": "1900700000",
"nicknames": null,
"components": [
{
"name": "Arco",
"type": "barangay",
"psgc_id": "1900702001",
"parent_psgc_id": "1900702000",
"nicknames": null,
"components": []
}
]
}
]
}
]
}
]
}
BARANGAY_FLAT
A denormalized array format optimized for database storage and bulk operations. Each entry is independent, with parent relationships established through parent_psgc_id.
[
{
"name": "Bangsamoro Autonomous Region In Muslim Mindanao (BARMM)",
"type": "region",
"psgc_id": "1900000000",
"parent_psgc_id": "0000000000",
"nicknames": null
},
{
"name": "Basilan",
"type": "province",
"psgc_id": "1900700000",
"parent_psgc_id": "1900000000",
"nicknames": null
},
{
"name": "City of Lamitan",
"type": "city",
"psgc_id": "1900702000",
"parent_psgc_id": "1900700000",
"nicknames": null
},
{
"name": "Arco",
"type": "barangay",
"psgc_id": "1900702001",
"parent_psgc_id": "1900702000",
"nicknames": null
}
]