brave-search

Brave Search API

概要

Brave のプライバシー重視の Search API を使って、ウェブ、画像、ニュースを検索します。OpenAI SDK との互換性により、引用付き回答のための AI Grounding にも対応しています。

前提条件

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

export BRAVE_API_KEY="your-api-key"

無料プランでは、月あたり 2,000 件のクエリを利用できます。Pro プランでは、Local POI 検索と AI Grounding が利用可能になります。

使用する場面

• 最新情報をウェブで検索する
• トピックに関する画像を探す
• 最近のニュース記事を取得する
• 引用付きの AI Grounding 回答を得る
• オートコンプリート候補を取得する
• 位置情報／POI を検索する（Pro プラン）

高スループットでの使用

幅広く、高速に実行しましょう。 この API は最大 50 リクエスト／秒の高い並列処理に対応しています。遠慮せずに活用してください。

• 検索を並列実行します。 10 個の異なるトピックを調査する必要がありますか？ 10 件の検索を同時に開始してください。1 つのメッセージ内で複数の Bash ツール呼び出しを使用します。
• 大量の結果にはサブエージェントを使います。 多くのコンテキスト（大量の結果、追加のスニペット、リサーチモードなど）が予想される場合は、サブエージェントに検索と結果の要約を任せてください。これにより、メインのコンテキストウィンドウを節約できます。
• 関連するクエリをまとめて実行します。 競合他社、代替案、またはトピックの複数の側面を検索しますか？ すべてまとめて実行してください。

digraph parallel_search {
    rankdir=LR;
    node [shape=box];

    task [label="Research task"];
    q1 [label="Query 1"];
    q2 [label="Query 2"];
    q3 [label="Query 3"];
    subagent [label="Subagent\n(preserves context)"];
    synthesize [label="Synthesized\nfindings"];

    task -> q1;
    task -> q2;
    task -> q3;
    q1 -> subagent [style=dashed];
    q2 -> subagent [style=dashed];
    q3 -> subagent [style=dashed];
    subagent -> synthesize;
}

サブエージェントを使う場面：

• トピックに関する多くの情報源を検索する（検索サブエージェントを起動し、要約を返してもらう）
• AI Grounding を使った詳細な調査（大量のトークンを使用するため、サブエージェントに任せる）
• 複数の選択肢を比較する（並列検索を実行し、サブエージェントに結果をまとめてもらう）

直接検索する場面：

• 生の URL／スニペットが必要な、手早い単一クエリ
• コンテキストを気にする必要がない、結果数の少ない検索

クイックリファレンス

タスク	コマンド
ウェブ検索	brave-search web "query"
画像検索	brave-search images "query"
ニュース検索	brave-search news "query"
AI 回答	brave-search ai "question"
候補の取得	brave-search suggest "partial query"
キーの確認	brave-search check-key

API エンドポイント

API	エンドポイント	プラン
ウェブ検索	/res/v1/web/search	無料
画像検索	/res/v1/images/search	無料
ニュース検索	/res/v1/news/search	無料
サジェスト	/res/v1/suggest/search	無料
AI Grounding	/res/v1/chat/completions	AI Grounding
Local POI	/res/v1/local/pois	Pro
Summarizer	/res/v1/summarizer/search	Pro

共通パラメーター

ウェブ検索

# Basic search
brave-search web "python async tutorial" --count 10

# Filter by freshness (pd=24h, pw=7d, pm=31d, py=365d)
brave-search web "latest news" --freshness pd

# Filter by country and language
brave-search web "local restaurants" --country US --lang en

# Safe search (off, moderate, strict)
brave-search web "query" --safesearch strict

# Get extra snippets
brave-search web "query" --extra-snippets

# Filter result types (web, news, videos, images, discussions)
brave-search web "query" --filter web,news

画像検索

# Basic image search
brave-search images "mountain sunset"

# With safe search
brave-search images "landscape" --safesearch strict --count 20

ニュース検索

# Recent news
brave-search news "AI developments" --count 10

# News with freshness filter
brave-search news "election results" --freshness pd

AI Grounding（引用付き回答）

# Get an AI answer with citations
brave-search ai "What is the tallest building in the world?"

# Enable deep research (multiple searches, slower)
brave-search ai "Compare React and Vue in 2024" --research

ワークフロー

digraph brave_search {
    rankdir=TB;
    node [shape=box];

    need [label="What do you need?" shape=diamond];
    web [label="Web Search\nbrave.py web"];
    images [label="Image Search\nbrave.py images"];
    news [label="News Search\nbrave.py news"];
    ai [label="AI Answer\nbrave.py ai"];

    results [label="Parse JSON results"];
    cite [label="Include citations\nfor AI answers"];

    need -> web [label="web pages"];
    need -> images [label="images"];
    need -> news [label="recent news"];
    need -> ai [label="cited answer"];

    web -> results;
    images -> results;
    news -> results;
    ai -> cite;
}

レスポンス構造

ウェブ検索結果

{
  "web": {
    "results": [
      {
        "title": "Page Title",
        "url": "https://example.com",
        "description": "Snippet from the page...",
        "extra_snippets": ["Additional context..."]
      }
    ]
  },
  "query": {
    "original": "search query",
    "altered": "modified query if spellchecked"
  }
}

AI Grounding のレスポンス

インライン引用付きの OpenAI 互換形式を返します。

The tallest building is the Burj Khalifa[1] at 828 meters...

[1] https://source-url.com

共通オプション

オプション	値	説明
--count	1-20（ウェブ）、1-200（画像）	結果数
--country	US、GB、DE、FR など	検索地域
--lang	en、de、fr、es など	検索言語
--safesearch	off、moderate、strict	成人向けコンテンツのフィルター
--freshness	pd、pw、pm、py	期間のフィルター
--json	フラグ	生の JSON を出力

エラー処理

エラー	原因	対処法
401 Unauthorized	API キーが無効、または未設定	BRAVE_API_KEY を確認してください
429 Rate Limited	リクエストが多すぎます	待つか、プランをアップグレードしてください
422 Validation	パラメーターが無効です	パラメーター値を確認してください

レート制限

• 無料：1 リクエスト／秒、月あたり 2,000 件
• Pro：より高い制限。ダッシュボードで確認してください
• レスポンスヘッダーに残りのクォータが表示されます：X-RateLimit-Remaining

よくある間違い

間違い	対処法
API キーが設定されていない	export BRAVE_API_KEY="..."
プランに合わないエンドポイント	ダッシュボードでサブスクリプションを確認してください
結果が多すぎる	ウェブ検索の上限は 20 件です。ページネーションには offset を使用してください
AI Grounding が利用できない	AI Grounding のサブスクリプションが必要です