Troubleshooting

This page lists common issues and how to resolve them quickly.

Invalid Country Or Subdivision Code

If you pass an invalid country or subdivision code, the package now raises a custom error with suggestions:

from iso3166_2 import Subdivisions

iso = Subdivisions()
iso["DE-BER"]  # raises SubdivisionNotFound with "Did you mean..."

Tips:

  • Use ISO 3166-1 alpha-2/alpha-3/numeric country codes.

  • For subdivision lookups, use valid ISO 3166-2 format (for example DE-BE).

Search Returns Too Many Results

Tune search relevance and filter down the result set:

iso.search(
    "Berlin",
    likeness_score=90,
    subdivision_type="Land",
    region="DE",
    exclude_match_score=False,
)

Tips:

  • Increase likeness_score for stricter matching.

  • Use subdivision_type, parent_code and region filters together.

Search Returns No Results

Try one or more of the following:

  • Lower likeness_score (for example from 100 to 80).

  • Enable local name search: local_other_name_search=True.

  • Remove strict filters like subdivision_type or parent_code.

Reverse Lookup (Coordinates) Returns Empty List

When using reverse_lookup, an empty list usually means no subdivision centroid is inside your search radius.

iso.reverse_lookup(52.5174, 13.3951, radius_km=75, region="DE")

Tips:

  • Increase radius_km.

  • Remove region filter if you are close to a border.

  • Verify latitude/longitude order is (lat, lng).

CLI Command Errors

Use --help with any command:

iso3166-2 --help
iso3166-2 search --help
iso3166-2 reverse --help

If you receive an import error in a local clone, run commands from the repository root or install editable mode:

pip install -e .

Typing Support In IDEs

The package ships a py.typed marker so type checkers can consume package type hints.

If your IDE still does not show hints:

  • Rebuild/reload your Python environment.

  • Ensure the interpreter points to the environment where iso3166-2 is installed.