Skip to main content

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

Metadata

Release files for ug-address 1.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ug-address 1.0.1
File Size Uploaded Provenance Actions
ug_address-1.0.1.tar.gz 709.9 kB Without provenance Details for ug_address-1.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ug-address 1.0.1
File Interpreter ABI Platform Actions
ug_address-1.0.1-py3-none-any.whl Python 3 none any Details for ug_address-1.0.1-py3-none-any.whl

Total release size: 1.4 MB

Release files / ug_address-1.0.1.tar.gz

Download URL ug_address-1.0.1.tar.gz
Size 709.9 kB
Tags Source
SHA-256 checksum
How to use checksums
ef02f524bf8cbdfc9db62497b6da2ebe17db1d9c9ce39fb2077908c3e6b37df9
BLAKE2b-256 checksum
How to use checksums
a43eb75603701e4f711fbdf2f81234233eff54421ca2423021016ce34c17ece0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.2

Release files / ug_address-1.0.1-py3-none-any.whl

Download URL ug_address-1.0.1-py3-none-any.whl
Size 707.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5230d9a686f7f72dc44a8baf244daf5b49496e71ad35e613ca7dec89fd4f66a3
BLAKE2b-256 checksum
How to use checksums
ca4e4bef7bac75b6112570dee1f560451084b31ffde0d451525d1bcf070fe6ab
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.2

Security for ug-address 1.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page