geowire/geowire

> **Give any AI agent real-world location intelligence in 5 minutes — no API key required.**
>
> One interface for place search, directions, and area/market analysis across every map provider.
GeoWire is an open-source geo intelligence gateway that sits between AI agents and
map/place data providers (OpenStreetMap, Google, Yelp, Foursquare, US Census, your
own data) and exposes them through a single **MCP server**, **REST API**, and
**SDK**. One interface for **place search, geocoding, directions & distance
matrices, and commercial-area analysis (density, ratings, demographics)** — with
provider fallback, multi-provider merge + dedup, cost budgets, and a policy engine
that enforces each provider's caching/attribution terms.
**Published on npm — MCP · REST · CLI · SDK all functional. 10 providers, 8 operations.**
> **Honest by design:** OpenStreetMap (the zero-key default) is a great
> *geocoder* — strong on place names, addresses, and landmarks — but thin on
> category words ("coffee", "pharmacy"), ratings, and hours. For US/Western
> commercial data, add a Google, Yelp, or Foursquare key (BYOK) — GeoWire merges
> them and tells you which source every field came from. Directions run key-free
> on OpenStreetMap routing (OSRM); US demographics come from the Census (free key).
**Contents:** Why · Quickstart · MCP tools · REST · Anatomy of a response · Config · Providers · Recipes & examples · Roadmap · Architecture
Why GeoWire?
| | Direct integration | Single-provider MCP | **GeoWire** |
|---|---|---|---|
| Unified place schema | ❌ per-provider code | ❌ | ✅ |
| Provider fallback on failure | ❌ | ❌ | ✅ |
| Multi-provider merge + dedup | ❌ | ❌ | ✅ |
| Cost budgets & routing | ❌ | ❌ | ✅ |
| Works without any API key | ❌ | depends | ✅ (OSM by default) |
| Self-hosted | — | depends | ✅ |
| Your own place data as a provider | ❌ | ❌ | ✅ |
| Transparent provenance (which source, what cost) | ❌ | ❌ | ✅ (every response) |
**Not a Google replacement — it *uses* Google.** The thing no single provider can
do: merge **your own store data + Google + OSM** into one deduped record, with
per-field provenance (your name is authoritative, Google adds ratings, OSM adds
coordinates). Real run below:
More than search — location intelligence for agents
Once your agent can find places, it can reason about *areas*. One analyze_area
call turns a point + radius into a commercial-district read — category density,
competition, the rating landscape, and (in the US) demographics:
Same gateway also does **directions & distance matrices** and **travel-time
isochrones** — key-free via OSRM — so an agent can rank candidates by drive time and
answer catchment questions like *"what's within a 15-minute drive of this address?"*
See Recipes.
Quickstart
1. MCP (Claude Desktop / Cursor) — 30 seconds
Add this to your MCP client config (e.g. Claude Desktop claude_desktop_config.json):
Then ask: *"Where is the Golden Gate Bridge?"*, *"Find coffee within 2 km of
37.7749, -122.4194 (San Francisco)."*, or *"How do I drive from downtown SF to
Fisherman's Wharf?"* Works with **zero API keys** — OpenStreetMap + OSRM routing
are the defaults. Add "env": { "GOOGLE_MAPS_API_KEY": "..." } (or YELP_API_KEY)
for ratings, reviews, and hours, and "CENSUS_API_KEY" for area demographics.
See more MCP client configs.
2. CLI — one-shot search & server
Add --json to any command for the full response (results + provenance meta).
3. Docker — self-hosted server
Or with docker compose up (see docker-compose.yml). API docs at /docs.
4. SDK (embedded)
Full embedded-SDK guide: examples/typescript-sdk.md.
MCP tools
| Tool | Description |
|---|---|
| search_places | Natural-language + coordinate/region place search |
| get_place | Details by provider:providerPlaceId reference |
| geocode_address | Address → coordinates (+ normalized address) |