geographicol

Normalize Colombian addresses into one canonical, structured form. Python 3.10+, zero dependencies.

Install

pip install geographicol

Usage

from geographicol import is_valid, normalize, parse

normalize("Cra 7 # 45-12 Torre 2 Apto 501")  # "KR 7 45 12 TO 2 APTO 501"
normalize("Cra 7 # 45-12 Torre 2 Apto 501", style="dian")  # "CR 7 45 12 TO 2 AP 501"
is_valid("Calle 45")  # False: no cross street

Styles

Every style accepts codes from all three tables as input. strict=True doubles every confidence penalty.

Named streets are supported: Avenida Boyacá # 12-30 gives street_name "BOYACÁ" and the canonical string AV BOYACÁ 12 30.

ParsedAddress

parse("Cra 7 # 45-12 Torre 2 Apto 501, Bogotá")
# ParsedAddress(
#     street_type="KR", street_number=7, street_name=None, street_letter=None,
#     street_quadrant=None,
#     cross_number=45, cross_letter=None, cross_quadrant=None, plate_number=12,
#     complements=[
#         Complement(type="TORRE", code="TO", value="2"),
#         Complement(type="APARTAMENTO", code="APTO", value="501"),
#     ],
#     locality="Bogotá", department=None,
#     canonical="KR 7 45 12 TO 2 APTO 501",
#     normalized="Carrera 7 # 45-12, Torre 2, Apartamento 501",
#     confidence=1.0,
#     warnings=["LOCALITY_UNVERIFIED"],
#     raw="Cra 7 # 45-12 Torre 2 Apto 501, Bogotá",
# )

ParsedAddress is a dataclass, so dataclasses.asdict() turns it into a plain dict. parse never raises. When it can't make sense of the input, it says so through confidence (0 to 1) and machine-readable warnings instead of guessing silently. The full rules, codes and warning list are in docs/nomenclature.md.

What this library does NOT do

It normalizes the syntax of an address, offline, from the string alone. It does not:

• Geocode: no coordinates, no maps.
• Validate against real addresses: KR 999 999 99 parses fine even though it doesn't exist.
• Look up cities or neighbourhoods: locality and department are captured as written and never checked (warning LOCALITY_UNVERIFIED).
• Fix typos or fuzzy-match: Carerra is not recognized.

Those need data and infrastructure, and will be part of the geographicol API.

License

MIT