etter /ˈɛtɐ/ n. (Swiss German) — the boundary or enclosure marking the edge of a village or commune; a natural demarcation between settled and unsettled land.
Natural language geographic query parsing using LLMs.
etter transforms natural language location queries into structured geographic filters that can be used by search engines and spatial databases. It uses Large Language Models (LLMs) to understand multilingual queries and extract spatial relationships.
Key Principle: etter's sole purpose is to extract the geographic filter from user queries. It does NOT handle feature/activity identification or search execution.
The development of this library is sponsored by Camptocamp.
- Geographic Filters Only: Extracts spatial relationships from queries, ignoring non-geographic content
- Multilingual Support: Parse queries in English, German, French, Italian, and more
- Rich Spatial Relations: Support for containment, buffer, and directional queries
- Structured Output: Pydantic models with full type safety
- Streaming Support: Real-time feedback with reasoning transparency for responsive UIs
- Flexible Configuration: Customizable spatial relations and confidence thresholds
- LLM Provider Agnostic: Works with OpenAI, Anthropic, or local models
✅ etter extracts:
- Spatial relations: "north of", "in", "near", etc.
- Reference locations: "Lausanne", "Lake Geneva", etc.
- Distance parameters: "within 5km", "around 2 miles", etc.
❌ etter does NOT handle:
- Feature/activity identification: "hiking", "restaurants", "hotels"
- Attribute filtering: "with children", "vegetarian", "4-star"
- Search execution or database queries
Integration Pattern: Parent application handles feature/activity filtering and combines it with etter's geographic filter for complete search functionality.
This project uses uv for dependency management.
# Install dependencies
uv sync
# Or with development dependencies
uv sync --extra dev
An interactive REPL is available for testing queries interactively:
Set your OpenAI API key before running:
export OPENAI_API_KEY='sk-...'
uv run python repl.py
A FastAPI demo server is available that combines query parsing with geographic resolution using SwissNames3D data.
Setup:
Set OPENAI_API_KEY in your .env file:
echo "OPENAI_API_KEY=sk-..." > .env
Running the server:
uv run uvicorn demo.main:app --port 8000 --reload
The API will be available at http://localhost:8000.
Making a query:
# Standard endpoint (returns complete result)
curl -X POST http://localhost:8000/api/query \
-H "Content-Type: application/json" \
-d '{"query": "north of Lausanne"}'
# Streaming endpoint (returns Server-Sent Events)
curl -X POST http://localhost:8000/api/query/stream \
-H "Content-Type: application/json" \
-d '{"query": "north of Lausanne"}' \
--no-buffer
Response: A GeoJSON FeatureCollection containing the parsed geographic query, spatial relation, and computed search areas.
The web UI at http://localhost:8000 includes a toggle to enable streaming mode with real-time reasoning display.
from langchain_openai import ChatOpenAI
from etter import GeoFilterParser
import os
# Initialize LLM
llm = ChatOpenAI(
model="gpt-4o",
temperature=0,
api_key=os.getenv("OPENAI_API_KEY")
)
# Initialize parser
parser = GeoFilterParser(
llm=llm,
confidence_threshold=0.6,
strict_mode=False
)
# Strict mode - raises error on low confidence
parser = GeoFilterParser(
llm=llm,
confidence_threshold=0.8,
strict_mode=True
)
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(spatial_config=config)
Main class for parsing queries.
Methods:
parse(query: str) -> GeoQuery: Parse a single queryparse_stream(query: str) -> AsyncGenerator[dict]: Parse with streaming eventsparse_batch(queries: List[str]) -> List[GeoQuery]: Parse multiple queriesget_available_relations(category: Optional[str]) -> List[str]: List available relationsdescribe_relation(name: str) -> str: Get relation description
Structured output model representing the parsed geographic filter.
Attributes:
query_type: Type of query (simple, compound, split, boolean)spatial_relation: Spatial relationship (e.g., "north_of", "in", "near")reference_location: Reference location (e.g., "Lausanne")buffer_config: Buffer parameters (optional)confidence_breakdown: Confidence scoresoriginal_query: Original input text
Note: etter is fully implemented with three integrated layers: parsing, geographic resolution via datasources, and spatial operations. The demo API shows a complete end-to-end workflow that resolves locations and computes search areas.
in: Exact boundary matching
near: Proximity with context-aware distance (default 5km, LLM infers based on activity, feature scale, and intent)on_shores_of: 1km ring buffer (excludes water body)along: 500m buffer for linear featuresin_the_heart_of: Erosion for central areas (default -500m, LLM infers based on area size)
- Cardinal:
north_of,south_of,east_of,west_of: 10km sector (90° each) - Diagonal:
northeast_of,southeast_of,southwest_of,northwest_of: 10km sector (90° each)
from etter import ParsingError, UnknownRelationError, LowConfidenceError
try:
result = parser.parse("some query")
except ParsingError as e:
print(f"Failed to parse: {e}")
print(f"Raw LLM response: {e.raw_response}")
except UnknownRelationError as e:
print(f"Unknown relation: {e.relation_name}")
except LowConfidenceError as e:
print(f"Low confidence: {e.confidence}")
print(f"Reasoning: {e.reasoning}")
Here are some good example queries to try with the demo application:
walk in the Gros-de-Vaudon the shores of the lac Moratnear Lausannesouth west of Lausanne5km north of Lausannewalking distance from Zurich main railway station15 min biking from Zurich main railway stationalong l'Orbe2km right bank of the Rhône
See ARCHITECTURE.md for detailed system design.
# Install dev dependencies
uv sync --extra dev
# Run tests
uv run pytest
# Format code
uv run ruff format
# Linting
uv run ruff check
# Type checking
uv run ty check