mapbox-search-patterns

Mapbox 検索パターンのスキル

Mapbox 検索ツールを効果的に使用するための、AI アシスタント向けの専門的なガイダンスです。ツールの選択、パラメーターの最適化、ジオコーディング、POI 検索、場所の探索に関するベストプラクティスを説明します。

利用可能な検索ツール

1. search_and_geocode_tool

最適な用途： 特定の場所、住所、ブランド、名前のある地点

クエリに次の内容が含まれる場合に使用します：

• 具体的な名称：「5番街のStarbucks」、「Empire State Building」
• ブランド名：「McDonald's」、「Whole Foods」
• 住所：「123 Main Street, Seattle」、「1 Times Square」
• チェーン店：「Target」
• 都市・場所：「San Francisco」、「Portland」

次の用途には使用しないでください： 一般的なカテゴリ（「コーヒーショップ」、「美術館」）

2. category_search_tool

最適な用途： 一般的な場所の種類、カテゴリ、複数形のクエリ

クエリに次の内容が含まれる場合に使用します：

• 一般的な種類：「コーヒーショップ」、「レストラン」、「ガソリンスタンド」
• 複数形：「美術館」、「ホテル」、「公園」
• 「〜はありますか」という表現：「コーヒーショップはありますか」、「すべてのレストラン」、「近くの薬局」
• 業界用語：「電気自動車の充電器」、「ATM」

次の用途には使用しないでください： 特定の名称やブランド

3. reverse_geocode_tool

最適な用途： 座標を住所、都市、町、郵便番号に変換する場合

次のような場合に使用します：

• GPS 座標があり、人が読める住所が必要な場合
• 特定の場所に何があるかを特定する必要がある場合
• ユーザーの位置情報を住所に変換する場合

ツール選択の判断表

ユーザーのクエリ	ツール	理由
"Find Starbucks on Main Street"	search_and_geocode_tool	特定のブランド名
"Find coffee shops nearby"	category_search_tool	一般的なカテゴリ、複数形
"What's at 37.7749, -122.4194?"	reverse_geocode_tool	座標から住所への変換
"Empire State Building"	search_and_geocode_tool	名前が特定された POI
"hotels in downtown Seattle"	category_search_tool	一般的な種類＋場所
"Target store locations"	search_and_geocode_tool	ブランド名（複数形でも）
"any restaurant near me"	category_search_tool	一般的な種類＋「any」の表現
"123 Main St, Boston, MA"	search_and_geocode_tool	特定の住所
"electric vehicle chargers"	category_search_tool	業界カテゴリ
"McDonald's"	search_and_geocode_tool	ブランド名

パラメーターのガイダンス

proximity、bbox、country の使い分け

検索結果を空間的に制限する3つの方法：

1. proximity（強く推奨）

機能： 結果を特定の場所に近いものへ偏らせますが、遠くにある一致候補は除外しません。

次のような場合に使用します：

• ユーザーが「近く」、「近所」、「近い」と言っている場合
• 基準となる場所はあるものの、ある程度の柔軟性が必要な場合
• ある地点との関連性に基づいて結果を並べ替えたい場合

例：

{
  "q": "pizza",
  "proximity": {
    "longitude": -122.4194,
    "latitude": 37.7749
  }
}

この方法が有効な理由： API はまずサンフランシスコのピザ店を返しますが、関連性が非常に高ければ、ニューヨークの有名なピザ店が含まれることもあります。

重要： 基準となる場所がある場合は、必ず proximity を設定してください。設定しないと、結果は IP ベースまたは全世界を対象としたものになります。

2. bbox（バウンディングボックス）

機能： 厳密な制約です。ボックス内の結果のみを返します。

次のような場合に使用します：

• ユーザーが「ダウンタウン内」、「この近隣地区内」などのエリアを指定している場合
• サービス提供エリアが定義されている場合
• 結果が境界内にあることを保証する必要がある場合

例：

{
  "q": "hotel",
  "bbox": [-122.51, 37.7, -122.35, 37.83] // [minLon, minLat, maxLon, maxLat]
}

この方法が有効な理由： すべてのホテルがサンフランシスコのダウンタウン地区内にあることを保証します。

注意点： 範囲が狭すぎると結果がなくなり、広すぎると関連性の低い結果が含まれます。

3. country

機能： 結果を特定の国に限定します。

次のような場合に使用します：

• ユーザーが国を指定している場合：「フランスのレストラン」
• 国別の機能を構築している場合
• 地域の境界を尊重する必要がある場合
• または、特定の国の結果を求めていることが明らかな場合

例：

{
  "q": "Paris",
  "country": ["FR"] // ISO 3166 alpha-2 codes
}

この方法が有効な理由： テキサス州のパリではなく、フランスのパリを見つけます。

組み合わせ可能： proximity ＋ country ＋ bbox、またはこれら3つの任意の組み合わせ

判断マトリクス：空間フィルター

シナリオ	使用するもの	理由
「近くのコーヒー店を探す」	proximity	ユーザーの位置を優先します
「シアトルのダウンタウンにあるコーヒー店」	proximity + bbox	ダウンタウンを中心にし、エリアを限定します
「フランスのホテル」	country	国境で厳密に限定します
「サンフランシスコで人気のピザ店」	proximity + country ["US"]	SF を優先し、US に限定します
「このルート沿いのガソリンスタンド」	ルート周辺の bbox	ルート周辺の範囲に厳密に限定します
「5 マイル以内のレストラン」	proximity（その後、距離でフィルター）	近くを優先し、結果をフィルターします

limit パラメーターの設定

category_search_tool のみ（1～25、デフォルトは 10）

用途	Limit	理由
簡単な候補提示	5	高速で、結果を絞り込めます
標準的なリスト	10	デフォルトで、バランスが良好です
網羅的な検索	25	許可される最大値
地図での表示	25	近くの候補をすべて表示します
ドロップダウン／オートコンプリート	5	UI に候補を表示しすぎないようにします

パフォーマンスのヒント： limit を小さくすると、応答が速くなります。

types パラメーター（search_and_geocode_tool）

フィーチャータイプでフィルターします：

タイプ	含まれるもの	使用する場面
poi	POI（ビジネス、ランドマーク）	住所ではなく、POI を探す場合
address	番地を含む住所	特定の住所が必要な場合
place	都市、近隣地域、地域	エリア／地域を探す場合
street	番地を含まない通りの名前	特定の住所ではなく、通りが必要な場合
postcode	郵便番号	ZIP／郵便番号で検索する場合
district	地区、近隣地域	エリアを基準に検索する場合
locality	町、村	自治体を検索する場合
country	国名	国レベルで検索する場合

組み合わせの例：

// Only POIs and addresses, no cities
{"q": "Paris", "types": ["poi", "address"]}
// Returns Paris Hotel, Paris Street, not Paris, France

// Only places (cities)
{"q": "Paris", "types": ["place"]}
// Returns Paris, France; Paris, Texas; etc.

デフォルトの動作： すべてのタイプが含まれます（通常はこの設定で問題ありません）。

auto_complete パラメーター（search_and_geocode_tool）

機能： 部分一致／あいまい一致を有効にします。

設定	動作	使用する場面
true	途中までの単語や誤字にも一致します	ユーザーがリアルタイムで入力している場合
false（デフォルト）	完全一致します	オートコンプリートではなく、最終クエリーの場合

例：

// User types "starb"
{ "q": "starb", "auto_complete": true }
// Returns: Starbucks, Starboard Tavern, etc.

次の用途に使用します：

• 入力と同時に検索するインターフェース

• 誤字への対応（「mcdonalds」→ McDonald's）

• 未入力のクエリー

次の場合は使用しないでください：

• 最終送信するクエリー（精度が下がります）
• 完全一致が必要な場合

避けるべきアンチパターン

禁止：ブランドに category_search を使用する

// BAD
category_search_tool({ category: 'starbucks' });
// "starbucks" is not a category, returns error

// GOOD
search_and_geocode_tool({ q: 'Starbucks' });

禁止：一般的なカテゴリーに search_and_geocode を使用する

// BAD
search_and_geocode_tool({ q: 'coffee shops' });
// Less precise, may return unrelated results

// GOOD
category_search_tool({ category: 'coffee_shop' });

禁止：ローカル検索で proximity を忘れる

// BAD - Results may be anywhere globally
category_search_tool({ category: 'restaurant' });

// GOOD - Biased to user location
category_search_tool({
  category: 'restaurant',
  proximity: { longitude: -122.4194, latitude: 37.7749 }
});

禁止：proximity を指定せずに曖昧な地名をジオコーディングする（REST でも同様）

これは、MCP ツールだけでなく、ブラウザーアプリで使う Mapbox Geocoding API v5／Search Box にも当てはまります。

// BAD — limit=1 without proximity can resolve "Lincoln Memorial" to Illinois
fetch(`https://api.mapbox.com/geocoding/v5/mapbox.places/${encodeURIComponent(q)}.json?access_token=${token}&limit=1`);

// GOOD — bias to map center (and optional bbox)
fetch(
  `https://api.mapbox.com/geocoding/v5/mapbox.places/${encodeURIComponent(q)}.json` +
    `?access_token=${token}&proximity=-77.0369,38.9072&bbox=-77.15,38.79,-76.90,38.99&limit=1`
);

また、検索入力にはデバウンス（clearTimeout + setTimeout）を設定し、キー入力のたびにジオコーディングが実行されないようにします。

禁止：proximity を使うべき場面で bbox を使用する

// BAD - Hard boundary may exclude good nearby results
search_and_geocode_tool({
  q: 'pizza',
  bbox: [-122.42, 37.77, -122.41, 37.78] // Tiny box
});

// GOOD - Bias toward point, but flexible
search_and_geocode_tool({
  q: 'pizza',
  proximity: { longitude: -122.4194, latitude: 37.7749 }
});

禁止：不要な ETA を要求する

// BAD - Costs API quota for routing calculations
search_and_geocode_tool({
  q: 'museums',
  eta_type: 'navigation',
  navigation_profile: 'driving'
});
// User didn't ask for travel time!

// GOOD - Only add ETA when needed
search_and_geocode_tool({ q: 'museums' });
// If user asks "how long to get there?", then add ETA

禁止：UI 表示の limit を大きくしすぎる

// BAD - Overwhelming for simple dropdown
category_search_tool({
  category: 'restaurant',
  limit: 25
});
// Returns 25 restaurants for a 5-item dropdown

// GOOD - Match UI needs
category_search_tool({
  category: 'restaurant',
  limit: 5
});

クイックリファレンス

ツール選択フローチャート

User query contains...

-> Specific name/brand (Starbucks, Empire State Building)
  -> search_and_geocode_tool

-> Generic category/plural (coffee shops, museums, any restaurant)
  -> category_search_tool

-> Coordinates -> Address
  -> reverse_geocode_tool

-> Address -> Coordinates
  -> search_and_geocode_tool with types: ["address"]

必須パラメーターのチェックリスト

ローカル検索では、必ず次を設定してください：

• proximity（厳密な境界が必要な場合は bbox）

カテゴリ検索では、次を検討してください：

• limit（UI の要件に合わせます）
• format（地図にプロットする場合は json_string）

曖昧さを解消するには、次を使用してください：

• country（地理的なコンテキストが重要な場合）
• types（地物の種類が重要な場合）

所要時間による順位付けでは、次を指定してください：

• eta_type、navigation_profile、origin（API クォータを消費します）

よくある間違い

1. proximity の指定忘れ -> 検索結果が全世界／IP ベースになります（または、名称が曖昧な記念碑や公園で誤った州の結果が表示されます）
2. 誤ったツールの使用 -> 「Starbucks」には category_search を使用します（search_and_geocode を使用してください）
3. 無効なカテゴリ -> まず category_list を確認してください
4. bbox が小さすぎる -> 結果が見つかりません。代わりに proximity を使用してください
5. 不要な ETA の要求 -> API コストが増加します
6. UI に対して limit が大きすぎる -> ユーザーが結果に圧倒されます
7. types によるフィルタリングなし -> POI が必要なのに都市が取得されます
8. タイプアヘッドでのデバウンスなし -> クォータを消費し、UI の動作が不安定になります

リファレンスファイル

特定のトピックについて詳しく知るには、次のファイルを読み込んでください：

• references/advanced-params.md — poi_category、ETA、format、language の各パラメーター
• references/workflows.md — よくあるパターン：近くの場所、ブランド検索、ジオコーディング、カテゴリ＋エリア、逆ジオコーディング、ルートベース、多言語
• references/optimization-combining.md — パフォーマンスの最適化、ツールの組み合わせ、検索結果がない場合の対処、category list リソース