mapbox-geospatial-operations

Mapbox 地理空間操作スキル

Mapbox MCP サーバーから適切な地理空間ツールを選ぶための、AI アシスタント向け専門ガイダンスです。問題が何を必要としているかに基づいてツールを選ぶことに重点を置いています。幾何計算かルーティングか、直線距離か道路ネットワークか、どの程度の精度が必要かを判断します。

基本原則：問題の種類によってツールを選ぶ

Mapbox MCP サーバーには、次の2種類の地理空間ツールがあります。

1. オフライン幾何ツール - 純粋な幾何学的・空間的計算には Turf.js を使用します
2. ルーティング・ナビゲーション API - 実際のルート、交通状況、所要時間が必要な場合は Mapbox API を使用します

重要な問い：問題が実際に必要としているものは何ですか？

判断の枠組み

問題の特性	ツールのカテゴリ	理由
直線距離（鳥の目で見た距離）	オフライン幾何	幾何学的距離を正確に計算できます
道路・経路の距離（車で移動した距離）	ルーティング API	道路ネットワークを把握しているのはルーティング API だけです
所要時間	ルーティング API	速度・交通状況データを使ったルーティングが必要です
点の包含判定（X は Y の内側か？）	オフライン幾何	純粋な幾何学的操作です
地理的形状（バッファー、重心、面積）	オフライン幾何	数学的・幾何学的な操作です
交通状況を考慮したルーティング	ルーティング API	リアルタイムの交通データが必要です
ルート最適化（訪問する最適な順序）	ルーティング API	複雑なルーティングアルゴリズムを使用します
高頻度の判定（例：リアルタイムのジオフェンシング）	オフライン幾何	遅延なく即座に応答できます

ユースケース別の判断表

距離の計算

ユーザーの質問：「X から Y までどのくらい離れていますか？」

実際に知りたいこと	ツールの選択	理由
直線距離（鳥の目で見た距離）	distance_tool	幾何学的距離を正確かつ即座に計算できます
車での移動距離	directions_tool	実際の道路距離を把握できるのはルーティングだけです
徒歩・自転車での移動距離	directions_tool	専用の経路ネットワークが必要です
所要時間	directions_tool または matrix_tool	速度データを使ったルーティングが必要です
現在の交通状況を考慮した距離	directions_tool (driving-traffic)	リアルタイムの交通状況を考慮する必要があります

例：「この5つの倉庫間の距離はどのくらいですか？」

• 鳥の目で見た距離 → distance_tool（10回の計算で即座に完了）
• 車での移動距離 → matrix_tool（5×5のマトリックスを1回の API 呼び出しで取得し、実際のルート距離を返します）

重要なポイント： 文脈における「距離」の意味に合ったツールを使います。必ず確認してください。鳥の目で見た距離ですか、それとも車での移動距離ですか？

近接性と包含

ユーザーの質問：「このエリアの近く／内部にあるポイントはどれですか？」

クエリタイプ	ツールの選択	理由
「半径 X メートル以内」	distance_tool ＋フィルター	単純な幾何学的半径
「車で X 分以内」	isochrone_tool → point_in_polygon_tool	移動時間ゾーンにはルーティングが必要で、その後に幾何学的包含を判定します
「このポリゴンの内部」	point_in_polygon_tool	純粋な幾何学的包含判定
「車で 30 分以内に到達可能」	isochrone_tool	ルーティングと交通情報が必要です
「このポイントに最も近いもの」	distance_tool（幾何学的）または matrix_tool（ルートベース）	「最も近い」の定義によって異なります

例：「これら 200 件の住所は、30 分の配達エリア内にありますか？」

1. エリアを作成 → isochrone_tool（ルーティング API。移動時間が必要）
2. 住所を確認 → point_in_polygon_tool（幾何学的。200 件を即座に判定）

重要なポイント： 移動時間ゾーンの作成にはルーティング、包含判定には幾何学的処理を使用します

ルーティングとナビゲーション

ユーザーの質問：「最適なルートはどれですか？」

シナリオ	ツールの選択	理由
A 地点から B 地点への道順	directions_tool	曲がり角ごとのルーティング
複数の立ち寄り先を回る最適な順序	optimization_tool	巡回セールスマン問題を解決します
GPS の軌跡を整える	map_matching_tool	道路網にスナップします
方位／コンパスの方向だけが必要	bearing_tool	単純な幾何学的計算
交通状況を考慮したルート	directions_tool（driving-traffic）	リアルタイムの交通状況に対応します
順序を固定したウェイポイント	ウェイポイントを指定した directions_tool	特定のポイントを経由するルーティング

例：「ホテルから空港まで案内してください」

• 曲がり角ごとの案内が必要 → directions_tool
• 「北東にある」と分かればよい → bearing_tool

重要なポイント： 実際のナビゲーションにはルーティングツール、方向情報には幾何学的ツールを使用します

面積と形状の操作

ユーザーの質問：「この場所の周囲にゾーンを作成してください」

要件	ツールの選択	理由
単純な円形バッファ	buffer_tool	幾何学的な円／半径
移動時間ゾーン	isochrone_tool	ルーティングネットワークに基づきます
面積を計算	area_tool	幾何学的計算
複雑な境界を単純化	simplify_tool	幾何学的な単純化
形状の中心を見つける	centroid_tool	幾何学的な重心

例：「各店舗の周囲 5km のカバー範囲を表示してください」

• 半径 5km → buffer_tool（幾何学的な円）
• 「15 分以内に到達できる顧客は誰ですか？」 → isochrone_tool（ルーティングベース）

重要なポイント： 距離ベースのゾーンには幾何学的ツール、時間ベースのゾーンにはルーティングツールを使用します

パフォーマンスとスケールに関する考慮事項

件数がツール選択に影響する場合

少量の処理（計算数 100 未満）：

• 幾何ツール：即座に処理でき、自由に繰り返せます
• ルーティング API：ほとんどの用途で十分な速さです

中量の処理（計算数 100～1,000）：

• 幾何ツール：引き続き高速で、問題ありません
• ルーティング API：バッチ処理（matrix_tool）を検討してください

大量の処理（計算数 1,000 超）：

• 幾何ツール：最適化が必要になる場合がありますが、それでも高速です
• ルーティング API：必ずバッチツールを使ってください（matrix_tool は最大 25×25 に対応します）

重要なポイント： 件数が幾何ツールの選択に影響することはほとんどありませんが、ルーティング API には効率化のためのバッチツールがあります

リアルタイム処理とバッチ処理

ユースケース	アプローチ	ツールの選択
リアルタイムのジオフェンシング（毎秒）	幾何学的なチェック	point_in_polygon_tool（即時）
ルート計画（一度限り）	全体的なルーティング	directions_tool または optimization_tool
定期的な近接チェック	幾何学的な距離	distance_tool
ライブ交通情報を使ったルーティング	交通情報を使ったルーティング	directions_tool（driving-traffic）

高頻度のジオフェンシングに関するアーキテクチャ上の注意： アプリケーションが非常に高い頻度（例：50 台の車両に対して 2 秒ごとにチェックする場合、毎秒 25 回）で包含チェックを呼び出すと、ネットワーク経由で MCP ツールを呼び出す際のエージェントの推論オーバーヘッドにより、実用的ではなくなります。このような場合は、頻繁に実行する処理には Turf.js をプロセス内で直接使用し（turf.booleanPointInPolygon）、ゾーンの定義（isochrone_tool）、ルートの再設定（directions_tool）、可視化（static_map_image_tool）などの周辺タスクには MCP ツールを使用することをおすすめします。

よくあるシナリオと最適なアプローチ

シナリオ 1：店舗検索

ユーザー：「最寄りの店舗を探して、5km の範囲を表示して」

最適なアプローチ：

1. 店舗を検索 → category_search_tool（距離も自動的に返します）
2. カバー範囲を作成 → buffer_tool（半径 5km の幾何学的な円）
3. 可視化 → static_map_image_tool

理由： 検索で距離がすでにわかるため、単純な半径には幾何学的なバッファーを使います

シナリオ 2：配送ルートの最適化

ユーザー：「8 件の住所／立ち寄り先への配送ルートを最適化して」

最適なアプローチ：

1. 住所をジオコーディング（必要な場合） → search_and_geocode_tool を使って、番地を含む住所を座標に変換します。座標がすでに指定されている場合でも、任意の前処理としてこれに触れてください。実際の配送リストには、住所と座標が混在していることがよくあります。
2. ルートを最適化 → optimization_tool（TSP ソルバー。総運転時間を最小化するように立ち寄り先の順序を変更します）

これらの代替手段ではなく、optimization_tool を使う理由：

• directions_tool は A → B 間（または順序が固定された経由地を通るルート）のみを検索します。立ち寄り先の順序は変更しません。8 か所を渡すと、ほとんどの場合最適ではない、指定された順序でルートを検索します。
• matrix_tool はすべての立ち寄り先の組み合わせについて所要時間を返します（8×8 = 64 個の値）が、最適な順序は計算しません。行列に基づいて自分で TSP を解く必要がありますが、optimization_tool なら 1 回の呼び出しで処理できます。

最適化の前に配送先住所をジオコーディングする際に便利なツールとして、必ず search_and_geocode_tool に言及してください。

シナリオ 3：サービスエリアの検証

ユーザー：「この 200 件の住所のうち、30 分以内に配達できるのはどれ？」

最適なアプローチ：

1. 配達エリアを作成 → isochrone_tool（車で 30 分）
2. 各住所をチェック → point_in_polygon_tool（幾何学的なチェックを 200 回）

理由： 正確な所要時間エリアにはルーティングを、包含チェックを高速に行うには幾何ツールを使います

シナリオ 4：GPS 軌跡の分析

ユーザー：「この自転車での走行はどれくらいの時間だった？」

最適なアプローチ：

1. GPS 軌跡を補正 → map_matching_tool（自転車道にスナップします）
2. 距離を取得 → API のレスポンスを使うか、distance_tool で計算します

理由： 道路／経路とのマッチングが必要です。距離の計算方法はどちらでも問題ありません

シナリオ 5：カバレッジ分析

ユーザー：「サービスエリア全体の広さはどれくらいですか？」

最適なアプローチ：

1. 各地点の周囲にバッファーを作成します → buffer_tool
2. 合計面積を計算します → area_tool
3. 時間ベースの場合は、各地点に isochrone_tool を使用します

理由： 距離ベースのカバレッジには幾何ツール、時間ベースにはルーティングを使用します

アンチパターン：誤った種類のツールを使う

❌ 避ける：ルーティングに関する質問に幾何ツールを使う

// WRONG: User asks "how long to drive there?"
distance_tool({ from: A, to: B });
// Returns 10km as the crow flies, but actual drive is 15km

// CORRECT: Need routing for driving distance
directions_tool({
  coordinates: [
    { longitude: A[0], latitude: A[1] },
    { longitude: B[0], latitude: B[1] }
  ],
  routing_profile: 'mapbox/driving'
});
// Returns actual road distance and drive time as the crow drives

誤りの理由： 直線距離 ≠ 道路を走る距離

❌ 避ける：幾何操作にルーティング API を使う

// WRONG: Check if point is in polygon
// (Can't do this with routing APIs)

// CORRECT: Pure geometric operation
point_in_polygon_tool({ point: location, polygon: boundary });

誤りの理由： ルーティング API は幾何学的な包含判定を行いません

❌ 避ける：「近い」と「到達可能」を混同する

// User asks: "What's reachable in 20 minutes?"

// WRONG: 20-minute distance at average speed
distance_tool + calculate 20min * avg_speed

// CORRECT: Actual routing with road network
isochrone_tool({
  coordinates: {longitude: startLng, latitude: startLat},
  contours_minutes: [20],
  profile: "mapbox/driving"
})

誤りの理由： 道路は直線ではなく、交通状況も変化します

❌ 避ける：方位で十分な場合にルーティングを使う

// User asks: "Which direction is the airport?"

// OVERCOMPLICATED: Full routing
directions_tool({
  coordinates: [
    { longitude: hotel[0], latitude: hotel[1] },
    { longitude: airport[0], latitude: airport[1] }
  ]
});

// BETTER: Just need bearing
bearing_tool({ from: hotel, to: airport });
// Returns: "Northeast (45°)"

こちらが望ましい理由： よりシンプルで瞬時に結果が得られ、実際の質問に答えられます

ハイブリッドアプローチ：異なる種類のツールを組み合わせる

幾何ツールとルーティングツールの両方を使うと効果的な問題もあります。

パターン 1：ルーティング + 幾何フィルター

1. directions_tool → Get route geometry
2. buffer_tool → Create corridor around route
3. category_search_tool → Find POIs in corridor
4. point_in_polygon_tool → Filter to those actually along route

使用例： 「ルート沿いのガソリンスタンドを探してください」

パターン 2：ルーティング + 距離計算

1. category_search_tool → Find 10 nearby locations
2. distance_tool → Calculate straight-line distances (geometric)
3. For top 3, use directions_tool → Get actual driving time

使用例： まず候補をすばやく絞り込み、その後、最終候補について正確なルーティングを取得します

パターン 3：等時間圏 + 包含判定

1. isochrone_tool → Create travel-time zone (routing)
2. point_in_polygon_tool → Check hundreds of addresses (geometric)

使用例： 「どの顧客が配送エリア内にいますか？」

判断アルゴリズム

ユーザーから地理空間に関する質問を受けた場合：

1. Does it require routing, roads, or travel times?
   YES → Use routing API (directions, matrix, isochrone, optimization)
   NO → Continue

2. Does it require traffic awareness?
   YES → Use directions_tool or isochrone_tool with traffic profile
   NO → Continue

3. Is it a geometric/spatial operation?
   - Distance between points (straight-line) → distance_tool
   - Point containment → point_in_polygon_tool
   - Area calculation → area_tool
   - Buffer/zone → buffer_tool
   - Direction/bearing → bearing_tool
   - Geometric center → centroid_tool
   - Bounding box → bounding_box_tool
   - Simplification → simplify_tool

4. Is it a search/discovery operation?
   YES → Use search tools (search_and_geocode, category_search)

判断のための主な質問

ツールを選ぶ前に、次の点を確認してください。

1. 「距離」は直線距離ですか、それとも道路を走る距離ですか？

   • 直線距離 → 幾何ツール
   • 道路を走る距離 → ルーティング API

2. ユーザーは移動時間を必要としていますか？

   • はい → ルーティング API（速度や交通状況を考慮できるのはこれだけです）
   • いいえ → 幾何ツールで十分な場合があります

3. 道路や経路に関する質問ですか、それとも純粋な空間的関係に関する質問ですか？

   • 道路や経路 → ルーティング API
   • 空間的関係 → 幾何ツール

4. 低レイテンシーでリアルタイムに処理する必要がありますか？

   • はい + 幾何学的な問題 → オフラインツール（瞬時に処理）
   • はい + ルーティングの問題 → ルーティング API を使用（こちらも高速です）

5. 精度が重要ですか、それとも近似で問題ありませんか？

   • 高精度が必要 + ルーティング → ルーティング API
   • 近似で問題ない → 幾何ツールを使える場合があります

用語ガイド

ユーザーの言葉の意味を理解する：

ユーザーの表現	通常の意味	ツールの種類
「距離」	文脈によって異なります。直線距離か、道路を走る距離か確認してください	状況による
「どれくらい離れているか」	多くの場合、道路を走る距離です	ルーティング API
「近く」	通常は直線距離（直線半径）です	幾何
「近い」	どちらの意味もあり得ます。確認してください！	確認する
「到達可能」	移動時間に基づきます（交通状況を考慮して道路を走る距離）	ルーティング API
「内部／含む」	幾何学的な包含	幾何
「ナビゲーション／道順」	ターンバイターンのルーティング	ルーティング API
「方位／方向」	コンパスの方角（直線距離）	幾何

クイックリファレンス

幾何操作（オフラインツール）

• distance_tool - 2 点間の直線距離
• bearing_tool - A から B へのコンパス方位
• midpoint_tool - 2 点間の中点
• point_in_polygon_tool - 点がポリゴン内にあるかを判定
• area_tool - ポリゴンの面積を計算
• buffer_tool - 円形のバッファー／ゾーンを作成
• centroid_tool - ポリゴンの幾何学的中心
• bbox_tool - ジオメトリの最小／最大座標
• simplify_tool - ジオメトリの複雑さを軽減

ルーティングとナビゲーション（API）

• directions_tool - ターンバイターンのルーティング
• matrix_tool - 多対多の移動時間
• optimization_tool - ルートの最適化（TSP）
• isochrone_tool - 移動時間ゾーン
• map_matching_tool - GPS を道路にスナップ

各カテゴリの使い分け

幾何ツールを使う場合：

• 問題が空間的または数学的なもの（包含、面積、方位）
• 直線距離が適切
• リアルタイムの確認ですぐに結果が必要
• 純粋な幾何学（道路や交通状況を考慮しない）

ルーティング API を使う場合：

• 実際の車、徒歩、自転車での移動距離が必要
• 所要時間が必要
• 道路網を考慮する必要がある
• 交通状況を考慮する必要がある
• ルートの最適化が必要
• ターンバイターン方式の道案内が必要

REST API を正確に使う（Directions / Isochrone）

Mapbox REST API（MCP ツールだけではありません）を使ったブラウザーデモを作成する場合：

Directions — ルートオブジェクトのメトリクスを使う

const route = data.routes[0];
// GOOD — meters / seconds from the API
stats.textContent =
  `Distance ${(route.distance / 1000).toFixed(2)} km · ` + `Duration ${Math.round(route.duration / 60)} min`;

// BAD — cosmetic labels or hardcoded ETAs that look like a working demo
// "Len 0.00 km · Time 2 min" / Math.round(120/60)

Isochrone — プロンプトで複数の等時間圏が求められている場合は、複数のコンターをリクエストする

// GOOD — three travel-time bands
`contours_minutes=15,30,60`;

// BAD — a single contour when the UX needs 15 / 30 / 60
`contours_minutes=30`;

他のスキルとの連携

連携できるもの：

• mapbox-search-patterns：場所を検索し、その後、地理空間操作を行います
• mapbox-web-performance-patterns：幾何計算のレンダリングを最適化します
• mapbox-token-security：適切なスコープが設定されたトークンを使ってリクエストを行います

リソース

• Mapbox MCP サーバー
• Turf.js ドキュメント（幾何ツールを支えます）
• Mapbox Directions API
• Mapbox Isochrone API
• Mapbox Matrix API
• Mapbox Optimization API