Data Models Explained

Overview of the three barangay PSGC data model shapes: nested (basic), flat (list), and extended (recursive tree). Choose the right model for your use case.
Author

bendlikeabamboo

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": "component_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": "component_city",
        "psgc_id": "1900702000",
        "parent_psgc_id": "1900700000",
        "nicknames": null
    },
    {
        "name": "Arco",
        "type": "barangay",
        "psgc_id": "1900702001",
        "parent_psgc_id": "1900702000",
        "nicknames": null
    }
]

See also