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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.