GeoGlobal — Geocoding, POI Discovery & Africa Routing

Status: LIVE on .106 (DataAcuity Maps server) as of 2026-05-28 Owner: Tinashe Bhengu Network: data-warehouse_data_stack (all .106 containers can reach by service name)

GeoGlobal is the global geo intelligence layer for The Geek Network. It backs:

• Place lookup — find any of 13.4M populated places worldwide by exact name, fuzzy text, or coordinates
• POI discovery — surface 3.5M+ points of interest (museums, tourism, historic sites, hotels, nature, archaeology, religious sites) ranked by interest score, distance, and theme
• Africa-wide turn-by-turn routing — driving / pedestrian / bicycle / motorcycle / truck across 38,822 tiles built from the latest Africa OpenStreetMap extract (May 2026)
• Quest composition — synthesis tool that finds the most interesting POIs near a location and routes through them in optimal order (round-trip)

Why this exists

Both TagMe and Takemehome.co.za already call maps.dataacuity.co.za for geocoding, reverse-geocoding, and directions — but most of the geo plumbing is either stubbed or unwired in the UI. GeoGlobal adds the missing capabilities (turn-by-turn routing, ranked POI discovery, multi-stop quest planning, fuzzy place search) and surfaces them as both:

• A REST API (proxied through maps_api on .106:5020) — the easiest way for the .NET/Blazor apps to consume
• An MCP server (geo_mcp on .106:5026) — for Butler (B! AI) and any other AI agent that should reason over geographic context

The two surfaces share the same backing data (geo_db PostgreSQL/PostGIS + valhalla routing container), so behavior is identical regardless of which entry point you use.

What's in this folder

Capabilities at a glance

Geographic coverage

• Place data and POIs: truly global. African coverage is best (this is what we built first), with very strong fill for Europe, North America, parts of Asia, and reasonable fill for the rest.
• Routing: Africa only for now. Calls outside the bounding box return a 400 with "No suitable edges near location". Future phases may add Europe, MENA, etc. as separate Valhalla containers or a hosted-routing fallback.

If a feature needs global routing today, point the call at the public Valhalla mirror or OpenRouteService API — but be aware of rate limits and SLAs.

Quick start — the smallest useful call

# Find Cape Town and the 5 most interesting things within 10 km
curl -s "http://197.97.200.106:5026/sse" # ... see GeoGlobal_API_Reference.md for the MCP/REST shapes

// In a TagMe or Takemehome service:
var client = httpClientFactory.CreateClient("GeoGlobal");
var result = await client.GetFromJsonAsync<List<Place>>(
    "/api/v2/geocode?query=Cape%20Town&include_interesting=true&max_interesting=5");

See GeoGlobal_API_Reference.md for every endpoint and GeoGlobal_Integration_Guide.md for end-to-end app patterns.

Performance notes

• Geocoding / reverse / search: typically <50 ms (indexed PostGIS query)
• POI nearby (within_km≤20, limit≤10): typically <150 ms
• Single-leg Valhalla route within Africa: typically 100–800 ms depending on distance
• discover_quest (POI search + optimized_route): typically 500 ms – 3 s for 5 POIs

These figures assume the caller is on .106 or .118 (in-cluster). External callers add WAN latency.

Versioning

• MCP server: v0.5 (2026-05-28 — adds interesting_nearby as a standalone tool plus three new tools: isochrone, distance_matrix, snap_to_road. Nine tools total)
• Prior: v0.4 (geocode + reverse + search + route + discover_quest + interesting_nearby enrichment)
• Valhalla: v3.5.1 with gis-ops/docker-valhalla wrapper
• GeoNames data snapshot: 2026-05-20
• OSM Africa extract: 2026-05-27 (openstreetmap.fr mirror)
• Wikipedia geo-tagged articles: not yet seeded (pending future work)

Breaking changes will bump the major version of the REST /api/v2/ namespace. The MCP tool surface follows MCP's standard semver discipline (additive changes within the same protocol version).

Where to go next

• You're building app features → GeoGlobal_Integration_Guide.md
• You're writing backend that calls the API directly → GeoGlobal_API_Reference.md
• You're an AI agent or B! Butler skill builder → GeoGlobal_API_Reference.md (MCP Tools section)
• You're operating the service / on call → GeoGlobal_Deployment.md
• You're querying the database directly → GeoGlobal_Data_Schema.md

Open items / not yet built

1. Wikipedia geo-tagged article seeding — would add ~1M more POIs with richer descriptions
2. EU country POI gap fill — current coverage outside Africa is biased toward dense OSM regions
3. Routing outside Africa — needs either more disk/RAM on this server, a second box, or a hosted API
4. mcpize.com public listing — once the MCP is stable for a couple weeks

Contact

• For app integration questions: open an issue or message in the team channel
• For ops / outage: check GeoGlobal_Deployment.md runbook first, then escalate