Is there any way to implement Local Reverse Geocoding outside of US?

[keviinmoo]

Hi there, is there currently anyway to use Local Reverse Geocoding in Australia as I don't prefer not to use Google Geocoding API.

Thank you for your time!

[stephanlensky]

Hey! I don't have any plans to implement this at the moment, but I'd be happy to accept a contribution. Unfortunately I'm a bit busy with work these days and don't have quite as much time to add new features myself.

Let me know if you'd be interested and I can share some information about what I'd expect the feature to look like.

[AndriyYer]

If the offer is still open, I’d love to contribute.

Was hoping to make this work for Canada 😃

[jihed123]

Hi @AndriyYer , i made it work and tested locally for Canada (the code is from AI)

and download the relevent file obviously and the cities1000 file works fine

change in hyacinth\hyacinth\util\geo.py:

the : GADM_USA_GPKG_PATH = Path("geography/gadm36_USA.gpkg")
to :  GADM_CAN_GPKG_PATH = Path("geography/gadm41_CAN.gpkg") 

and this class

class LocalReverseGeocoder:
    """
    Implementation of a reverse geocoder using freely available geospatial data.
    The "reverse" method accepts a lat/long coordinate and attempts to return a 3-pair of a country,
    primary administrative zone (province/territory), and city. Currently supports locations within Canada.
    """
    class ReverseGeocodeResult(NamedTuple):
        country: str | None
        primary_administrative_zone: str | None
        city: str | None

    def __init__(self) -> None:
        _logger.info("Loading Canadian geospatial datasets...")
        self.ensure_geospatial_datasets_downloaded()
        
        # Use the ADM_ADM_1 layer for provinces/territories
        self.gadm_primary_subdivision_datasets: dict[str, GeoDataFrame] = {
            "CAN": gpd.read_file(GADM_CAN_GPKG_PATH, layer='ADM_ADM_1')
        }
        
        self.geonames_cities_dataset = pd.read_csv(
            GEONAMES_CITIES_PATH,
            sep="\t",
            usecols=[1, 4, 5, 8, 10],
            names=["name", "latitude", "longitude", "country", "admin1"],
        )
        
        _logger.info("Creating indexes...")
        # Map Canadian province/territory codes to match GEONAMES format
        self.admin_code_mapping = {
            "Alberta": "01",
            "British Columbia": "02",
            "Manitoba": "03",
            "New Brunswick": "04",
            "Newfoundland and Labrador": "05",
            "Nova Scotia": "07",
            "Ontario": "08",
            "Prince Edward Island": "09",
            "Québec": "10",  # Note the accent
            "Saskatchewan": "11",
            "Northwest Territories": "13",
            "Yukon": "12",
            "Nunavut": "14"
        }
        
        # Get the actual column names from the dataset
        gadm_columns = self.gadm_primary_subdivision_datasets["CAN"].columns
        name_column = next(col for col in gadm_columns if 'NAME_1' in col)
        id_column = next(col for col in gadm_columns if 'GID_1' in col)
        
        # Adjust column names based on what's actually in the dataset
        self.primary_subdivisions_by_country: dict[str, pd.DataFrame] = {
            country: gadm_dataset.rename(columns={name_column: "name", id_column: "hasc"})
            for country, gadm_dataset in self.gadm_primary_subdivision_datasets.items()
        }
        
        self.cities_by_hasc: dict[str, pd.DataFrame] = {}
        for country in self.primary_subdivisions_by_country:
            for _, subdivision in self.primary_subdivisions_by_country[country].iterrows():
                # Clean up the province name to match our mapping
                province_name = subdivision["name"].replace("Province of ", "").strip()
                admin_code = self.admin_code_mapping.get(province_name)
                if admin_code:
                    self.cities_by_hasc[subdivision["hasc"]] = self.geonames_cities_dataset[
                        (self.geonames_cities_dataset["country"] == country)
                        & (self.geonames_cities_dataset["admin1"] == admin_code)
                    ]
        
        self.city_index_by_hasc = {
            hasc: KDTree(self.cities_by_hasc[hasc][["latitude", "longitude"]])
            for hasc in self.cities_by_hasc
            if not self.cities_by_hasc[hasc].empty
        }
        _logger.info("Done!")

    def ensure_geospatial_datasets_downloaded(self) -> None:
        if not GADM_CAN_GPKG_PATH.exists() or not GEONAMES_CITIES_PATH.exists():
            raise FileNotFoundError(
                "Could not find local geospatial data. Please download gadm41_CAN.gpkg and"
                " cities1000.txt to use local geocoding."
            )

    def reverse(self, geotag: tuple[float, float]) -> ReverseGeocodeResult:
        geotag_df = gpd.points_from_xy(y=(geotag[0],), x=(geotag[1],))[0]
        country = "CAN"
        gadm_dataset = self.gadm_primary_subdivision_datasets[country]
        subdivision_index = gadm_dataset.sindex.query(geotag_df, predicate="within")
        
        if subdivision_index.size > 0:
            # Use the actual column names we found
            name_column = next(col for col in gadm_dataset.columns if 'NAME_1' in col)
            id_column = next(col for col in gadm_dataset.columns if 'GID_1' in col)
            
            province = gadm_dataset.at[subdivision_index[0], name_column]
            # Clean up the province name
            if isinstance(province, str):
                province = province.replace("Province of ", "").strip()
            
            hasc = gadm_dataset.at[subdivision_index[0], id_column]
        else:
            province = None
            hasc = None
            
        nearest_city = None
        if hasc is not None and hasc in self.city_index_by_hasc:
            _, nn_index = self.city_index_by_hasc[hasc].query([geotag])
            nearest_city = self.cities_by_hasc[hasc].iloc[nn_index[0]]["name"]
            
        return LocalReverseGeocoder.ReverseGeocodeResult(
            country=country,
            primary_administrative_zone=province,
            city=nearest_city,
        )

If the offer is still open, I’d love to contribute.

Was hoping to make this work for Canada 😃