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?

**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:

// "Is this a good block for a new café?" — SF, 1 km radius

{ "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radiusMeters": 1000, "categories": ["cafe", "restaurant", "bar"] } // → per-category counts + density/km², avg rating (Google/Yelp), price mix, // an activity proxy (Yelp review volume), and Census demographics for the tract.

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

{

"mcpServers": { "geowire": { "command": "npx", "args": ["-y", "@geowirehq/mcp"] } } }

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

npx @geowirehq/cli search "Golden Gate Bridge"    # terminal search with a results table

npx @geowirehq/cli search "coffee" --near 37.7749,-122.4194 --radius 2000 # near a coordinate npx @geowirehq/cli reverse 37.8199,-122.4783 # coordinate → nearest place npx @geowirehq/cli route 37.7749,-122.4194 37.8083,-122.4156 # driving directions (no key, OSRM) npx @geowirehq/cli get google:ChIJ... # one place by reference (getPlace-capable provider) npx @geowirehq/cli # start the REST + MCP server (zero-config) npx @geowirehq/cli init # interactive setup wizard (.env + config) npx @geowirehq/cli test # check provider connections

Add --json to any command for the full response (results + provenance meta).

3. Docker — self-hosted server

docker run -p 4980:4980 geowire/geowire

then:

curl -X POST http://localhost:4980/v1/places/search \ -H 'content-type: application/json' \ -d '{"query":"coffee","near":{"latitude":37.7749,"longitude":-122.4194},"radiusMeters":2000}'

Or with docker compose up (see docker-compose.yml). API docs at /docs.

4. SDK (embedded)

import { createGeoWire } from "@geowirehq/core";

import { createNominatimProvider } from "@geowirehq/provider-nominatim";

const geo = createGeoWire({ providers: [createNominatimProvider()] }); const { results, meta } = await geo.searchPlaces({ query: "coffee", near: { latitude: 37.7749, longitude: -122.4194 }, radiusMeters: 2000, });

Full embedded-SDK guide: examples/typescript-sdk.md.

MCP tools

Every response includes both a human-readable summary and structuredContent (schema-valid JSON).

REST endpoints

Optional Bearer auth: set GEOWIRE_API_KEYS=key1,key2.

Anatomy of a response

No black box. Every response carries a meta block: which providers were used / skipped / failed (and why), dedup counts, cache status, estimated cost, and per-field sourcing — so you always know where each value came from.

{

"results": [{ "id": "gwp_CvWvRZrFtegkJPxP9CW0", "name": "Golden Gate Bridge", "location": { "latitude": 37.8199286, "longitude": -122.4782551 }, "sources": [{ "provider": "nominatim", "providerPlaceId": "way/27385590", "fields": ["name", "location", "categories", "address"] // ← what this source contributed }], "attributions": ["© OpenStreetMap contributors"] }], "meta": { "providersUsed": [{ "provider": "nominatim", "resultCount": 1, "latencyMs": 2449 }], "providersSkipped": [], // e.g. { provider: "google", reason: "MISSING_CREDENTIALS" | "QUOTA_EXCEEDED" } "providersFailed": [], // e.g. { provider: "google", reason: "TIMEOUT" } "strategy": "first-success", "cache": { "hit": false } // merging adds: "dedup": { "before": 3, "after": 1 } // paid provider: "estimatedCostUSD": 0.032 } }

After a merge, sources[].fields shows (say) the phone came from Google while the coordinates came from OSM. Walkthrough: docs/recipes.md.

Configuration (optional — everything works without it)

geowire.config.yaml:

providers:

nominatim: { enabled: true } # default ON, no key (search/geocode) osrm: { enabled: true } # default ON, no key (directions) google: { enabled: true, apiKey: ${GOOGLE_MAPS_API_KEY} } yelp: { enabled: true } # env YELP_API_KEY (US/Western business & reviews) census: { enabled: true } # env CENSUS_API_KEY (US demographics, free) kakao: { enabled: true } # env KAKAO_REST_API_KEY (KR) internal: { enabled: true, source: ./my-places.csv, priority: 100 } routing: defaultStrategy: merge # first-success | merge | cost-aware | weighted | fastest providerWeights: # for weighted: order by priority·cost·coverage priority: 0.5 cost: 0.3 coverage: 0.2 budget: perRequestMaxUSD: 0.10 # over-budget paid providers are skipped, free ones used

Keys come from the environment (${VAR}), never committed in plaintext.

Providers

Regional providers make Korea (Kakao/Naver) and China (Baidu) coverage first-class where OSM is thin and Google has gaps — Baidu returns BD-09 coordinates, which GeoWire converts to WGS84 automatically. Merge them all + your own store data into one deduped