stapel-geo

Geohash proximity search and geocoding, no GDAL/PostGIS/spatial database: a hierarchical location tree (flat lat/lon points with an auto-encoded geohash and a stable cross-service UUID), a proximity search facade (nearby/radius/bbox) behind one swappable backend, and a geocoder proxy (forward/structured/reverse) behind a provider merge-registry, throttled, cached and spend-ledgered per call.

Part of the Stapel framework — composable Django apps that deploy as a monolith or as microservices without changing module code.

Install

pip install stapel-geo

At a glance

Documentation

Flows: English · Errors: English · Русский · OpenAPI · capabilities.json · llms.txt (for agents)

What this is

• Location tree — hierarchical reference places (django-treenode): flat lat/lon points with an auto-encoded, indexed geohash and a stable cross-service UUID. No polygons.
• Proximity search facade — nearby (top-K) / radius (membership) / bbox (viewport, antimeridian-aware) behind one swappable backend key. The default runs on your primary database via geohash prefix expansion (correct across the equator, the antimeridian and the poles, ranked by exact haversine); a Redis GEOSEARCH side-index backend ships for the hot set; Elasticsearch/Solr are named stubs.
• Geocoder proxy — forward / structured / reverse geocoding behind a provider merge-registry (photon self-hosted default, nominatim keyless dev/fallback, google/yandex key-gated stubs), throttled, cached (30-day TTL) and spend-ledgered per call.
• comm surface — geo.nearby / geo.radius / geo.bbox / geo.geohash_encode / geo.resolve: consumers (listings, calendar) query geo by name, never importing it.

Quick start

pip install "stapel-geo[redis]"  # + the Redis search backend

INSTALLED_APPS = [
    # ...
    "stapel_geo",
]

# urls.py — the canonical versioned surface /geo/api/v1/...
path("geo/", include("stapel_geo.urls"))
# ... or mount only the geocoder proxy:
path("geo/api/v1/geocoding/", include("stapel_geo.geocoding.urls"))

Plain manage.py migrate — any Django database backend works.

HTTP surface (/geo/api/v1/)

Settings (STAPEL_GEO)

comm Functions

from stapel_core.comm import call

call("geo.nearby", {"lat": 49.61, "lon": 6.13, "limit": 5})
call("geo.radius", {"lat": 49.61, "lon": 6.13, "radius_km": 25})
call("geo.bbox", {"min_lat": 49, "min_lon": 5, "max_lat": 50, "max_lon": 7})
call("geo.geohash_encode", {"lat": 49.61, "lon": 6.13})   # -> {"geohash": ...}
call("geo.resolve", {"uuid": "<location-uuid>"})

min_lon > max_lon in geo.bbox means the box crosses the antimeridian.

Swapping the search backend

STAPEL_GEO = {"SEARCH_BACKEND": "stapel_geo.search.redis.RedisGeoSearchBackend"}

The Redis backend is a side index: the primary DB stays the source of truth; post_save/post_delete keep it in sync and RedisGeoSearchBackend().rebuild() re-indexes from scratch. Implement stapel_geo.search.base.GeoSearchBackend (three verbs) to bring your own engine — see MODULE.md.

Extension points

See MODULE.md — the agent-facing map of every fork-free seam, and CHANGELOG.md — including what 0.3.0 removed and why.

License

MIT — see LICENSE.

_{This page is assembled by stapel-readme from docs/readme.md plus the contract artifacts in docs/. Edit the prose in docs/readme.md; the badges, facts and links above and below it are generated — do not hand-edit README.md.}