ウェブ検索

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 の両方のメソッドがサポートされています。POST は長いクエリや複雑な Goggles に便利です。

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

オプショナルヘッダー:

• Accept-Encoding: gzip — gzip 圧縮を有効化

ウェブ検索をいつ使用するか

機能	ウェブ検索 (本機能)	LLM コンテキスト (llm-context)	回答 (answers)
出力	構造化結果 (リンク、スニペット、メタデータ)	LLM 用に事前抽出されたページコンテンツ	エンドツーエンドの AI 回答と引用元
結果タイプ	ウェブ、ニュース、動画、ディスカッション、FAQ、インフォボックス、ロケーション、リッチ結果	抽出されたテキストチャンク、テーブル、コード	合成された回答 + ソースリスト
ユニーク機能	Goggles、構造化データ (schemas)、リッチコールバック	トークン予算管理、閾値モード	マルチイテレーション検索、ストリーミング、OpenAI SDK 互換
速度	高速 (~0.5-1s)	高速 (<1s)	遅い (~30-180s)
最適用途	検索 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-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

# Web と video 結果のみ
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	string	常に "search"
query.original	string	元の検索クエリ
query.altered	string?	スペルチェック修正済みクエリ (変更されている場合)
query.cleaned	string?	クリーンアップ/正規化されたクエリ
query.spellcheck_off	bool?	スペルチェックが無効化されたかどうか
query.more_results_available	bool	より多くのページが存在するかどうか
query.show_strict_warning	bool?	厳密な safesearch が成人向け結果をブロックした場合は true
query.search_operators	object?	適用された検索演算子 (applied, cleaned_query, sites)
web.type	string	常に "search"
web.results[].title	string	ページタイトル
web.results[].url	string	ページ URL
web.results[].description	string?	スニペット/説明テキスト
web.results[].age	string?	人間が読みやすい経過時間 (例: "2 days ago")
web.results[].language	string?	コンテンツ言語コード
web.results[].meta_url	object	URL コンポーネント (scheme, netloc, hostname, path)
web.results[].thumbnail	object?	サムネイル (src, original)
web.results[].thumbnail.original	string?	オリジナル フルサイズ画像 URL
web.results[].thumbnail.logo	bool?	サムネイルがロゴかどうか
web.results[].profile	object?	パブリッシャー識別情報 (name, url, long_name, img)
web.results[].page_age	string?	公開日時 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	string?	コンテンツタイプ分類
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	string?	フォーラム/コミュニティ名
discussions.results[].data.num_answers	int?	回答/返信の数
discussions.results[].data.question	string?	ディスカッション質問
discussions.results[].data.top_comment	string?	最高評価のコメント抜粋
faq.results[]	array?	FAQ エントリー
news.results[]	array?	ニュース記事
videos.results[]	array?	ビデオ結果
infobox.results[]	array?	ナレッジグラフエントリー
locations.results[]	array?	ローカル POI 結果
rich.hint.vertical	string?	リッチ結果タイプ
rich.hint.callback_key	string?	リッチデータ用コールバックキー

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 レスポンス

mixed オブジェクトは、異なるタイプ間での結果の優先表示順序を定義します。3 つの配列を含みます:

配列	目的
main	プライマリ結果リスト (表示する結果の順序付きシーケンス)
top	メイン結果の上に表示する結果
side	メイン結果とともに表示する結果 (例: インフォボックス)

各エントリーは type (例: "web", "videos")、index (対応する結果配列への参照)、all (この位置でそのタイプのすべての結果を含める場合は true) を持つ ResultReference です。

検索演算子

演算子	構文	説明
Site	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 で登録される必要があります。インライン型ルールは登録不要です。

構文: $boost=N / $downrank=N (1–10)、$discard、$site=example.com。カンマで結合: $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

リソース: Discover · 構文 · Quickstart

リッチデータエンリッチメント

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

# 1. リッチコールバックを有効にして検索
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}"

# レスポンスに含まれます: "rich": {"hint": {"callback_key": "abc123...", "vertical": "weather"}}

# 2. コールバックキーでリッチデータを取得
curl -s "https://api.search.brave.com/res/v1/web/rich?callback_key=abc123..." \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

対応リッチタイプ: Calculator、Definitions、Unit Conversion、Unix Timestamp、Package Tracker、Stock、Currency、Cryptocurrency、Weather、American Football、Baseball、Basketball、Cricket、Football/Soccer、Ice Hockey、Web3、Translator

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

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 でサイトをブースト/破棄し、完全にカスタマイズされたランキング実現します。

注記

• ページネーション: offset (0-9) と count を使用して結果をページネーション
• Count: ウェブ検索の最大は 20; 実際の結果数はリクエスト数より少ない可能性があります