geowire

GeoWire

5 分钟内，让任何 AI Agent 都具备真实世界的位置情报能力——无需 API 密钥。

一个接口，覆盖所有地图服务提供商的地点搜索、路线规划和区域／市场分析。

GeoWire 是一个开源地理情报网关，位于 AI Agent 与地图／地点数据服务提供商（OpenStreetMap、Google、Yelp、Foursquare、US Census 以及你自己的数据）之间，通过单一的 MCP 服务、REST API 和 SDK 提供这些数据。一个接口即可完成 地点搜索、地理编码、路线规划与距离矩阵，以及商业区域分析（密度、评分、人口统计数据）——并支持服务提供商故障回退、多服务提供商合并与去重、成本预算，以及用于强制遵守各服务提供商缓存／署名条款的策略引擎。

已发布到 npm——MCP · REST · CLI · SDK 均可正常使用。10 个服务提供商，8 种操作。

**以诚为本：**OpenStreetMap（默认零密钥）是很好的地理编码器——擅长处理地点名称、地址和地标——但在类别词语（“咖啡”“药店”）、评分和营业时间方面数据较少。对于美国／西方商业数据，可添加 Google、Yelp 或 Foursquare 密钥（BYOK）；GeoWire 会合并数据，并告知你每个字段的来源。路线规划可通过 OpenStreetMap 路由（OSRM）免费使用且无需密钥；美国人口统计数据来自 Census（免费密钥）。

目录：缘由 · 快速开始 · MCP 工具 · REST · 响应解析 · 配置 · 服务提供商 · 配方与示例 · 路线图 · 架构

为什么选择 GeoWire？

	直接集成	单一服务提供商 MCP	GeoWire
统一的地点架构	❌ 每个服务提供商都要编写代码	❌	✅
故障时切换服务提供商	❌	❌	✅
多服务提供商合并与去重	❌	❌	✅
成本预算与路由	❌	❌	✅
无需任何 API 密钥即可使用	❌	取决于具体情况	✅（默认使用 OSM）
可自托管	—	取决于具体情况	✅
将你自己的地点数据用作服务提供商	❌	❌	✅
来源透明（来源是什么、成本是多少）	❌	❌	✅（每个响应均包含）

它不是 Google 的替代品，而是使用 Google。它能做到单个服务提供商都做不到的事：将你自己的门店数据 + Google + OSM合并为一条去重记录，并标明每个字段的来源（你的名称具有权威性，Google 提供评分，OSM 提供坐标）。实际运行效果如下：

不止于搜索——为 Agent 提供位置情报

Agent 找到地点后，还能分析区域。一次 analyze_area 调用即可根据一个地点和半径生成商业区分析——包括类别密度、竞争情况、评分分布，以及（在美国）人口统计数据：

// "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.

同一个网关还支持路线规划与距离矩阵以及行程时间等时圈——通过 OSRM 使用且无需密钥，因此 Agent 可以根据驾车时间对候选地点排序，并回答“从这个地址开车 15 分钟以内能到哪里？”之类的覆盖范围问题。参见配方。

快速开始

1. MCP（Claude Desktop / Cursor）——30 秒

将以下内容添加到你的 MCP 客户端配置中（例如 Claude Desktop 的 claude_desktop_config.json）：

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

然后提问：“金门大桥在哪里？”、“在旧金山坐标 37.7749, -122.4194 的 2 公里范围内找咖啡店。”或“从旧金山市中心怎么开车去渔人码头？”无需任何 API 密钥即可使用——默认采用 OpenStreetMap + OSRM 路由。添加 "env": { "GOOGLE_MAPS_API_KEY": "..." }（或 "YELP_API_KEY"）即可获取评分、评论和营业时间；添加 "CENSUS_API_KEY" 即可获取区域人口统计数据。参见更多 MCP 客户端配置。

2. CLI — 一次性搜索和服务

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

在任何命令中添加 --json，即可获取完整响应（结果 + 来源信息 meta）。

3. Docker — 可自托管服务

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

也可以运行 docker compose up（参见 docker-compose.yml）。API 文档位于 /docs。

4. SDK（嵌入式）

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,
});

完整的嵌入式 SDK 指南：examples/typescript-sdk.md。

MCP 工具

工具	描述
search_places	使用自然语言以及坐标/区域搜索地点
get_place	根据 provider:providerPlaceId 引用获取详情
geocode_address	地址 → 坐标（+ 标准化地址）
reverse_geocode	坐标 → 最近的地址
get_directions	获取途经点之间的路线（距离、时间、路段）——无需密钥（OSRM）
distance_matrix	N×M 出行距离/时间——按驾车时间对候选项排序——无需密钥
analyze_area	商业区域分析：类别密度、竞争情况、评分分布、人口统计信息
get_isochrone	出行时间可达范围多边形（“驾车 15 分钟内可到达的地点”）——无需密钥（OSRM）
get_demographics	坐标所在区域的人口/年龄/收入信息（US Census，免费密钥）
list_geo_providers	活跃的提供方、功能和状态（Agent 自我感知）

每个响应都包含易读的摘要和 structuredContent （符合 schema 的 JSON）。

REST 端点

方法	路径
POST	/v1/places/search	搜索
GET	/v1/places/{ref}	地点详情（provider:id）
GET	/v1/geocode?address=	地理编码
GET	/v1/reverse-geocode?lat=&lon=	逆地理编码
POST	/v1/directions	途经点之间的路线（无需密钥）
POST	/v1/distance-matrix	N×M 出行距离/时间矩阵（无需密钥）
POST	/v1/analyze-area	商业区域分析（密度、竞争情况、评分、人口统计信息）
POST	/v1/isochrone	出行时间可达范围多边形（无需密钥）
GET	/v1/demographics?lat=&lon=	区域人口统计信息（US Census，免费密钥）
GET	/v1/providers	列出提供方
GET	/v1/health	健康检查
GET	/metrics	Prometheus 指标
GET	/docs	Swagger UI（OpenAPI 3.1）
POST	/mcp	通过 Streamable HTTP 使用 MCP

可选 Bearer 身份验证：设置 GEOWIRE_API_KEYS=key1,key2。

响应解析

没有黑箱。每个响应都包含一个 meta 块，说明哪些提供方已使用/已跳过/失败（以及原因）、去重计数、缓存状态、预估成本和各字段的来源，让你始终清楚每个值的来源。

{
  "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
  }
}

合并后，sources[].fields 会显示（例如）电话号码来自 Google，而坐标来自 OSM。操作演示：docs/recipes.md。

配置（可选——不配置也能正常运行）

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

密钥从环境变量（${VAR}）读取，绝不会以明文形式提交。

提供方

提供方	需要密钥？	功能
@geowirehq/provider-nominatim（OpenStreetMap）	无	search、geocode、reverseGeocode
@geowirehq/provider-osrm（OpenStreetMap routing）	无	route、distanceMatrix
@geowirehq/provider-google（Maps Platform）	自带密钥（BYOK）	search、geocode、reverseGeocode、getPlace、route、distanceMatrix
@geowirehq/provider-kakao（카카오맵，KR）	自带密钥 KAKAO_REST_API_KEY	search、geocode、reverseGeocode
@geowirehq/provider-naver（네이버 지역검색，KR）	自带密钥 NAVER_CLIENT_ID+NAVER_CLIENT_SECRET	search、geocode
@geowirehq/provider-baidu（百度地图，CN）	自带密钥 BAIDU_MAP_AK	search、geocode、reverseGeocode
@geowirehq/provider-foursquare（全球 POI）	自带密钥 FOURSQUARE_API_KEY	search、getPlace
@geowirehq/provider-yelp（美国／西方商业信息、评分和评论）	自带密钥 YELP_API_KEY	search、getPlace
@geowirehq/provider-census（美国人口统计数据）	自带密钥 CENSUS_API_KEY（免费）	demographics
@geowirehq/provider-internal（你的 CSV）	无	search

在 OSM 数据稀疏、Google 覆盖不足的地区，区域提供方让韩国（Kakao/Naver）和中国（Baidu）的覆盖成为一等能力。Baidu 返回 BD-09 坐标，GeoWire 会自动将其转换为 WGS84。将这些数据与您自己的商店数据合并，生成一条去重记录。

提供方的角色——各展所长

各提供方并非可以互换，而是互为补充。当 merge 合并重复项时，GeoWire 不会直接选取优先级最高的提供方的整条记录，而是从对相应字段最具权威性的提供方获取每个字段。每个提供方都会在其清单（fieldAuthority）中声明其优势，因此合并后的一处地点可以同时包含 OSM 的坐标、Google 的评论和 Kakao 的本地名称：

提供方	权威字段	角色
Nominatim / OSM	location、address	基础地图几何信息和地址
Google	business（评分、营业时间、评论）、contact	丰富的商业信息
Foursquare	business（照片、价格）、类别	全球 POI 专家
Kakao / Naver / Baidu	name、address	特定国家／地区的本地名称
Internal（你的 CSV）	name、contact、business	你的数据是可信来源

每个响应中的 sources[].fields 都会记录各字段来自哪个提供方。这就是代码中的“地图领域的 Stripe”理念：你会得到一条整洁的地点记录，其中每个部分都来自最了解它的提供方。（评论／照片是提供方的原始内容——策略引擎会强制执行各提供方的存储条款；Google 原始内容不会被缓存。）

想要添加其他提供方？请参阅 CONTRIBUTING.md—— “30 分钟编写一个提供方”。

配方与示例

• docs/recipes.md——端到端配方：附近＋半径搜索、 合并＋去重、成本预算、按国家／地区路由、使用你自己的 CSV、自托管。
• examples/mcp-clients.md——Claude Desktop/Code、Cursor、Cline、VS Code、Windsurf 的配置。
• examples/typescript-sdk.md——嵌入 SDK。
• examples/llm-tool-use.md——原始 OpenAI / Anthropic 函数调用。另见 LangChain · Vercel AI SDK。

路线图

v0.1 的范围刻意限定为“能够运行”。坦诚说明目前尚未包含的内容：

领域	已发布	计划中
操作	搜索、地理编码、反向地理编码、获取地点、路线规划、距离矩阵、区域分析、等时圈	自动补全（已输入类型，但尚未接入）
策略	first-success、merge、cost-aware、weighted、fastest	—（全部 5 种均已发布）
字段来源	基于角色的合并（每个提供方的权威字段）	按字段配置覆盖
路线规划提供方	OSRM（无需密钥）、Google Routes（自带密钥）	Mapbox、Valhalla、HERE
路线规划	显式指定 country，优先使用免费服务的成本排序	根据坐标推断国家
分析	类别密度／竞争／评分分布、美国人口统计数据、活动代理指标、等时圈（出行时间覆盖范围）	实际客流量（付费数据）、精确等时圈（ORS/Valhalla）、韩国人口统计数据（SGIS）
缓存	内存中（LRU）	Redis 适配器
提供方	OSM、OSRM、Google、Yelp、Foursquare、Census、Kakao、Naver、Baidu、自有 CSV	Mapbox、HERE、TomTom、……（欢迎社区提交 PR）
速率限制	按提供方设置（OSM 每秒 1 个请求）	全局／按端点

架构

AI agent / app
   │  MCP · REST · SDK
   ▼
GeoWire core  ── pipeline: plan → execute → normalize → dedup → rank → policy → cache
   │  GeoProvider contract
   ▼
providers: nominatim · osrm · google · yelp · foursquare · census · kakao · naver · baidu · internal · (community)

单体仓库包含以下软件包：schema · provider-sdk · provider-testkit · core · providers/* · mcp · apps/server · cli。

文档

• 配方／操作指南 — 面向任务，可直接复制粘贴
• 示例 — MCP 客户端、SDK、LangChain、AI SDK、工具使用
• 贡献指南 + 编写提供方
• 系统设计

许可证

Apache-2.0。GeoWire 代码的许可证与第三方地图／地点数据提供方的条款相互独立——Google、Mapbox、HERE、Kakao、Naver 等服务的使用均受各提供方自身条款约束。OSM 数据采用 ODbL；GeoWire 的策略引擎会针对各提供方强制执行署名和缓存限制。