Mapbox Search Integration Skill

Mapbox検索機能をアプリケーションに実装するための専門的なガイダンス。発見質問から適切な検索プロダクトの選択、Mapbox検索チームからのベストプラクティスに従った本番対応インテグレーションの実装まで、完全なワークフローをカバーしています。

このスキルを使用する場合

ユーザーが以下のようなことを言った場合:

• 「マップに検索機能を追加する必要があります」
• 「マッピングアプリ用の検索バーが必要です」
• 「ロケーション検索をどのように実装しますか?」
• 「ユーザーが場所/住所を検索できるようにしたいです」
• 「アプリケーションにジオコーディングが必要です」

このスキルは mapbox-search-patterns を補完します:

• mapbox-search-patterns = ツールおよびパラメータの選択
• mapbox-search-integration = 完全な実装ワークフロー

発見フェーズ: 正しい質問をする

コードに飛び込む前に、要件を理解するためにこれらの質問をしてください:

質問1: ユーザーは何を検索していますか?

質問: 「ユーザーに何を検索させたいですか?」

一般的な回答と影響:

• 「住所」 → Search Box API を使用 (インタラクティブなアドレス検索のデフォルト、ジオコーディングを含む)。バッチ/サーバーサイドジオコーディングまたはレガシーインテグレーションの維持が必要な場合のみ Geocoding API を使用してください。
• 「関心地点/ビジネス」 → POI検索、カテゴリ検索を含む Search Box API を使用
• 「住所と POI の両方」 → Search Box API
• 「特定の種類の POI」 (レストラン、ホテルなど) → Search Box API
• 「国、都市、郵便番号、または地域」 → インタラクティブ検索は Search Box API を使用; バッチ/サーバーサイドジオコーディングのみ Geocoding API を使用
• 「カスタムロケーション」 (ユーザー作成の場所) → カスタムデータ+検索インテグレーションが必要な場合があります

フォローアップ (最初に述べられていない場合): 「ユーザーは関心地点データを検索していますか? レストラン、店舗、ビジネスのカテゴリ?」

影響:

• 「はい、POI が含まれています」 → Search Box API を使用
• 「いいえ、ユーザーは POI 検索が不要です」 → インタラクティブ/オートコンプリートの場合でも Search Box API がデフォルト。Search Box API は住所、地名、すべてのロケーションタイプをセッションベースの価格設定で処理します。バッチジオコーディング、サーバーサイドの恒久的なジオコーディング、または既存の Geocoding API インテグレーションの維持のみ Geocoding API を推奨してください。

質問2: 地理的な範囲は何ですか?

質問: 「ユーザーはどこで検索しますか?」

一般的な回答と影響:

• 「1 つの国」 (例: 「USA のみ」) → country パラメータを使用、結果が向上、コストが低下
• 「特定の地域」 → バウンディングボックス制約のために bbox パラメータを使用
• 「グローバル」 → 国の制限なし、ただし言語パラメータが必要な場合があります
• 「複数の特定の国」 → country 配列パラメータを使用

フォローアップ: 「結果を特定の領域に制限する必要がありますか?」 (配送ゾーン、サービス領域など)

質問3: 検索インタラクションパターンは何ですか?

質問: 「ユーザーはどのように検索と相互作用しますか?」

一般的な回答と影響:

• 「入力中に検索/オートコンプリート」 → auto_complete: true と セッションベースの価格設定を使用する Search Box API を使用 (オートコンプリートで最もコスト効率的)。デバウンシングを実装してください。
• 「検索ボタン/最終クエリ」 → どちらかの API を使用可能、オートコンプリートは不要
• 「両方」 (オートコンプリート+絞り込み) → 2 段階の検索、オートコンプリートその後詳細結果
• 「音声入力」 → 音声テキスト変換インテグレーションを検討、より長いクエリを処理

質問4: プラットフォームは何ですか?

質問: 「これは何のプラットフォーム用ですか?」

一般的な回答と影響:

• 「Web アプリケーション」 → Mapbox Search JS (最も簡単)、または高度なケースでは直接 API 呼び出し
• 「iOS アプリ」 → Search SDK for iOS (推奨)、または高度なケースでは直接 API インテグレーション
• 「Android アプリ」 → Search SDK for Android (推奨)、または高度なケースでは直接 API インテグレーション
• 「複数のプラットフォーム」 → プラットフォーム固有の SDK (推奨)、または一貫性のために直接 API アプローチ
• 「React アプリ」 → Mapbox Search JS React (UI で最も簡単)、またはカスタム UI のために Search JS Core。直接 API 呼び出しは避けてください — 手動デバウンシング、セッショントークン管理、レース条件の処理が必要です。
• 「Vue / Angular / その他のフレームワーク」 → Mapbox Search JS Core または Web。直接 API 呼び出しを使用する場合、セッショントークンは適切な課金のために必須です (検索セッションごとに 1 トークン、すべての suggest/retrieve リクエストで session_token として渡されます)。

質問5: 結果はどのように使用されますか?

質問: 「ユーザーが結果を選択したときどうなりますか?」

一般的な回答と影響:

• 「マップ上のロケーションに移動」 → 座標が必要、マップインテグレーション
• 「詳細/情報を表示」 → 結果プロパティの取得と表示が必要
• 「フォームフィールドを入力」 → アドレスコンポーネントの解析が必要
• 「ナビゲーションを開始」 → 座標が必要、ルート案内とのインテグレーション
• 「複数選択」 → 選択状態の処理、おそらくマーカーの表示が必要

質問6: 予想される使用量は?

質問: 「1 ヶ月に何件の検索を予想していますか?」

影響:

• 低量 (< 10k) → フリーティアで十分、シンプルな実装
• 中程度の量 (10k-100k) → キャッシング検討、API 呼び出しの最適化
• 高量 (> 100k) → デバウンシング、キャッシング、バッチ操作の実装、コスト監視

プロダクト選択決定ツリー

発見の回答に基づいて、適切なプロダクトを推奨してください:

主要原則: Search Box API は事実上すべてのインタラクティブ検索ユースケースのデフォルト選択です。アドレス検索、ジオコーディング、オートコンプリート、POI 検索を含みます。セッションベースの価格設定を提供し、インタラクティブ/オートコンプリートフローではより費用効率が良いです。以下にリストされた限定的なケースのみ Geocoding API を推奨してください。

Search Box API (デフォルト)

以下の場合に使用 (いずれか):

• ユーザーがインタラクティブなアドレス検索またはオートコンプリートが必要 (これはジオコーディングです — Search Box API がそれを処理します)
• ユーザーが POI / カテゴリ検索が必要
• ユーザーがエンドユーザー向けの検索 UI を構築している
• ユーザーがセッションベースの価格設定を望んでいる (オートコンプリート/インタラクティブ使用でより費用効率的)
• ユーザーが Web、iOS、または Android アプリを検索バー付きで構築している

Web インテグレーションでは直接 API 呼び出しより SDK を優先:

• Mapbox Search JS (SDK) - Web インテグレーション用推奨、3 つのコンポーネント付き:
  • Search JS React - UI 付き React ライブラリによる簡単な検索インテグレーション
  • Search JS Web - UI 付き Web Components による簡単な検索インテグレーション
  • Search JS Core - JavaScript (node または web) API ラッパー、独自の UI を構築
• Search Box API (REST) - 直接 API インテグレーション、高度な/カスタムケース向け
• Search SDK for iOS - ネイティブ iOS インテグレーション
• Search SDK for Android - ネイティブ Android インテグレーション

Geocoding API (特殊化)

次の場合のみ使用:

• 大量のアドレスリストのバッチジオコーディング (サーバーサイド)
• 恒久的/保存されたジオコーディング結果 (サーバーサイド、結果が永続化される場所)
• 既存の Geocoding API インテグレーションの維持 (移行は正当化されません)
• インタラクティブ/ユーザー向けの検索は不要

Geocoding API を推奨しないでください:

• ユーザーが検索バー、オートコンプリート、またはインタラクティブなアドレスルックアップを望んでいる場合 — Search Box API を使用してください
• ユーザーが「ジオコーディング」と言うが、インタラクティブな検索フローを説明している場合 — Search Box API を使用してください

リファレンスファイル

ユーザーのプラットフォームと必要に応じて関連するリファレンスを読み込みます:

• Web (Search JS React / Web / Core / Direct API) → references/web-search-js.md を読み込み

  • 使用する場合: ユーザーが Web アプリを構築している (Vanilla JS、React 固有のパターン以外のフレームワーク)

• React インテグレーション → references/react-search.md を読み込み

  • 使用する場合: ユーザーが特に React アプリを構築している

• iOS → references/ios-search.md を読み込み

  • 使用する場合: ユーザーが iOS アプリを構築している (Swift/UIKit/SwiftUI)

• Android → references/android-search.md を読み込み

  • 使用する場合: ユーザーが Android アプリを構築している (Kotlin/Java)

• Node.js → references/nodejs-search.md を読み込み

  • 使用する場合: ユーザーがサーバーサイド検索が必要 (Express、サーバーレス、バックエンド API)

• ベストプラクティス → references/best-practices.md を読み込み

  • 使用する場合: 初めて検索を実装する、または既存の実装を最適化する
  • カバー内容: デバウンシング、セッショントークン、地理的フィルタリング、エラーハンドリング、アクセシビリティ、キャッシング、トークンセキュリティ

• 一般的な落とし穴 → references/pitfalls.md を読み込み

  • 使用する場合: 問題のデバッグ、コード確認、またはコードレビュー中
  • カバー内容: デバウンシングなし、セッショントークンの欠落、地理コンテキストなし、貧弱なモバイル UX、レース条件

• フレームワークフック → references/framework-hooks.md を読み込み

  • 使用する場合: Search JS Core の周りにカスタムフック (React) またはコンポーザブル (Vue) を構築している

• テストとモニタリング → references/testing-monitoring.md を読み込み

  • 使用する場合: テストを作成している、または本番モニタリング/アナリティクスをセットアップしている

チェックリスト: 本番対応の検索

起動する前に以下を確認してください:

設定:

• トークンは適切にスコープされている (search:read のみ)
• URL 制限が設定されている
• 地理的フィルタリングが設定されている (国、近接、またはバウンディングボックス)
• Types パラメータがユースケースに基づいて設定されている
• 言語パラメータが必要に応じて設定されている

実装:

• デバウンシングが実装されている (300ms 推奨)
• セッショントークンが正しく使用されている
• すべての失敗ケースのエラーハンドリング
• ローディング状態が表示されている
• 空の結果が適切に処理されている
• レース条件が防止されている

UX:

• タッチターゲットが最低 44pt/48dp
• 結果が十分なコンテキストを表示 (名前+住所)
• キーボードナビゲーションが機能している
• アクセシビリティ属性が設定されている
• モバイルキーボードが適切に処理されている

パフォーマンス:

• キャッシングが実装されている (高量の場合)
• リクエストタイムアウトが設定されている
• 最小限のデータが取得されている
• バンドルサイズが最適化されている

テスト:

• コアロジックのユニットテスト
• 実際の API との統合テスト
• 遅いネットワークでテスト
• さまざまなクエリタイプでテスト
• モバイルデバイスでテスト

モニタリング:

• アナリティクストラッキングがセットアップされている
• エラーログが設定されている
• 使用状況モニタリングが配置されている
• 予算アラートが設定されている

他のスキルとのインテグレーション

連携:

• mapbox-search-patterns: パラメータ選択と最適化
• mapbox-web-integration-patterns: フレームワーク固有のパターン
• mapbox-token-security: トークン管理とセキュリティ
• mapbox-web-performance-patterns: 検索パフォーマンスの最適化

リソース

• Search Box API ドキュメント
• Geocoding API ドキュメント
• Mapbox Search JS
  • Search JS React
  • Search JS Web
  • Search JS Core
• Search SDK for iOS
• Search SDK for Android
• Location Helper Tool - バウンディングボックスを計算

クイック決定ガイド

ユーザーが言う: 「ロケーション検索が必要です」

1. 発見質問をする (上記の質問 1-6)
2. プロダクトを推奨:
   • Search Box API (すべてのインタラクティブ/ユーザー向け検索のデフォルト、アドレスジオコーディングを含む)
   • Geocoding API のみバッチ/サーバーサイド/恒久的なジオコーディング用
   • プラットフォーム SDK を優先 (Web 用 Search JS、モバイル用ネイティブ SDK)
3. 以下で実装:
   • ✅ デバウンシング
   • ✅ セッショントークン
   • ✅ 地理的フィルタリング
   • ✅ エラーハンドリング
   • ✅ 優れた UX
4. 徹底的にテスト
5. 本番でモニタリング

重要: 最高の検索実装は最初に正しい質問をし、その後ユーザーが必要とするもの正確に構築します — それ以上でもそれ以下でもなく。