動画の検索 | YouTube Data API v2

ここで解説しているのはYouTube Data API (v2) についてであり、このAPIは2014/03/04にサポートが終了しています。リファレンス ガイド: Data API プロトコル - YouTube | Google Developers

新しいバージョンのYouTube Data API (v3) があります。

YouTubeの動画検索を行うには、次の2つの方法があります。

  • YouTube Data API
  • Google AJAX Search API

ここではYouTube Data APIについて解説します。Google AJAX Search APIについてはGoogle AJAX Search APIによる動画検索の方法で取り上げています。

YouTube Data APIとGoogle AJAX Search APIの比較
  YouTube Data API Google AJAX Search API
使用言語 Java、PHP、JavaScript JavaScript
検索対象 YouTube YouTube、Googleビデオ
機能
  • 検索
  • 動画のアップロード
  • 動画の更新と削除
  • コミュニティ機能
(YouTubeの機能)
  • 検索

リクエスト

http://gdata.youtube.com/feeds/projection/feed

URLのprojectionの値によって、下表のようにレスポンスが異なります。

projectionの値 用途 レスポンス
api 一般  
base フィードリーダー 拡張要素を含まない基本的なAtomフィード
mobile 携帯端末  

またfeedでは、取得する情報の種類を指定します。

feedの値 対象
api  
users ユーザー動画
videos 動画情報

フィードの種類

取得対象 パス
標準の動画フィード
feeds/api/standardfeeds/FeedId
動画の検索
feeds/api/videos
チャンネルの検索
feeds/api/channels
再生リストの検索
feeds/api/playlists/snippets
リファレンス ガイド: Data API プロトコル - YouTube | Google Developers

ユーザー動画

取得対象 パス
プロフィール エントリ
feeds/api/users/username
アップロードした動画
feeds/api/users/username/uploads
お気に入りの動画フィード
feeds/api/users/username/favorites
再生リスト フィード
feeds/api/users/username/playlists
チャンネル登録フィード
feeds/api/users/username/subscriptions
コンタクト フィード
feeds/api/users/username/contacts

現在認証されているユーザーの情報にアクセスするには、usernameをdefaultとします。

動画情報

取得対象 パス
動画情報
feeds/api/videos/videoid
動画レスポンスフィード
feeds/api/videos/videoid/responses
関連動画フィード
feeds/api/videos/videoid/related
コメント フィード
feeds/api/videos/videoid/comments
 
feeds/api/videos/videoid/ratings
 
feeds/api/videos/videoid/complaints

クエリ パラメータ

サポートされるGoogle Data APIのクエリ
パラメータ 説明 既定値
alt 返されるデータのフォーマット指定
  • atom (既定)
  • rss
  • json
  • json-in-script※1
  • jsonc※1※2
※1 コールバック関数を、callbackパラメータの値に設定する必要がある。
※2 対応するフィードは、動画、プレイリスト、お気に入り動画のみ。
atom
author

検索リクエストでは、検索範囲を特定のYouTubeユーザーがアップロードした動画に制限する

標準フィードのリクエストでは、標準フィードを取得してから、特定の投稿者がアップロードした動画にのみレスポンスをフィルタリングする

ユーザー アクティビティ フィードのリクエストでは、authorパラメータには、最大20件のYouTubeユーザー名をカンマで区切ったリストを含める。レスポンスには、それらのユーザーのいずれかが行ったアクティビティが含まれる

 
callback APIレスポンスを送るコールバック関数を指定する
(altパラメータの値がjson-in-scriptまたはjsoncに設定されている場合にのみ使用)
 
max-results 結果セットに含める最大の件数を指定する。最大値は50 25
prettyprint trueに設定すると、インデントや改行でフォーマットされたXMLレスポンスをリクエストする false
start-index 一致した結果のうち、結果セットに最初に含める結果のインデックスを指定する

1をベースとしたインデックス。つまり最初の結果が1で、2番目の結果が2

 
strict trueに設定すると、APIリクエストに無効なリクエスト パラメータが含まれていた場合に、そのリクエストを拒否することを指示

APIのデフォルトの動作では、無効なリクエスト パラメータを無視する

 
v APIリクエストの処理にYouTubeが使用するAPIのバージョンを指定する。APIバージョンの指定は、GData-Version HTTPリクエスト ヘッダーでも可

APIのバージョンを指定しないと、YouTubeではそのリクエストの処理にAPIバージョン1を使用する。APIのバージョン指定については、APIのバージョン指定セクションにある

 
Queries - Protocol Reference - Google Data Protocol - Google Code
YouTube Data API固有のクエリ
パラメータ 説明
caption 検索する動画を、キャプション トラックがある動画に制限する

このパラメータは値を指定しない。さもなくばAPIはHTTP 400レスポンスを返す。

category 特定のカテゴリの動画、または特定のキーワードやデベロッパー タグに関連する動画を取得する
client (必須) クライアントID (アプリケーションを特定する文字列) を指定する
format 動画が特定の動画フォーマットで再生できる必要があることを示す。次のフォーマットのいずれかを指定する。
動画フォーマット
1 モバイル向け動画の再生用RTSPストリーミングURL。H.263動画 (最大176x144) とAMR音声
5 この動画用の埋め込み型プレーヤー (SWF) へのHTTP URL。このフォーマットは、埋め込み可能ではない動画には利用できない。通常、デベロッパーはクエリに &format=5を追加して、自分のサイトに埋め込むことができる動画に検索を制限する。
6 モバイル向け動画の再生用RTSPストリーミングURL。MPEG-4 SP動画 (最大176x144) とAAC音声
key (必須) デベロッパー キーを指定する。これはAPIリクエストを行っているデベロッパーまたは会社を識別する英数字の文字列
location 検索する動画を、そのメタデータに指定された地理的場所によって制限する。次のいずれかのコンテキストで使用できる。
  • 特定の場所を指定する地理座標 (緯度,経度) を指定する。そのときにはlocation-radiusパラメータと組み合わせて、地域を定義する

    地名に関連付けられていて、特定の地理座標には関連付けられていない動画をAPIレスポンスから除外するには、感嘆符 (「!」) をパラメータ値の最後に追加する。これによりAPIレスポンス内のすべての動画を、必ず地図上にプロットできるようになる。

    このパラメータの使用例を次に示す。

    location=37.42307,-122.08427&location-radius=100km
    location=37.42307,-122.08427!&location-radius=100km

    特定の座標に関連付けられたフィード エントリには<georss:where>タグが含まれ、さらに<yt:location>タグが含まれることもある。

    地名に関連付けられ、特定の地理座標には関連付けられてはいないフィード エントリは、<yt:location>タグを使って場所を指定する。

  • 空にするか、または感嘆符を1つ指定する。そのときパラメータには値は必要ない。

    パラメータを指定すると地理的場所が指定された動画に検索結果が限定されるが、特定の地理的場所の動画を検索することはできない。

    地理的場所が指定された動画では、そのメタデータに<georss:where>タグが含まれる。

location-radius locationパラメータと組み合わせて地域を指定する。動画に関連付けられた地理座標がその地域内にある場合、その動画は検索の対象となる。

パラメータ値は、浮動小数点数の後に単位を付けて指定する必要がある。有効な単位は、m、km、ft、mi。有効なパラメータ値の例は、「1500m」、「5km」、「10000ft」、「0.75mi」。この半径の値が、1,000kmより大きいと、APIはエラーを返す。

lr 検索範囲を、タイトル、説明、またはキーワードが特定の言語である動画に制限する。このパラメータは、標準フィード以外の動画フィードのリクエストに使用できる。

動画で利用できるキャプション トラックのリストを取得するリクエストで、lrパラメータはキャプション トラックのリストをフィルタリングして、指定した言語のみを含むようにする。lrパラメータの有効値は、ISO 639-1の2文字の言語コード

orderby 動画フィードに対してのみサポートされており、検索結果セットの動画を並べ替えるために使用する値を指定する

このパラメータの有効値は、

  • relevance (関連度)
  • published (投稿日時)
  • viewCount (再生回数)
  • rating (評価)
  • relevance_lang_languageCode

relevance_lang_languageCodeに設定すると、特定の言語に最も関連性の高い結果を要求できる。ここでlanguageCodeはISO 639-1の2文字の言語コード。言語コードを指定した場合でも、検索キーワードとの関連性が高い場合には他の言語の結果も返されることがある。

デフォルト値は、検索結果フィードの場合relevance (関連性)

q 検索キーワードを指定する。

動画のすべての動画メタデータ (タイトル、キーワード、説明、投稿者のユーザー名、カテゴリ) をこのキーワードと照合して検索する。

パラメータ値の中に空白、引用符などの区切り文字を含めるには、URLエスケープが必要。

  • 完全一致を検索 … キーワードを引用符 (") で囲む。たとえば「spy plane」に一致する動画を検索するには、「%22spy+plane%22」とする。

リクエストにブール型演算子のNOT (-) とOR (|) を使って、動画を除外したり、複数の検索キーワードのいずれかに関連する動画を検索したりすることもできる。(パイプ (|) 文字はURLエスケープし、「%7C」とする)

  • 「boating」または「sailing」に一致する動画を検索するには、「boating%7Csailing」とする。
  • 「boating」か「sailing」のいずれかに一致し、「fishing」には一致しない動画を検索するには、「boating%7Csailing+-fishing」とする。

Data API v3での動画検索

restriction 再生可能な国が特定されている動画の、フィルタリングに使用するIPアドレスを指定する。

このパラメータを常に使用して、エンド ユーザーのIPアドレスを指定することが望ましい (デフォルトでは、クライアント アプリケーションのIPアドレスに基づいて、APIリクエストを送信している国で再生できない動画が除外される)。

再生可能な動画を個々のコンピュータからリクエストするには、リクエストにrestrictionパラメータを含め、パラメータ値を、動画を再生するコンピュータのIPアドレスに設定する (例:restriction=255.255.255.255)。

特定の国で再生できる動画をリクエストするには、リクエストにrestrictionパラメータを含め、パラメータ値を、動画を再生する国のISO 3166の2文字の国コードに設定する (例:restriction=DE)。

検索結果、再生リスト、お気に入りの動画、動画レスポンスなど、動画のリストを取得するどのリクエストにも、このパラメータを含める。APIレスポンス内の動画が、指定している地域で再生できず、コンテンツの利用が制限されている場合、そのタグの<entry>には<media:content>タグは含まれないが、その動画が制限されていることを示す<yt:state>タグが含まれる。

safeSearch 検索結果に標準コンテンツの他、制限コンテンツも含めるかどうかを指定する。

YouTubeでコンテンツを制限するかどうかの判断は、APIリクエストにrestrictionパラメータを使って指定したユーザーのIPアドレスや場所に基づく。制限コンテンツをリクエストすると、制限コンテンツを含む動画のフィード エントリには、<media:rating>要素が含まれる。

このパラメータの有効な値は次の通り

説明
none 検索結果セットのフィルタリングを行わない。
moderate (既定値) 検索結果のコンテンツに対して一定のフィルタリングを行い、少なくともアプリケーションの言語/地域で制限されているコンテンツは除外する。

動画の内容に基づいて、検索結果から動画が削除されたり検索結果内での優先度が下がったりすることがある。

strict 検索結果から制限コンテンツをすべて除外しようとする。

動画の内容に基づいて、検索結果から動画が削除されたり検索結果内での優先度が下がったりすることがある。

(※safeSearchパラメータはYouTube Data APIのバージョン2で導入された。これはバージョン1で使用されていたracyに代わるもの) セーフモード - YouTube ヘルプ
time 指定された期間内にアップロードされた動画に検索を制限する。

このパラメータの有効な値は、

  • today (1日)
  • this_week (7日)
  • this_month (1か月)
  • all_time (すべての期間) (既定値)

このパラメータは、検索フィードと、top_rated、top_favorites、most_viewed、most_popular、most_discussed、most_respondedの各標準フィードに対してサポートされる。

uploader 検索リクエストに対してのみサポートされており、YouTubeパートナーの動画にのみ検索範囲を制限できる。

YouTubeパートナーとは、YouTubeパートナー プログラムに承認され、参加している個人または組織のこと。uploaderパラメータの値にはpartnerを指定する。

APIレスポンスのフィード エントリには、<media:credit>タグのyt:type属性値がpartnerである場合、エントリにパートナー動画が含まれる。

<media:credit role="uploader" scheme="urn:youtube yt:type="partner">
  partner_name
</media:credit>
デベロッパー ガイド: Data API プロトコル - API クエリ パラメータ - YouTube の API とツール - Google Code

カテゴリとキーワードによる検索

URLの一部で指定する方法と、URLのクエリ部分で指定する方法の2つがあります。

http://gdata.youtube.com/feeds/api/videos/-/keyword?v=2
http://gdata.youtube.com/feeds/api/videos?category=keyword&v=2

キーワードの最初の文字は小文字にします。さもなくば、それはカテゴリ名として扱われます。

検索条件の指定
AND検索

それぞれの方法に応じて、スラッシュ (/) かカンマ (,) で区切ります。

http://gdata.youtube.com/feeds/api/videos/-/word1/word2?v=2
http://gdata.youtube.com/feeds/api/videos?category=word1%2Cword2&v=2
OR検索

いずれの方法でもパイプ (|) で区切ります。ただしクエリで指定する方法では、エンコードした「%7C」とします。

NOT検索

キーワードの前にハイフン (-) を指定します。

レスポンス

JSONC形式

{

    "apiVersion": "2.1",
    "data": {
        "updated": "2012-04-25T14:07:31.000Z",
        "totalItems": 8006,
        "startIndex": 1,
        "itemsPerPage": 25,
        "items": [ … ]
    }

}
itemsプロパティ
プロパティ 説明
id 動画を識別するURN
uploaded 最初にアップロードされた日時
updated 最後に更新された日時
uploader アップロードしたユーザー名
category カテゴリ
title タイトル
description 動画の要約
tags タグ
thumbnail サムネイル
player プレーヤーにより再生できる動画のURL
content 動画に関するURLとさまざまな情報
duration 動画の長さ [秒]
aspectRatio 動画のアスペクト比
viewCount 再生回数
favoriteCount お気に入りに追加したユーザー数
status 動画の状態
accessControl 動画へのアクセス制御
statusプロパティ
value reason 説明
restricted requesterRegion ユーザーの地域では利用できない
limitedSyndication ブラウザ以外のデバイスでは利用できない
private 動画へのアクセスが制限されている (非公開動画)
rejected copyright 動画が著作権を侵害している
inappropriate 動画に不適切なコンテンツが含まれている
duplicate 動画がアップロード済みの別の動画と重複している
termsOfUse 動画が利用規約に違反している
suspended 動画に関連付けられたアカウントが停止している
tooLong 動画の長さが上限の10分を超えている
blocked 動画がコンテンツの所有者によりブロックされている
failed cantProcess 動画ファイルを変換できない
invalidFormat 動画のファイルフォーマットが無効
unsupportedCodec 動画のコーデックがサポートされていない
empty 動画ファイルが空
tooSmall 動画ファイルが小さすぎる
yt:state - Data API プロトコル - YouTube | Google Developers
accessControlプロパティ
プロパティ 制御対象
rate 動画の評価
comment 動画についてのコメント
commentVote 他のユーザー コメントの評価
videoRespond 動画へのレスポンス
embed サードパーティのサイトへの動画の埋め込み
syndicate 携帯電話やテレビでの表示
list YouTubeの検索結果への表示
yt:accessControl - Reference Guide: Data API Protocol - YouTube | Google Developers