geowire

GeoWire

API キー不要で、わずか 5 分であらゆる AI エージェントに実世界の位置情報インテリジェンスを提供します。

あらゆる地図プロバイダーを横断する、場所の検索、ルート案内、エリア／市場分析のための統一インターフェースです。

GeoWire は、AI エージェントと地図／場所データプロバイダー（OpenStreetMap、Google、Yelp、Foursquare、US Census、お客様独自のデータ）の間に位置し、それらのデータを単一の MCP サーバー、REST API、SDK として提供する、オープンソースの位置情報インテリジェンスゲートウェイです。プロバイダーのフォールバック、複数プロバイダーの統合と重複排除、コスト上限、各プロバイダーのキャッシュ／帰属表示条件を適用するポリシーエンジンを備え、**場所の検索、ジオコーディング、ルート案内と距離行列、商業エリア分析（密度、評価、人口統計）**のための統一インターフェースを提供します。

npm で公開済み — MCP・REST・CLI・SDK はすべて利用可能です。10 プロバイダー、8 操作。

**誠実さを設計の基本にしています。**API キー不要のデフォルトである OpenStreetMap は優れたジオコーダーで、地名、住所、ランドマークに強い一方、「コーヒー」「薬局」などのカテゴリ語、評価、営業時間の情報は限られています。米国／西洋圏の商業データには、Google、Yelp、Foursquare のキーをご利用ください（BYOK）。GeoWire はデータを統合し、各フィールドの出典を示します。ルート案内は OpenStreetMap のルーティング（OSRM）を使用するためキー不要です。米国の人口統計データは Census から取得します（無料のキーが必要です）。

目次：理由 · クイックスタート · MCP ツール · REST · レスポンスの構造 · 設定 · プロバイダー · レシピと例 · ロードマップ · アーキテクチャ

GeoWire を選ぶ理由

	直接統合	単一プロバイダーの MCP	GeoWire
統一された場所スキーマ	❌ プロバイダーごとのコード	❌	✅
障害発生時のプロバイダーフォールバック	❌	❌	✅
複数プロバイダーの統合と重複排除	❌	❌	✅
コスト上限とルーティング	❌	❌	✅
API キーなしで動作	❌	場合による	✅（デフォルトは OSM）
セルフホスト可能	—	場合による	✅
独自の場所データをプロバイダーとして利用	❌	❌	✅
透明なデータ来歴（出典とコスト）	❌	❌	✅（すべてのレスポンス）

Google の代替ではなく、Google を利用します。単一のプロバイダーにはできないこと、それはお客様独自の店舗データ + Google + OSMを統合し、重複のない 1 件のレコードにまとめることです。フィールドごとのデータ来歴も提供します（店舗名はお客様のデータを優先し、評価は Google、座標は OSM から取得します）。実行例：

検索だけではなく、エージェントのための位置情報インテリジェンス

エージェントが場所を見つけられるようになれば、エリアについて推論できるようになります。analyze_area を 1 回呼び出すだけで、地点と半径から商業地区の状況を把握できます。カテゴリの密度、競合状況、評価の分布、そして（米国内では）人口統計データを確認できます。

// "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 経由でキー不要なので、エージェントは所要運転時間で候補を順位付けしたり、「この住所から車で 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 km 以内でコーヒー店を探してください。」「サンフランシスコのダウンタウンからフィッシャーマンズワーフまで車で行くにはどうすればよいですか？」と尋ねてください。API キーなしで動作します。デフォルトでは OpenStreetMap と OSRM のルーティングを使用します。評価、レビュー、営業時間には "env": { "GOOGLE_MAPS_API_KEY": "..." }（または YELP_API_KEY）を、エリアの人口統計データには "CENSUS_API_KEY" を追加してください。その他の MCP クライアント設定もご覧ください。

2. CLI — 1 回限りの検索とサーバー

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	座標の周辺地域の人口／年齢／所得（米国国勢調査、無料キー）
list_geo_providers	有効なプロバイダー、機能、ステータス（エージェントの自己認識）

すべてのレスポンスには、人が読める要約と structuredContent （スキーマに準拠した 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=	周辺地域の人口統計（米国国勢調査、無料キー）
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)	BYOK KAKAO_REST_API_KEY	search、geocode、reverseGeocode
@geowirehq/provider-naver (네이버 지역검색, KR)	BYOK NAVER_CLIENT_ID+NAVER_CLIENT_SECRET	search、geocode
@geowirehq/provider-baidu (百度地图, CN)	BYOK BAIDU_MAP_AK	search、geocode、reverseGeocode
@geowirehq/provider-foursquare (global POI)	BYOK FOURSQUARE_API_KEY	search、getPlace
@geowirehq/provider-yelp (US/Western business, ratings & reviews)	BYOK YELP_API_KEY	search、getPlace
@geowirehq/provider-census (US demographics)	BYOK CENSUS_API_KEY (無料)	demographics
@geowirehq/provider-internal (自分のCSV)	なし	search

地域プロバイダーを使うことで、OSMの情報が少なくGoogleの対応にも不足がある韓国（Kakao/Naver）や中国（Baidu）を第一級でカバーできます。BaiduはBD-09座標を返しますが、GeoWireが自動的にWGS84へ変換します。これらすべてのデータに自分の店舗データを加え、重複を排除した1つのレコードに統合できます。

プロバイダーの役割 — それぞれの得意分野を担当

プロバイダーは相互に置き換えられるものではなく、互いに補完し合うものです。merge が重複を統合する際、GeoWireは優先順位が最も高いプロバイダーのレコード全体を選ぶのではなく、各フィールドについて、その情報を最も正確に提供するプロバイダーから取得します。各プロバイダーはマニフェスト（fieldAuthority）で得意分野を宣言するため、1つに統合された場所情報に、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」の考え方です。整った場所情報を1つ取得でき、その各部分は最も詳しいプロバイダーから提供されます。（レビューや写真はプロバイダーのオリジナルデータです。ポリシーエンジンが各プロバイダーの保存条件を適用するため、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（BYOK）	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 のポリシーエンジンはプロバイダーごとに帰属表示とキャッシュ制限を適用します。