ug-address

A lightweight Python SDK for cascading Uganda address selection.

Supports:

District → County/Division → Sub-county → Parish → Village

The SDK is:

• dependency-free
• offline-first
• fast
• pure Python
• framework agnostic

Perfect for:

• Django apps
• Flask apps
• FastAPI
• CLI tools
• data processing
• backend validation
• Uganda-based SaaS products

---

Installation

pip install ug-address

---

Quick Start

from ug_address import UgAddress

addr = UgAddress()

districts = addr.get_districts()

print(districts[:5])

---

Example Output

[
    {
        "id": "98",
        "name": "ABIM"
    },
    {
        "id": "1",
        "name": "ADJUMANI"
    }
]

---

Full Example

from ug_address import UgAddress

addr = UgAddress()

# -----------------------------------
# Get districts
# -----------------------------------

districts = addr.get_districts()

print('DISTRICTS:\n')

for district in districts[:5]:

    print(
        district['id'],
        '-',
        district['name']
    )

# -----------------------------------
# Select district
# -----------------------------------

addr.select_district('32')  # Kampala

counties = addr.get_counties()

print('\nCOUNTIES:\n')

for county in counties:

    print(
        county['id'],
        '-',
        county['name']
    )

# -----------------------------------
# Select county
# -----------------------------------

addr.select_county(counties[0]['id'])

subcounties = addr.get_subcounties()

print('\nSUBCOUNTIES:\n')

for subcounty in subcounties[:5]:

    print(
        subcounty['id'],
        '-',
        subcounty['name']
    )

# -----------------------------------
# Select subcounty
# -----------------------------------

addr.select_subcounty(subcounties[0]['id'])

parishes = addr.get_parishes()

print('\nPARISHES:\n')

for parish in parishes[:5]:

    print(
        parish['id'],
        '-',
        parish['name']
    )

# -----------------------------------
# Select parish
# -----------------------------------

addr.select_parish(parishes[0]['id'])

villages = addr.get_villages()

print('\nVILLAGES:\n')

for village in villages[:5]:

    print(
        village['id'],
        '-',
        village['name']
    )

# -----------------------------------
# Select village
# -----------------------------------

addr.select_village(villages[0]['id'])

# -----------------------------------
# Final address
# -----------------------------------

print('\nFORMATTED ADDRESS:\n')

print(
    addr.get_formatted_address()
)

# -----------------------------------
# Raw selection
# -----------------------------------

print('\nRAW SELECTION:\n')

print(
    addr.get_selection()
)

---

API Reference

---

Constructor

from ug_address import UgAddress

addr = UgAddress()

---

Data Getters

All getters return alphabetically sorted lists.

---

get_districts()

Returns all Uganda districts.

districts = addr.get_districts()

---

get_counties(district_id=None)

Returns counties/divisions for a district.

counties = addr.get_counties('32')

If no ID is provided, the currently selected district is used.

---

get_subcounties(county_id=None)

Returns sub-counties for a county.

subcounties = addr.get_subcounties('69')

---

get_parishes(subcounty_id=None)

Returns parishes for a sub-county.

parishes = addr.get_parishes('1546')

---

get_villages(parish_id=None)

Returns villages/cells for a parish.

villages = addr.get_villages('9127')

---

Selection Methods

Selecting a level automatically clears downstream selections.

---

select_district(id)

addr.select_district('32')

---

select_county(id)

addr.select_county('69')

---

select_subcounty(id)

addr.select_subcounty('1546')

---

select_parish(id)

addr.select_parish('9127')

---

select_village(id)

addr.select_village('57217')

---

Event Listeners

The SDK supports reactive callbacks.

---

on_district_change()

addr.on_district_change(
    lambda e: print(e)
)

Event structure:

{
    "district_id": "32",
    "counties": [...]
}

---

on_county_change()

addr.on_county_change(
    lambda e: print(e)
)

---

on_subcounty_change()

addr.on_subcounty_change(
    lambda e: print(e)
)

---

on_parish_change()

addr.on_parish_change(
    lambda e: print(e)
)

---

on_village_change()

addr.on_village_change(
    lambda e: print(e)
)

---

Reading the Selection

get_selection()

Returns the currently selected hierarchy.

selection = addr.get_selection()

Example:

{
    "district": {
        "id": "32",
        "name": "KAMPALA"
    },
    "county": {
        "id": "69",
        "name": "KAMPALA CENTRAL DIVISION"
    },
    "subcounty": {
        "id": "123",
        "name": "CENTRAL WARD"
    },
    "parish": {
        "id": "456",
        "name": "NAKASERO PARISH"
    },
    "village": {
        "id": "789",
        "name": "NAKASERO VILLAGE A"
    }
}

---

get_formatted_address()

Returns a human-readable address string.

addr.get_formatted_address()

Example:

Nakasero Village A, Nakasero Parish, Central Ward, Kampala Central Division, Kampala

---

Reset

reset()

Clears all selected levels.

addr.reset()

---

Data Structure

District
└── County / Division
    └── Sub-county
        └── Parish
            └── Village / Cell

Relationships:

county.district === district.id
subcounty.county === county.id
parish.subcounty === subcounty.id
village.parish === parish.id

---

Use Cases

• Uganda registration forms
• Backend address validation
• Location normalization
• GIS preprocessing
• CRM systems
• Fintech onboarding
• Delivery systems
• Government systems
• Health systems
• Logistics platforms

---

Performance

The SDK ships with embedded Uganda administrative data:

• no API requests
• no database needed
• works fully offline

---

License

MIT License

Free for:

• commercial use
• open-source projects
• SaaS products
• government systems
• educational projects

---

Links

• GitHub: https://github.com/jessebyarugaba/ug-address-python
• Issues: https://github.com/jessebyarugaba/ug-address-python/issues
• npm: https://www.npmjs.com/package/@jessebyarugaba/ug-address