web-search

Web Search

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

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

クイックスタート（cURL）

基本的な検索

curl -s "https://api.search.brave.com/res/v1/web/search?q=python+web+frameworks" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

パラメーターを指定した検索

curl -s "https://api.search.brave.com/res/v1/web/search" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -G \
  --data-urlencode "q=rust programming tutorials" \
  --data-urlencode "country=US" \
  --data-urlencode "search_lang=en" \
  --data-urlencode "count=10" \
  --data-urlencode "safesearch=moderate" \
  --data-urlencode "freshness=pm"

エンドポイント

GET https://api.search.brave.com/res/v1/web/search
POST https://api.search.brave.com/res/v1/web/search

注：GET メソッドと POST メソッドの両方に対応しています。長いクエリや複雑な Goggles には POST が便利です。

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

任意のヘッダー：

• Accept-Encoding: gzip — gzip 圧縮を有効にします

Web Search の用途

機能	Web Search（このツール）	LLM Context（llm-context）	Answers（answers）
出力	構造化された検索結果（リンク、スニペット、メタデータ）	LLM 向けに抽出済みのページコンテンツ	引用付きのエンドツーエンドの AI 回答
検索結果の種類	Web、ニュース、動画、ディスカッション、FAQ、インフォボックス、場所、リッチ	抽出されたテキストチャンク、表、コード	統合された回答とソース一覧
独自の機能	Goggles、構造化データ（schemas）、リッチコールバック	トークン予算の制御、しきい値モード	複数回の検索、ストリーミング、OpenAI SDK 互換
速度	高速（約0.5～1秒）	高速（1秒未満）	低速（約30～180秒）
最適な用途	検索 UI、データ抽出、カスタムランキング	RAG パイプライン、AI エージェント、グラウンディング	チャットインターフェース、詳細な調査

パラメーター

パラメーター	型	必須	デフォルト	説明
q	string	はい	-	検索クエリ（1～400文字、最大50語）
country	string	いいえ	US	検索対象の国（2文字の国コードまたは ALL）
search_lang	string	いいえ	en	言語の指定（2文字以上の言語コード）
ui_lang	string	いいえ	en-US	UI の言語（例："en-US"）
count	int	いいえ	20	1ページあたりの最大検索結果数（1～20）
offset	int	いいえ	0	ページネーションのページオフセット（0～9）
safesearch	string	いいえ	moderate	アダルトコンテンツのフィルター（off／moderate／strict）
freshness	string	いいえ	-	時間フィルター（pd／pw／pm／py または日付範囲）
text_decorations	bool	いいえ	true	ハイライトマーカーを含めます
spellcheck	bool	いいえ	true	クエリを自動修正します
result_filter	string	いいえ	-	検索結果の種類をフィルターします（カンマ区切り）
goggles	string	いいえ	-	カスタムランキングフィルター（URL またはインライン）
extra_snippets	bool	いいえ	-	検索結果ごとに最大5件の追加スニペットを取得します
operators	bool	いいえ	true	検索演算子を適用します
units	string	いいえ	-	測定単位（metric／imperial）
enable_rich_callback	bool	いいえ	false	サードパーティのリッチデータコールバックを有効にします
include_fetch_metadata	bool	いいえ	false	検索結果に fetched_content_timestamp を含めます

鮮度の値

値	説明
pd	過去1日（24時間）
pw	過去1週間（7日間）
pm	過去1か月（31日間）
py	過去1年（365日間）
YYYY-MM-DDtoYYYY-MM-DD	任意の日付範囲

検索結果フィルターの値

フィルターの種類：discussions、faq、infobox、news、query、videos、web、locations

# Only web and video results
curl "...&result_filter=web,videos"

位置情報ヘッダー（任意）

位置情報に対応した結果を得るには、次のヘッダーを追加します。座標が分かっている場合は緯度／経度だけで十分です。ほかのヘッダーは、座標を取得できない場合の代替としてのみ必要です。

ヘッダー	型	説明
X-Loc-Lat	float	ユーザーの緯度（-90.0～90.0）
X-Loc-Long	float	ユーザーの経度（-180.0～180.0）
X-Loc-Timezone	string	IANA タイムゾーン（例："America/San_Francisco"）
X-Loc-City	string	市区町村名
X-Loc-State	string	州／地域コード（ISO 3166-2）
X-Loc-State-Name	string	州／地域の正式名称（例："California"）
X-Loc-Country	string	2 文字の国コード
X-Loc-Postal-Code	string	郵便番号（例："94105"）

優先順位：X-Loc-Lat と X-Loc-Long が優先されます。指定されている場合、下流サービスは座標から直接位置情報を解決し、テキストベースのヘッダー（City、State、Country、Postal-Code）は位置情報の解決には使用されません。座標がない場合にのみ、テキストベースのヘッダーを指定してください。両方を送信しても問題はありません。緯度／経度が優先されます。

レスポンス形式

レスポンスフィールド

フィールド	型	説明
type	文字列	常に "search" です
query.original	文字列	元の検索クエリ
query.altered	文字列?	スペルチェックで修正されたクエリ（変更された場合）
query.cleaned	文字列?	整理／正規化されたクエリ
query.spellcheck_off	bool?	スペルチェックが無効になっていたかどうか
query.more_results_available	bool	さらにページがあるかどうか
query.show_strict_warning	bool?	厳格なセーフサーチによって成人向けの結果がブロックされた場合は True
query.search_operators	object?	適用された検索演算子（applied、cleaned_query、sites）
web.type	文字列	常に "search" です
web.results[].title	文字列	ページタイトル
web.results[].url	文字列	ページ URL
web.results[].description	文字列?	スニペット／説明文
web.results[].age	文字列?	人が読み取れる形式の経過時間（例："2 days ago"）
web.results[].language	文字列?	コンテンツの言語コード
web.results[].meta_url	object	URL の構成要素（scheme、netloc、hostname、path）
web.results[].thumbnail	object?	サムネイル（src、original）
web.results[].thumbnail.original	文字列?	元のフルサイズ画像の URL
web.results[].thumbnail.logo	bool?	サムネイルがロゴかどうか
web.results[].profile	object?	発行元の情報（name、url、long_name、img）
web.results[].page_age	文字列?	公開日時の ISO 形式の日時（例："2025-04-12T14:22:41"）
web.results[].extra_snippets	list[str]?	追加の抜粋（最大 5 件）
web.results[].deep_results	object?	ページ内の追加リンク（buttons、links）
web.results[].schemas	list?	schema.org の構造化データ（未加工）
web.results[].product	object?	商品情報とレビュー
web.results[].recipe	object?	レシピの詳細（材料、時間、評価）
web.results[].article	object?	記事のメタデータ（著者、発行元、日付）
web.results[].book	object?	書籍情報（著者、ISBN、評価）
web.results[].software	object?	ソフトウェア製品の情報
web.results[].rating	object?	総合評価
web.results[].faq	object?	ページで見つかった FAQ
web.results[].movie	object?	映画情報（監督、出演者、ジャンル）
web.results[].video	object?	動画のメタデータ（再生時間、再生回数、作成者）
web.results[].location	object?	場所／レストランの詳細
web.results[].qa	object?	質問と回答の情報
web.results[].creative_work	object?	クリエイティブ作品のデータ
web.results[].music_recording	object?	音楽／楽曲のデータ
web.results[].organization	object?	組織情報
web.results[].review	object?	レビューデータ
web.results[].content_type	文字列?	コンテンツ種別の分類
web.results[].fetched_content_timestamp	int?	取得時刻（include_fetch_metadata=true の場合）
web.mutated_by_goggles	bool	Goggles によって検索結果の順位が変更されたかどうか
web.family_friendly	bool	検索結果がファミリー向けかどうか
mixed	object?	優先表示順（「Mixed Response」を参照）
discussions.results[]	array?	フォーラムのディスカッションクラスター
discussions.results[].data.forum_name	文字列?	フォーラム／コミュニティ名
discussions.results[].data.num_answers	int?	回答／返信の数
discussions.results[].data.question	文字列?	ディスカッションの質問
discussions.results[].data.top_comment	文字列?	最も多く投票されたコメントの抜粋
faq.results[]	array?	FAQ 項目
news.results[]	array?	ニュース記事
videos.results[]	array?	動画の検索結果
infobox.results[]	array?	ナレッジグラフの項目
locations.results[]	array?	地域の POI 検索結果
rich.hint.vertical	文字列?	リッチ検索結果の種類
rich.hint.callback_key	文字列?	リッチデータのコールバックキー

JSON の例

{
  "type": "search",
  "query": {
    "original": "python frameworks",
    "altered": "python web frameworks",
    "spellcheck_off": false,
    "more_results_available": true
  },
  "web": {
    "type": "search",
    "results": [
      {
        "title": "Top Python Web Frameworks",
        "url": "https://example.com/python-frameworks",
        "description": "A comprehensive guide to Python web frameworks...",
        "age": "2 days ago",
        "language": "en",
        "meta_url": {
          "scheme": "https",
          "netloc": "example.com",
          "hostname": "example.com",
          "path": "/python-frameworks"
        },
        "thumbnail": {
          "src": "https://...",
          "original": "https://original-image-url.com/img.jpg"
        },
        "extra_snippets": ["Additional excerpt 1...", "Additional excerpt 2..."]
      }
    ],
    "family_friendly": true
  },
  "mixed": {
    "type": "mixed",
    "main": [
      {"type": "web", "index": 0, "all": false},
      {"type": "web", "index": 1, "all": false},
      {"type": "videos", "all": true}
    ],
    "top": [],
    "side": []
  },
  "videos": { "...": "..." },
  "news": { "...": "..." },
  "rich": {
    "type": "rich",
    "hint": {
      "vertical": "weather",
      "callback_key": "<callback_key_hex>"
    }
  }
}

混合レスポンス

mixed オブジェクトは、種類をまたいだ結果の優先表示順を定義します。次の3つの配列が含まれます。

配列	目的
main	メインの結果リスト（表示する結果の順序付きシーケンス）
top	メインの結果の上に表示する結果
side	メインの結果の横に表示する結果（例：インフォボックス）

各エントリは ResultReference で、type（例："web"、"videos"）、index（対応する結果配列内のインデックス）、all（この位置にその種類の結果をすべて含める場合は true）を指定します。

検索演算子

演算子	構文	説明
サイト	site:example.com	特定のドメインに結果を限定します
ファイル拡張子	ext:pdf	特定のファイル拡張子を持つ結果
ファイルタイプ	filetype:pdf	特定のファイルタイプで作成された結果
タイトル内	intitle:python	タイトルに語句を含むページ
本文内	inbody:tutorial	本文に語句を含むページ
ページ内	inpage:guide	タイトルまたは本文に語句を含むページ
言語	lang:es	特定の言語（ISO 639-1）のページ
地域	loc:us	特定の国（ISO 3166-1 alpha-2）のページ
含める	+term	語句を必ず含めます
除外	-term	語句を含むページを除外します
完全一致	"exact phrase"	指定した語句の順序で完全一致させます
AND	term1 AND term2	両方の語句が必要です（大文字）
OR / NOT	term1 OR term2、NOT term	論理演算子です（大文字）

演算子の解析を無効にするには、operators=false を設定します。

Goggles（カスタムランキング）— Brave 独自機能

Goggles を使うと、検索結果の順位を変更できます。信頼できる情報源の順位を上げたり、SEO スパムを抑制したり、対象を絞った検索範囲を作成したりできます。

方法	例
ホスト型	--data-urlencode "goggles=https://raw.githubusercontent.com/brave/goggles-quickstart/main/goggles/rust_programming.goggle"
インライン	--data-urlencode 'goggles=$discard\n$site=example.com'

ホスト型の Goggles は GitHub/GitLab 上に置き、! name:、! description:、! author: のヘッダーを含めたうえで、https://search.brave.com/goggles/create に登録する必要があります。インラインルールの登録は不要です。

構文：ルールは $ に続けて、カンマ区切りのオプションを指定します。アクション（いずれか1つ）：discard、boost[=N]、downrank[=N]。N は 1～10 の整数です。サイトフィルター：site=DOMAIN。例：$site=example.com,boost=3。ルールは \n（%0A）で区切ります。

許可リスト：$discard\n$site=docs.python.org\n$site=developer.mozilla.org — ブロックリスト：$discard,site=pinterest.com\n$discard,site=quora.com

リソース：見つける · 構文 · クイックスタート

リッチデータの拡充

天気、株式、スポーツ、通貨などに関するクエリには、リッチコールバックのワークフローを使用します。

# 1. Search with rich callback enabled
curl -s "https://api.search.brave.com/res/v1/web/search?q=weather+san+francisco&enable_rich_callback=true" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

# Response includes: "rich": {"hint": {"callback_key": "abc123...", "vertical": "weather"}}

# 2. Get rich data with the callback key
curl -s "https://api.search.brave.com/res/v1/web/rich?callback_key=abc123..." \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

対応するリッチタイプ：計算機、定義、単位変換、Unix タイムスタンプ、荷物追跡、株式、通貨、暗号通貨、天気、アメリカンフットボール、野球、バスケットボール、クリケット、サッカー、アイスホッケー、Web3、翻訳

リッチコールバックエンドポイント

GET https://api.search.brave.com/res/v1/web/rich

パラメーター	型	必須	説明
callback_key	string	はい	ウェブ検索の rich.hint.callback_key フィールドにあるコールバックキー

ユースケース

• 汎用検索の統合：1回の呼び出しで、最も充実した結果セット（ウェブ、ニュース、動画、ディスカッション、FAQ、インフォボックス、場所）を取得します。RAG/LLM のグラウンディングには、llm-context を推奨します。
• 構造化データの抽出：schemas と結果の型付きフィールドを使って、商品、レシピ、評価、記事を取得します。
• Goggles によるカスタム検索：Brave 独自の機能です。インラインルールまたはホスト型 Goggles を使ってサイトの順位を上げたり、除外したりし、ランキングを完全にカスタマイズできます。

注意事項

• ページネーション：結果をページ分割するには、count とともに offset（0～9）を使用します
• 件数：ウェブ検索では最大20件です。実際の結果数は要求した件数より少ない場合があります