mcpField
S
suggest

suggest

github.com/brave開発1921.1k 回インストール11 週間前に更新
リポジトリ

suggest について

Suggestは、部分的なクエリに対する候補を返すBrave Search APIの補完エンドポイントです。言語、国、件数を指定でき、リッチモードではエンティティの詳細も取得できます。

主な機能

  1. 01クエリのオートコンプリート候補
  2. 02言語、国、件数の指定
  3. 03任意のエンティティ詳細と画像
  4. 04誤字を含むクエリへの候補提示

活用シーン

  1. 01検索入力に応じた候補画面の構築
  2. 02RAG検索前の部分クエリの補完
  3. 03検索結果画面でのエンティティ表示
  4. 04誤字を含む入力への候補提示

インストール

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

$npx skills add https://github.com/brave/brave-search-skills --skill suggest

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

詳細

候補表示／オートコンプリート

API キーが必要です：https://api.search.brave.com から取得してください。

プラン：Suggest プランに含まれています。https://api-dashboard.search.brave.com/app/subscriptions/subscribe をご覧ください。

クイックスタート（cURL）

基本的な候補表示
curl -s "https://api.search.brave.com/res/v1/suggest/search?q=how+to+" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"
すべてのパラメーターを指定する場合
curl -s "https://api.search.brave.com/res/v1/suggest/search" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -G \
  --data-urlencode "q=albert" \
  --data-urlencode "country=US" \
  --data-urlencode "lang=en" \
  --data-urlencode "count=10" \
  --data-urlencode "rich=true"

エンドポイント

GET https://api.search.brave.com/res/v1/suggest/search

認証：X-Subscription-Token: <API_KEY> ヘッダー

省略可能なヘッダー：

  • Accept-Encoding: gzip — レスポンスの圧縮を有効にします

パラメーター

パラメーター型必須デフォルト説明
qstringはい—候補を表示する検索クエリ（1～400文字、最大50語）
langstringいいえen言語設定（2文字以上の言語コード。例：fr、de、zh-hans）
countrystringいいえUS検索対象国（2文字の国コードまたはALL）
countintいいえ5候補数（1～20）。実際の結果はこれより少ない場合があります
richboolいいえfalseエンティティ情報（タイトル、説明、画像）を追加します。有料のSearchプランが必要です

レスポンスフィールド

フィールド型説明
typestring常に"suggest"です
query.originalstring元の候補表示用検索クエリ
resultsarray候補のリスト（空の場合があります）
results[].querystring候補として提案されたクエリの補完内容
results[].is_entitybool?候補として提案された拡張クエリがエンティティかどうか（richのみ）
results[].titlestring?候補として提案されたクエリの拡張タイトル（richのみ）
results[].descriptionstring?候補として提案されたクエリの拡張説明（richのみ）
results[].imgstring?候補として提案されたクエリの拡張画像URL（richのみ）

値がnullのフィールドはレスポンスから除外されます。richでない結果にはqueryフィールドのみが含まれます。

richレスポンスの例（rich=true）
{
  "type": "suggest",
  "query": { "original": "albert" },
  "results": [
    {
      "query": "albert einstein",
      "is_entity": true,
      "title": "Albert Einstein",
      "description": "German-born theoretical physicist",
      "img": "https://imgs.search.brave.com/..."
    },
    { "query": "albert einstein quotes", "is_entity": false }
  ]
}

ユースケース

  • 入力中の検索候補表示：リアルタイムのオートコンプリートドロップダウン。デバウンス時間は150～300msに設定します。
  • RAG 用のクエリ調整：web-searchまたはllm-contextを呼び出す前に、途中まで入力されたクエリや曖昧なクエリを拡張します。
  • エンティティ検出：rich=trueを使って、プレビューカード用のタイトル、説明、画像を含むエンティティを検出します。
  • 誤入力に強い入力：別途スペルチェックを行わずに、誤字のある入力から適切な候補を取得します。

注意事項

  • レイテンシ：100ms未満のレスポンス時間を想定して設計されています。
  • 国／言語：候補の関連性を高めるためのヒントであり、厳密なフィルターではありません。
  • 誤字への対応：別途スペルチェックを行わなくても、よくある誤字に対応した候補を表示します。

コメント

Markdown 対応