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, plus a coarse IP-geolocation verb behind its own provider registry, so a map opens on a real place before the browser's position prompt is answered.

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.

• Where to open the map before anyone is asked — ip (public) places the visitor from the address their request arrived on, so a picker opens on a city while the browser's geolocation prompt is still unanswered, or after it was refused. Offline maxmind database or a single configured static point, behind the same kind of provider registry as the geocoder, with the map's own default centre as the floor under both. Coarse on purpose: city-at-best, wrong on a VPN or a carrier NAT, and source/precision/ip_resolved come back with the point so a UI never presents a guess as the user's address.

• 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
pip install "stapel-geo[ipgeo]"  # + the offline MaxMind reader for `ip`

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

Behind a proxy? Set IP_TRUSTED_PROXY_DEPTH to the number of hops you actually own (1 behind a single nginx). Leave it at 0 there and every visitor geolocates to your proxy; raise it past what you own and a caller picks their own IP by typing an X-Forwarded-For header. The chain X-Forwarded-For ++ [REMOTE_ADDR] is counted from the right, which is what keeps a forged prefix inert. manage.py check says this too (stapel_geo.W008/W009/W010).

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

Swappable from settings, no fork: the search backend (SEARCH_BACKEND), the geocoder registry (GEOCODERS / GEOCODER), the geocode cache (GEOCODE_CACHE_POLICY), the display line (ADDRESS_FORMATTER), the IP locator registry (IP_LOCATORS / IP_LOCATOR — same merge semantics as the geocoders'), and which address a request came from (IP_CLIENT_IP_RESOLVER, the proxy-trust decision as one function).

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