Skip to content

hyperion.adapters.geocoder.static

hyperion.adapters.geocoder.static

Static :class:~hyperion.ports.geocoder.Geocoder adapter (lite).

A dependency-free, offline geocoder backed by in-memory lookup tables. Intended for tests and offline scenarios where the Google Maps API is unavailable. Its error messages mirror :class:~hyperion.adapters.geocoder.google.GoogleMaps so the two are substitutable behind the :class:~hyperion.ports.geocoder.Geocoder port.

StaticGeocoder 

StaticGeocoder(*, locations=None, named_locations=None, altitudes=None)

A geocoder that resolves from fixed lookup tables.

Parameters:

Name Type Description Default
locations Mapping[str, Location] | None

Maps an address string to its :class:Location.

 None
named_locations Mapping[tuple[float, float], NamedLocation] | None

Maps a (latitude, longitude) tuple to a :class:NamedLocation for reverse geocoding.

 None
altitudes Mapping[tuple[float, float], float] | None

Maps a (latitude, longitude) tuple to an altitude in meters above sea level.

 None
Source code in hyperion/adapters/geocoder/static.py 
28
29
30
31
32
33
34
35
36
37
def __init__(
    self,
    *,
    locations: Mapping[str, Location] | None = None,
    named_locations: Mapping[tuple[float, float], NamedLocation] | None = None,
    altitudes: Mapping[tuple[float, float], float] | None = None,
) -> None:
    self._locations: dict[str, Location] = dict(locations or {})
    self._named_locations: dict[tuple[float, float], NamedLocation] = dict(named_locations or {})
    self._altitudes: dict[tuple[float, float], float] = dict(altitudes or {})

geocode 

geocode(address)

Resolve address from the static table.

Source code in hyperion/adapters/geocoder/static.py 
39
40
41
42
43
def geocode(self, address: str) -> Location:
    """Resolve ``address`` from the static table."""
    if (location := self._locations.get(address)) is None:
        raise ValueError(f"Could not geocode address: {address!r}.")
    return location

reverse_geocode 

reverse_geocode(location, language=None)

Resolve location coordinates from the static table.

language is accepted for :class:~hyperion.ports.geocoder.Geocoder compatibility and ignored (static data is language-agnostic).

Source code in hyperion/adapters/geocoder/static.py 
45
46
47
48
49
50
51
52
53
54
def reverse_geocode(self, location: Location, language: str | None = None) -> NamedLocation:
    """Resolve ``location`` coordinates from the static table.

    ``language`` is accepted for :class:`~hyperion.ports.geocoder.Geocoder`
    compatibility and ignored (static data is language-agnostic).
    """
    key = (location.latitude, location.longitude)
    if (named := self._named_locations.get(key)) is None:
        raise ValueError(f"Could not reverse-geocode provided location - no results. {location!r}")
    return named

get_altitude 

get_altitude(location)

Return the altitude of location from the static table.

Source code in hyperion/adapters/geocoder/static.py 
56
57
58
59
60
61
def get_altitude(self, location: Location) -> float:
    """Return the altitude of ``location`` from the static table."""
    key = (location.latitude, location.longitude)
    if (altitude := self._altitudes.get(key)) is None:
        raise ValueError(f"No elevation data found for location {location!r}.")
    return altitude