Mapbox Search Patterns Skill

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

利用可能な検索ツール

1. search_and_geocode_tool

最適な用途: 特定の場所、住所、ブランド、名称付きロケーション

以下の場合に使用:

• 特定の名称: 「Starbucks on 5th Avenue」「Empire State Building」
• ブランド名: 「McDonald's」「Whole Foods」
• 住所: 「123 Main Street, Seattle」「1 Times Square」
• チェーン店: 「Target」
• 都市/場所: 「San Francisco」「Portland」

使用しない場合: 一般的なカテゴリー（「coffee shops」「museums」）

2. category_search_tool

最適な用途: 一般的な場所のタイプ、カテゴリー、複数形クエリ

以下の場合に使用:

• 一般的なタイプ: 「coffee shops」「restaurants」「gas stations」
• 複数形: 「museums」「hotels」「parks」
• Is-a フレーズ: 「any coffee shop」「all restaurants」「nearby pharmacies」
• 業界用語: 「electric vehicle chargers」「ATMs」

使用しない場合: 特定の名称またはブランド

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 vs Bbox vs Country

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

1. proximity（強く推奨）

動作: ロケーションに向けて結果をバイアスさせますが、遠い一致を除外しません

以下の場合に使用:

• ユーザーが「near me」「nearby」「close to」と言った場合
• 参照ポイントはあるがある程度の柔軟性が必要な場合
• 結果を特定のポイントとの関連性でソートしたい場合

例:

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

動作原理: API は最初に SF のピザ屋を返しますが、関連性が高ければ有名な NYC のピザ屋も含める可能性があります

重要: 参照ロケーションがある場合は常に proximity を設定してください！設定しないと、結果は IP ベースまたはグローバルになります。

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

動作: ハード制約 - ボックス内の結果のみを返します

以下の場合に使用:

• ユーザーがエリアを指定した場合: 「in downtown」「within this neighborhood」
• 定義されたサービスエリアがある場合
• 結果がバウンダリ内であることを保証する必要がある場合

例:

{
  "q": "hotel",
  "bbox": [-122.51, 37.7, -122.35, 37.83]
}

動作原理: すべてのホテルが SF のダウンタウンエリア内にあることを保証します

注意: ボックスが小さすぎる = 結果なし；大きすぎる = 関連性の低い結果

3. country

動作: 結果を特定の国に制限します

以下の場合に使用:

• ユーザーが国を指定した場合: 「restaurants in France」
• 国別の機能を構築している場合
• 地域的な境界を尊重する必要がある場合
• またはユーザーが特定の国内の結果を望んでいることが明確な場合

例:

{
  "q": "Paris",
  "country": ["FR"]
}

動作原理: Paris, France を検索します（Paris, Texas ではなく）

組み合わせ可能: proximity + country + bbox または 3 つの任意の組み合わせ

判定マトリックス: 空間フィルタ

シナリオ	使用	理由
「Find coffee near me」	proximity	ユーザーロケーションに向けてバイアス
「Coffee shops in downtown Seattle」	proximity + bbox	ダウンタウンを中心に、エリアに制限
「Hotels in France」	country	ハード国境
「Best pizza in San Francisco」	proximity + country ["US"]	SF にバイアス、US に制限
「Gas stations along this route」	ルート周辺の bbox	ルート廊下へのハード制約
「Restaurants within 5 miles」	proximity（その後距離でフィルタ）	近くをバイアス、結果をフィルタ

limit パラメータの設定

category_search_tool のみ (1-25, デフォルト 10)

ユースケース	制限値	理由
クイック提案	5	高速でフォーカスされた結果
標準リスト	10	デフォルト、バランスが良い
包括的な検索	25	最大許容値
マップ表示	25	すべての近くのオプションを表示
ドロップダウン/オートコンプリート	5	UI を圧倒しない

パフォーマンスのヒント: 制限値が低い = 更高速なレスポンス

types パラメータ（search_and_geocode_tool）

機能タイプでフィルタ:

タイプ	含まれるもの	使用する場合
poi	関心地点（ビジネス、ランドマーク）	POI を検索、住所ではない
address	街路住所	特定の住所が必要
place	都市、地区、地域	エリア/地域を検索
street	番号のない街路名	街路が必要、特定の住所ではない
postcode	郵便番号	ZIP/郵便番号で検索
district	地区、地域	エリアベースの検索
locality	町、村	市町村検索
country	国名	国レベルの検索

例の組み合わせ:

// POI と住所のみ、都市なし
{"q": "Paris", "types": ["poi", "address"]}
// Paris Hotel, Paris Street を返す、Paris, France ではなく

// 場所のみ（都市）
{"q": "Paris", "types": ["place"]}
// Paris, France; Paris, Texas など を返す

デフォルト動作: すべてのタイプを含む（通常は必要な動作）

auto_complete パラメータ（search_and_geocode_tool）

動作: 部分的/ファジーマッチングを有効にします

設定	動作	使用する場合
true	部分単語、タイプミスにマッチ	ユーザーがリアルタイムで入力中
false（デフォルト）	完全一致	最終クエリ、オートコンプリートではない

例:

// ユーザーが「starb」と入力
{ "q": "starb", "auto_complete": true }
// 返す: Starbucks, Starboard Tavern など

以下の場合に使用:

• 入力時検索インターフェース
• タイプミスの処理（「mcdonalds」-> McDonald's）
• 不完全なクエリ

以下の場合は使用しない:

• 最終/送信されたクエリ（精度が低い）
• 完全一致が必要な場合

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

非推奨: ブランドに category_search を使用

// 悪い例
category_search_tool({ category: 'starbucks' });
// 「starbucks」はカテゴリーではなく、エラーを返す

// 良い例
search_and_geocode_tool({ q: 'Starbucks' });

非推奨: 一般的なカテゴリーに search_and_geocode を使用

// 悪い例
search_and_geocode_tool({ q: 'coffee shops' });
// 精度が低く、関連のない結果が返る可能性がある

// 良い例
category_search_tool({ category: 'coffee_shop' });

非推奨: ローカル検索で proximity を忘れる

// 悪い例 - 結果はグローバルどこにでもある可能性がある
category_search_tool({ category: 'restaurant' });

// 良い例 - ユーザーロケーションに向けてバイアス
category_search_tool({
  category: 'restaurant',
  proximity: { longitude: -122.4194, latitude: 37.7749 }
});

非推奨: proximity の代わりに bbox を使用

// 悪い例 - ハード境界により良い近くの結果が除外される可能性がある
search_and_geocode_tool({
  q: 'pizza',
  bbox: [-122.42, 37.77, -122.41, 37.78]
});

// 良い例 - ポイントに向けてバイアス、柔軟性がある
search_and_geocode_tool({
  q: 'pizza',
  proximity: { longitude: -122.4194, latitude: 37.7749 }
});

非推奨: 不要に ETA をリクエスト

// 悪い例 - ルーティング計算に API クォータが必要
search_and_geocode_tool({
  q: 'museums',
  eta_type: 'navigation',
  navigation_profile: 'driving'
});
// ユーザーが旅行時間を尋ねていない！

// 良い例 - 必要な場合のみ ETA を追加
search_and_geocode_tool({ q: 'museums' });
// ユーザーが「how long to get there?」と尋ねた場合のみ、ETA を追加

非推奨: UI 表示に limit を高く設定

// 悪い例 - シンプルなドロップダウンには圧倒的
category_search_tool({
  category: 'restaurant',
  limit: 25
});
// 5 項目のドロップダウンに 25 のレストランを返す

// 良い例 - UI ニーズと一致させる
category_search_tool({
  category: 'restaurant',
  limit: 5
});

クイックリファレンス

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

ユーザークエリに含まれる...

-> 特定の名称/ブランド（Starbucks、Empire State Building）
  -> search_and_geocode_tool

-> 一般的なカテゴリー/複数形（coffee shops、museums、any restaurant）
  -> category_search_tool

-> 座標 -> アドレス
  -> reverse_geocode_tool

-> アドレス -> 座標
  -> 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. limit が UI に対して高すぎる -> ユーザーが圧倒される
7. types をフィルタしない -> POI が必要な場合に都市を取得

リファレンスファイル

特定のトピックに関するより深いガイダンスについては以下をロードしてください:

• references/advanced-params.md — poi_category、ETA、format、言語パラメータ
• references/workflows.md — 一般的なパターン: Near Me、Branded、Geocoding、Category+Area、Reverse、Route-Based、Multilingual
• references/optimization-combining.md — パフォーマンス最適化、ツールの組み合わせ、結果がない場合の処理、カテゴリーリストリソース