videos-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/videos/search?q=python+tutorial" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

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

curl -s "https://api.search.brave.com/res/v1/videos/search" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -G \
  --data-urlencode "q=machine learning explained" \
  --data-urlencode "country=US" \
  --data-urlencode "search_lang=en" \
  --data-urlencode "count=20" \
  --data-urlencode "freshness=pm"

エンドポイント

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

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

注：GET メソッドと POST メソッドの両方をサポートしています。長いクエリには POST が便利です。

パラメーター

パラメーター	型	必須	デフォルト	説明
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～50）
offset	int	いいえ	0	ページのオフセット（0～9）
safesearch	string	いいえ	moderate	成人向けコンテンツのフィルター（off／moderate／strict）
freshness	string	いいえ	-	期間フィルター（pd／pw／pm／py または日付範囲）
spellcheck	bool	いいえ	true	クエリを自動修正します
operators	bool	いいえ	true	検索演算子を適用します
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	任意の日付範囲

レスポンス形式

{
  "type": "videos",
  "query": {
    "original": "python tutorial",
    "spellcheck_off": false
  },
  "extra": {
    "might_be_offensive": false
  },
  "results": [
    {
      "type": "video_result",
      "title": "Python Tutorial for Beginners",
      "url": "https://www.youtube.com/watch?v=rfscVS0vtbw",
      "description": "Learn Python programming from scratch...",
      "age": "February 12, 2025",
      "page_age": "2025-02-12T00:00:00",
      "page_fetched": "2025-02-12T15:00:00Z",
      "thumbnail": {
        "src": "https://imgs.search.brave.com/...",
        "original": "https://i.ytimg.com/vi/rfscVS0vtbw/hqdefault.jpg"
      },
      "video": {
        "duration": "03:45:00",
        "views": 1523000,
        "creator": "freeCodeCamp",
        "publisher": "YouTube",
        "requires_subscription": false,
        "tags": ["python", "programming"],
        "author": {
          "name": "freeCodeCamp.org",
          "url": "https://www.youtube.com/@freecodecamp"
        }
      },
      "meta_url": {
        "scheme": "https",
        "netloc": "youtube.com",
        "hostname": "www.youtube.com",
        "favicon": "https://imgs.search.brave.com/...",
        "path": "\u203a watch"
      }
    }
  ]
}

レスポンスフィールド

フィールド	型	説明
type	string	常に "videos" です
query.original	string	元の検索クエリ
query.altered	string?	スペルチェックで修正されたクエリ（変更された場合）
query.cleaned	string?	整形／正規化されたクエリ
query.spellcheck_off	bool?	スペルチェックが無効になっていたかどうか
query.show_strict_warning	bool?	厳格なセーフサーチによって成人向けの結果がブロックされた場合は True
query.search_operators	object?	適用された検索演算子（applied、cleaned_query、sites）
extra.might_be_offensive	bool	結果に不快なコンテンツが含まれる可能性があるかどうか
results[].type	string	常に "video_result" です
results[].url	string	動画のソース URL
results[].title	string	動画のタイトル
results[].description	string?	動画の説明
results[].age	string?	人が読みやすい形式の経過期間（例："6 months ago"）または絶対日付（例："February 12, 2025"）
results[].page_age	string?	ソースに記載されたページの経過期間（ISO datetime）
results[].page_fetched	string?	ページが最後に取得された日時（ISO datetime、例：2025-02-12T15:00:00Z）
results[].fetched_content_timestamp	int?	取得タイムスタンプ（include_fetch_metadata=true の場合のみ）
results[].video.duration	string?	時間文字列（形式は可変）
results[].video.views	int?	整数形式の再生回数
results[].video.creator	string?	チャンネル名／クリエイター名
results[].video.publisher	string?	プラットフォーム（YouTube、Vimeo など）
results[].video.requires_subscription	bool?	動画の視聴にサブスクリプションが必要かどうか
results[].video.tags	list[str]?	動画に関連するタグ
results[].video.author	object?	著者のプロフィール
results[].video.author.name	string	著者名
results[].video.author.url	string	著者のプロフィール URL
results[].video.author.long_name	string?	著者の詳細な名前
results[].video.author.img	string?	著者のプロフィール画像 URL
results[].thumbnail.src	string	提供されたサムネイル URL
results[].thumbnail.original	string?	元のサムネイル URL
results[].meta_url.scheme	string?	URL のプロトコルスキーム
results[].meta_url.netloc	string?	ネットワーク上の場所
results[].meta_url.hostname	string?	小文字に変換されたドメイン名
results[].meta_url.favicon	string?	ファビコン URL
results[].meta_url.path	string?	URL パス

検索演算子

検索演算子を使って結果を絞り込みます。

• site:youtube.com - 特定のサイトに限定します
• "exact phrase" - 完全一致するフレーズを検索します
• -exclude - 用語を除外します

operators=false を設定すると、演算子の解析が無効になります。

ユースケース

• 動画コンテンツの調査：トピック別にチュートリアル、解説、レビューを検索します。video.duration、video.views、video.creator のメタデータを使って、プログラムから結果を絞り込み、順位付けできます。豊富なメタデータ（再生時間、再生回数、クリエイター、タグ）とリクエストあたり最大 50 件の結果を利用できる専用動画インデックスが必要な場合は、web-search より videos-search を優先してください。
• 新着動画のモニタリング：トレンドのトピックや特定のテーマについて新しく公開された動画コンテンツを追跡するには、freshness=pd または freshness=pw を使用します。
• プラットフォームを指定した検索：site:youtube.com や site:vimeo.com の演算子を使って、特定の動画プラットフォームを対象にします。
• 動画メタデータの抽出：分析、コンテンツキュレーション、レコメンデーションシステム向けに、再生回数、再生時間、クリエイター情報、タグを取得します。

注意事項

• ページネーション：追加の結果を取得するには、count と合わせて offset（0～9）を使用します
• 最大結果数：リクエストあたり最大 50 件