動画の検索 | 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パラメータの有効値は、ISO 639-1の2文字の言語コード

orderby

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

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

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

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

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

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

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

パラメータ値の中に空白、引用符などの区切り文字を含めるには、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検索

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

参考

デベロッパーガイド: Data API プロトコル - カテゴリとキーワードによる検索 - YouTube の API とツール - Google Code

レスポンス

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