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 / resolve 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. Forward search takes the map's own narrowings: a hard bbox and a soft viewport bias.

• The location picker's server half — because a place is chosen by a human, not typed as two decimals:

  • every feature carries properties.formatted, the display line, in the country's own postal order;
  • geocoding/resolve?lat=&lon= turns one coordinate pair into a confirmable place (label, components, geohash, alternatives) in one round trip — the whole server side of "detect my position" and of a dropped map pin;
  • map/config (public) hands the frontend its tile template, the attribution the ODbL licence obliges the map to display, the zoom envelope, the operating bbox and the debounce discipline.

  The React pair builds against docs/frontend-contract.md.

• comm surface — geo.nearby / geo.radius / geo.bbox / geo.geohash_encode / geo.resolve / geo.geocode / geo.reverse_geocode / geo.map_config: 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)

Sending lang? Send default, or nothing. PHOTON_LANGUAGES is what the index on disk carries, and Photon refuses anything else with HTTP 400 rather than degrading. Requests for an unindexed language clamp to PHOTON_LANGUAGE_FALLBACK ("default" = the local name on the map, which for a single-country product is already the right language), and the response's lang field tells you what was really used. To index another language for real, build the Photon database from the JSON dump with photon.jar import -languages …; listing it here without rebuilding turns every request into a 502. manage.py check says all of this (stapel_geo.W005/W006).

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.}