mcpField
M
mapbox-search-integration

mapbox-search-integration

github.com/mapbox開発831.9k 回インストール4 週間前に更新
リポジトリ

mapbox-search-integration について

mapbox-search-integrationは、Mapbox検索を実装する開発者やコーディングエージェント向けのスキルです。要件の確認から製品選定、各プラットフォームでの実装、リリース前の確認までを案内します。

主な機能

  1. 01検索要件のヒアリング
  2. 02用途に応じた製品選定
  3. 03Web・モバイル実装ガイド
  4. 04本番準備チェックリスト

活用シーン

  1. 01地図アプリへの場所検索追加
  2. 02住所・POI検索フローの設計
  3. 03検索機能のリリース前確認

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/mapbox/mapbox-agent-skills --skill mapbox-search-integration

インストール後、Claude Code で/mapbox-search-integrationを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

evals/
evals.json
references/
android-search.md
best-practices.md
framework-hooks.md
ios-search.md
nodejs-search.md
pitfalls.md
react-search.md
testing-monitoring.md
web-search-js.md

詳細

Mapbox Search 統合スキル

アプリケーションに Mapbox 検索機能を実装するための専門的なガイダンスです。適切な要件確認の質問から、適切な検索プロダクトの選択、Mapbox 検索チームのベストプラクティスに沿った本番環境対応の統合の実装まで、ワークフロー全体を網羅します。

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

ユーザーが次のように言った場合：

  • 「地図に検索機能を追加したい」
  • 「地図アプリ用の検索バーが必要です」
  • 「場所検索はどのように実装すればよいですか？」
  • 「ユーザーが場所や住所を検索できるようにしたい」
  • 「アプリケーションでジオコーディングが必要です」

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

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

要件確認フェーズ：適切な質問をする

コードに取りかかる前に、要件を把握するために次の質問をします。

質問 1：ユーザーは何を検索しますか？

質問：「ユーザーに何を検索してもらいたいですか？」

よくある回答とその意味：

  • 「住所」 → Search Box API を使用します（ジオコーディングを含む、インタラクティブな住所検索の標準的な選択肢です）。Geocoding API は、バッチ／サーバーサイドのジオコーディングを行う場合、または既存の統合を維持する場合に限り使用します。
  • 「POI／ビジネス」 → POI 検索には、カテゴリ検索を使って Search Box API を使用します
  • 「住所と POI の両方」 → Search Box API
  • 「特定の種類の POI」（レストラン、ホテルなど） → Search Box API
  • 「国、都市、郵便番号、または近隣地域」 → インタラクティブ検索には Search Box API を使用し、Geocoding API はバッチ／サーバーサイドのジオコーディングに限り使用します
  • 「カスタムの場所」（ユーザーが作成した場所） → カスタムデータと検索の統合が必要になる場合があります

最初の質問で明らかにならなかった場合の追加質問：「ユーザーは POI データを検索しますか？レストラン、店舗、ビジネスカテゴリなどです。」

意味：

  • 「はい、POI も含みます」 → Search Box API を使用します
  • 「いいえ、POI 検索は必要ありません」 → インタラクティブ／オートコンプリートのユースケースでは、引き続き Search Box API を標準として選びます。Search Box API は、セッションベースの料金体系で住所、地名、あらゆる種類の場所を扱えます。Geocoding API を推奨するのは、バッチジオコーディング、サーバーサイドでの永続的なジオコーディング、または既存の Geocoding API 統合の維持に限ります。
質問 2：地理的な範囲はどのくらいですか？

質問：「ユーザーはどこを検索しますか？」

よくある回答とその意味：

  • 「1 か国」（例：「米国内のみ」） → 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：想定する利用量はどのくらいですか？

質問：「月に何回の検索を見込んでいますか？」

考慮事項：

  • 少量（< 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 - API 用の JavaScript（node または web）ラッパーで、独自の 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 アプリ（バニラ 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 制限が設定されている
  • 地理的フィルタリング（country、proximity、または bbox）が設定されている
  • ユースケースに応じて types パラメーターが設定されている
  • 必要に応じて language パラメーターが設定されている

実装：

  • デバウンスが実装されている（推奨：300ms）
  • セッショントークンが正しく使用されている
  • すべての失敗ケースに対するエラー処理がある
  • 読み込み状態が表示される
  • 検索結果がない場合も適切に処理される
  • 競合状態が防止されている

UX：

  • タッチターゲットが少なくとも 44pt／48dp ある
  • 結果に十分なコンテキスト（名前と住所）が表示される
  • キーボード操作が機能する
  • アクセシビリティ属性が設定されている
  • モバイルキーボードが適切に処理される

パフォーマンス：

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

テスト：

  • コアロジックのユニットテストがある
  • 実際の API を使った統合テストがある
  • 低速ネットワークでテスト済み
  • さまざまなクエリタイプでテスト済み
  • モバイルデバイスでテスト済み

モニタリング：

  • 分析トラッキングが設定されている
  • エラーログが設定されている
  • 使用状況のモニタリングが導入されている
  • 予算アラートが設定されている

他のスキルとの連携

連携対象：

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

リソース

すばやく判断するためのガイド

ユーザーの発言：「場所を検索したい」

  1. 要件を確認する質問をする（上記の質問 1〜6）
  2. 製品を推奨する：
    • Search Box API（住所のジオコーディングを含む、ユーザーが操作するすべての検索のデフォルト）
    • Geocoding API は、バッチ処理／サーバー側／永続的なジオコーディングに限って使用
    • プラットフォーム SDK を優先（ウェブでは Search JS、モバイルではネイティブ SDK）
  3. 以下を実装する：
    • ✅ デバウンス
    • ✅ セッショントークン
    • ✅ 地理的フィルタリング
    • ✅ エラー処理
    • ✅ 優れた UX
  4. 徹底的にテストする
  5. 本番環境でモニタリングする

覚えておきましょう： 最適な検索を実装するには、まず適切な質問をし、次にユーザーが必要とするものを過不足なく構築します。

コメント

Markdown 対応