Getting Started

What is etter?

etter (/ˈɛtɐ/, Swiss German) — the boundary marking the edge of a village or commune.

etter transforms natural language location queries into structured geographic filters. It uses LLMs to understand multilingual queries and extract spatial relationships, returning typed Pydantic models your application can act on.

Key principle: etter has one responsibility — extract the geographic filter. It does not identify features, filter attributes, or execute searches.

User query: "Hiking with children north of Lausanne"
                      ↓
Parent app  →  extracts: Activity="Hiking", Audience="children"
                      ↓
etter       →  parses:   relation="north_of", location="Lausanne"
                      ↓
Parent app  →  queries:  WHERE activity='hiking' AND ST_Intersects(location, sector)

Installation

git clone https://github.com/geoblocks/etter.git
cd etter
uv sync --extra dev

With PostGIS datasource support:

uv sync --extra postgis

Quick Start

from langchain_openai import ChatOpenAI
from etter import GeoFilterParser
import os

llm = ChatOpenAI(model="gpt-4o", temperature=0, api_key=os.getenv("OPENAI_API_KEY"))

parser = GeoFilterParser(llm=llm)
result = parser.parse("north of Lausanne")

print(result.spatial_relation.relation)       # "north_of"
print(result.reference_location.name)         # "Lausanne"
print(result.buffer_config.distance_m)        # 10000
print(result.confidence_breakdown.overall)    # 0.95

See GeoFilterParser for the full constructor signature and options.

Confidence and Strict Mode

By default etter warns on low confidence. Use strict_mode=True to raise instead:

# Lenient: emits LowConfidenceWarning below threshold
parser = GeoFilterParser(llm=llm, confidence_threshold=0.6, strict_mode=False)

# Strict: raises LowConfidenceError below threshold
parser = GeoFilterParser(llm=llm, confidence_threshold=0.8, strict_mode=True)

See GeoQuery for a full description of all output fields.

Streaming

For responsive UIs, use parse_stream to receive reasoning events in real time:

async for event in parser.parse_stream("5km north of Lausanne"):
    if event["type"] == "reasoning":
        print(event["content"])           # e.g. "Identified relation: north_of"
    elif event["type"] == "data-response":
        geo_query = event["content"]      # raw dict (GeoQuery fields)
    elif event["type"] == "error":
        raise RuntimeError(event["content"])

See parse_stream for all event types.

Custom Spatial Relations

Register additional relations beyond the 15 built-ins:

from etter import SpatialRelationConfig, RelationConfig

config = SpatialRelationConfig()
config.register_relation(RelationConfig(
    name="close_to",
    category="buffer",
    description="Very close proximity",
    default_distance_m=1000,
    buffer_from="center",
))

parser = GeoFilterParser(llm=llm, spatial_config=config)

See Spatial Relations for the full list of built-ins and configuration options.