hyperion.ports.geocoder

hyperion.ports.geocoder

Port: geocoder abstraction.

Geocoder is the dependency-inversion seam between callers that need address <-> coordinate resolution and a concrete backend (Google Maps, or a static offline lookup for tests). It is a runtime_checkable :class:typing.Protocol -- adapters satisfy it structurally, no forced inheritance (see docs/ddd-refactor-plan.md F4 / Step 7).

The port references only the pure-domain :class:~hyperion.domain.geo.Location and :class:~hyperion.domain.geo.NamedLocation value objects, so importing it stays lite (no googlemaps, no boto3).

Contract:

• geocode raises :class:ValueError when the address cannot be resolved.
• reverse_geocode raises :class:ValueError when the location has no address.
• get_altitude raises :class:ValueError when no elevation data exists.

Geocoder

Bases: Protocol

Abstraction over geocoding backends.

geocode

geocode(address)

Resolve address to a :class:Location.

Raises:

Type	Description
ValueError	if the address cannot be geocoded.

Source code in hyperion/ports/geocoder.py

def geocode(self, address: str) -> Location:
    """Resolve ``address`` to a :class:`Location`.

    Raises:
        ValueError: if the address cannot be geocoded.
    """
    ...

reverse_geocode

reverse_geocode(location, language=None)

Resolve location coordinates to a named address.

Parameters:

Name	Type	Description	Default
location	Location	The coordinates to reverse-geocode.	required
language	str | None	Optional language for the returned components.	None

Raises:

Type	Description
ValueError	if the location cannot be reverse-geocoded.

Source code in hyperion/ports/geocoder.py

def reverse_geocode(self, location: Location, language: str | None = None) -> NamedLocation:
    """Resolve ``location`` coordinates to a named address.

    Args:
        location: The coordinates to reverse-geocode.
        language: Optional language for the returned components.

    Raises:
        ValueError: if the location cannot be reverse-geocoded.
    """
    ...

get_altitude

get_altitude(location)

Return the altitude of location in meters above sea level.

Raises:

Type	Description
ValueError	if no elevation data is available.

Source code in hyperion/ports/geocoder.py

def get_altitude(self, location: Location) -> float:
    """Return the altitude of ``location`` in meters above sea level.

    Raises:
        ValueError: if no elevation data is available.
    """
    ...