リファレンス ガイド: Data API プロトコル

目次

概要

このドキュメントは、YouTube とやり取りするクライアント アプリケーションを作成するプログラマを対象としています。このドキュメントでは、デベロッパー ガイド: Data API プロトコルの内容と Java や PHP のデベロッパー用の言語固有のガイドの内容を補足します。

このドキュメントでは、YouTube Data API を使用して取得できるさまざまなタイプのフィードを順に説明します。異なるフィード間を移動する方法を説明する図も示します。たとえば、ユーザーの再生リスト フィードに、個々の再生リストとユーザー プロフィールのようなデータを参照する URL が含まれていることを図で示します。これらの図により、あるフィードから別のフィードに移動する方法がわかります。最後に、このドキュメントでは、YouTube Data API リクエストに使用するパラメータと、API レスポンスに返される XML タグを定義します。Java や PHP のデベロッパーのために、XML タグが VideoEntry、ProfileEntry、またはその他のタイプのオブジェクトのプロパティに直接対応している場合があります。

プロジェクションの値

YouTube Data API では、API で利用可能なデータのさまざまなビュー、つまりプロジェクションが提供されます。デベロッパー ガイド: Data API プロトコルとこのドキュメントの例では、すべて api プロジェクションを使用します。このプロジェクションでは、このドキュメントの XML 要素の定義のセクションで定義されたタグがすべてサポートされます。

このドキュメントを利用するデベロッパーのほとんどが、api プロジェクションを使用することになります。ただし携帯端末用アプリケーションを開発する場合は、API ドキュメントに記載されているリクエストのどのサンプルでも、「api」を「mobile」に置き換えることができます。同様に、フィード リーダーに最適な base プロジェクションを使用する場合は、API ドキュメントに記載されているリクエストのどのサンプルでも、「api」を「base」に置き換えることができます。

サポートされているプロジェクションの値を次の表に示します。

フィードのタイプ

YouTube Data API からは次のタイプのフィードを取得できます。

この API では、認証せずに上記のフィードを取得できます。ただし場合によって、認証済みのリクエストにより追加の情報が取得できます。たとえば、ユーザーごとのアップロードされた動画のリストに対して認証済みのリクエストを送信すると、フィードには非公開動画や拒否された動画、保留中の動画が含まれます。認証されていない API リクエストや、現在認証されているユーザー以外のユーザーがアップロードした動画のリクエストへのレスポンスには、非公開動画や、拒否されたまたは保留中の動画は含まれません。

動画、再生リスト、チャンネル登録、評価、コメントなどのエンティティを追加、更新するには、GET リクエストを含むすべてのリクエストで、デベロッパー キーと、AuthSub 認証か ClientLogin 認証を使用した認証が必要です。

動画フィード

動画フィードは、動画エントリのコレクションを返します。各動画エントリには、動画フィードの結果セットに含まれる個々の動画の情報が含まれます。YouTube Data API を使用すると、次のタイプの動画フィードを取得できます。

Videos feed

API は動画の検索リクエストへのレスポンスに、検索した動画のフィードを 1 つ返します。この検索した動画のフィードには、最大で 999 のエントリが含まれます。検索結果を取得するには、次の URL に API リクエストを送信します。

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

検索リクエストには、このドキュメントのクエリ パラメータの定義のセクションで定義されているどのクエリ パラメータ (time パラメータを除く) も使用できます。たとえば、次の URL では「skateboarding dog」に関連するすべての動画の検索結果の 21 番目から 10 件の結果を返すように要求します。

http://gdata.youtube.com/feeds/api/videos?
     vq=skateboarding+dog
     &start-index=21
     &max-results=10

Related videos feed

関連動画フィードには、ある動画に関連付けられた動画のリストが含まれます。YouTube では関連動画のセットがアルゴリズムにより選択されます。

API レスポンス内の各動画エントリには、一連の <link> タグが含まれます。rel 属性値が http://gdata.youtube.com/schemas/2007/#video.related の <link> タグは、その動画エントリに関連付けられた他の動画を取得する URL を示します。(<link> タグの href 属性がその URL を示します。)

<link rel="http://gdata.youtube.com/schemas/2007#video.related"
     type="application/atom+xml"
     href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/related"/>

関連動画フィードには、最大 100 本の動画が含まれます。

Video responses feed

動画レスポンス フィードには、別の動画へのレスポンスとして明示的に指定された動画が含まれます。1 本の動画を動画レスポンスとして指定できるのは、他の 1 本の動画に対してのみで、動画レスポンスのない動画もあります。

API レスポンス内の各動画エントリには、一連の <link> タグが含まれます。rel 属性値が http://gdata.youtube.com/schemas/2007/#video.responses の <link> タグは、その動画エントリの動画レスポンスを取得する URL を示します。(次の例に示すように、<link> タグの href 属性がその URL を示します。)

<link rel="http://gdata.youtube.com/schemas/2007#video.responses"
     type="application/atom+xml"
     href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/responses"/>

Standard feeds

標準フィードには、YouTube のユーザーの行動を反映する動画のリスト (評価の高い動画、人気の動画などのフィード) または YouTube スタッフが選択した動画のリスト (おすすめの動画、モバイル向け動画などのフィード) が含まれます。これらのフィードの多くは、YouTube ウェブサイトの [動画] タブに表示されます。

標準フィードを取得するには、そのフィードに関連付けられた URL に HTTP GET リクエストを送信します。各標準フィードに関連付けられた URL を次の表に示します。

地域固有の標準フィードの取得

この API では、標準フィードの URL に regionID を挿入することで、地域固有の標準フィードを取得できます。地域固有の標準フィードの取得に使用する URL フォーマットは次のとおりです。

http://gdata.youtube.com/feeds/api/standardfeeds/regionID/feedID

たとえば日本で評価の高い動画のリストを取得するには、次の URL に HTTP GET リクエストを送信します。

http://gdata.youtube.com/feeds/api/standardfeeds/JP/top_rated

注意: watch_on_mobile 標準フィードの地域固有のバージョンは使用できません。

次の表に、YouTube Data API が地域固有のフィードをサポートしている国と、その国に関連付けられた regionID を示します。

標準フィードでの time パラメータの使用

すべての標準フィードで time クエリ パラメータがサポートされており、前日、先週、または先月の関連する結果のみを含めるようにフィードを限定できます。たとえば前日の評価の高い動画を取得するには、次の URL に HTTP GET リクエストを送信します。

http://gdata.youtube.com/feeds/api/standardfeeds/top_rated?time=today

User's favorites feed

お気に入りの動画フィードには、特定のユーザーがお気に入りの動画として明示した動画のリストが取得されます。YouTube のウェブサイトでは、ユーザーは自分のアカウント ページで自分のお気に入りの動画のリストを表示、編集できます。ユーザーのお気に入りの動画は、YouTube の他のユーザーにも公開されます。

• 現在ログインしているユーザーのお気に入りの動画フィードを要求するには、次の URL に HTTP GET リクエストを送信します。注意: このリクエストの場合、Authorization HTTP リクエスト ヘッダーに認証トークンを指定する必要があります。認証トークンにより YouTube はユーザーを識別できます。

  http://gdata.youtube.com/feeds/api/users/default/favorites

• 別のユーザーのお気に入りの動画フィードを要求するには、次の URL に HTTP GET リクエストを送信します。このリクエストに認証は必要ありません。

  http://gdata.youtube.com/feeds/api/users/username/favorites

  上記の URL では、テキスト username をユーザーの YouTube ユーザー名で置き換える必要があります。

お気に入りフィードには、最大 50 件のエントリが返されます。start-index と max-results のクエリ パラメータを使用してフィードのページ番号を指定することで、レスポンスのサイズと待ち時間を最適化してください。max-results の推奨値は 10 です。この場合約 60 KB のデータを含むレスポンスが生成されます。

Playlist feed

再生リストフィードには、最大 200 本の動画のコレクションに関する情報が含まれ、順に表示できます。ユーザーは自分のアカウント ページで自分の複数の再生リストの一覧を表示、編集できます。ユーザーの再生リストは、YouTube の他のユーザーにも公開されます。さらに、ユーザーは、個々の再生リストに対して動画の追加、削除、変更ができます。

再生リストは、公開することも非公開にすることもできます。API を使用して、認証のあるなしにかかわらず、公開再生リストを取得できます。ただし、ユーザーの非公開再生リストは、そのユーザーが正しく認証され、再生リストの表示を認可された場合のみ取得できます。

再生リスト フィードを取得する前に、ユーザーの再生リスト フィードを取得します。これには、そのユーザーが作成した再生リストの一覧が含まれています。ユーザーの再生リスト フィードでは、各エントリは 1 つの再生リストを表します。(一方、再生リスト フィードは 1 つの再生リストに含まれる個々の動画を表します。)ユーザーの再生リスト フィードの各エントリには、URL を示す <gd:feedLink> タグが含まれ、この URL からその再生リストのフィードを取得できます。

<gd:feedLink rel='http://gdata.youtube.com/schemas/2007#playlist'
    href='http://gdata.youtube.com/feeds/api/playlists/PLAYLIST_ID'/>

注意: 実際の URL には PLAYLIST_ID の部分に再生リストを一意に識別する ID が含まれます。

ユーザーの再生リスト フィード

ユーザーの再生リスト フィードには、そのユーザーが作成した再生リストの一覧が含まれます。現在認証されているユーザーの再生リスト フィードを要求する場合、このフィードには公開と非公開の両方の再生リストが含まれます。認証されていないリクエストを送る場合や、現在認証されているユーザー以外のユーザーが作成した再生リストを要求する場合、そのフィードには公開再生リストしか含まれません。

ユーザーの再生リスト フィードの各 entry には、1 つの再生リストのタイトル、説明、投稿者などの情報が含まれます。エントリ内の <gd:feedLink> タグは、その再生リスト フィード (その再生リスト内の動画についての情報が含まれる) を取得できる URL を示します。

• 現在ログインしているユーザーの再生リスト フィードを要求するには、次の URL に HTTP GET リクエストを送信します。注意: このリクエストの場合、Authorization HTTP リクエスト ヘッダーに認証トークンを指定する必要があります。認証トークンにより YouTube はユーザーを識別できます。

  http://gdata.youtube.com/feeds/api/users/default/playlists

• 別のユーザーの再生リスト フィードを要求するには、次の URL に HTTP GET リクエストを送信します。このリクエストに認証は必要ありません。

  http://gdata.youtube.com/feeds/api/users/username/playlists

  上記の URL では、テキスト username をユーザーの YouTube ユーザー名で置き換える必要があります。

ユーザーのチャンネル登録フィード

ユーザーのチャンネル登録フィードには、ユーザーが登録したチャンネルのリスト、お気に入りの動画リスト、検索キーワードが含まれます。

• 現在ログインしているユーザーのチャンネル登録フィードを要求するには、次の URL に HTTP GET リクエストを送信します。注意: このリクエストの場合、Authorization HTTP リクエスト ヘッダーに認証トークンを指定する必要があります。認証トークンにより YouTube はユーザーを識別できます。

  http://gdata.youtube.com/feeds/api/users/default/subscriptions

• 別のユーザーのチャンネル登録フィードを要求するには、次の URL に HTTP GET リクエストを送信します。このリクエストには認証は必要ありません。

  http://gdata.youtube.com/feeds/api/users/username/subscriptions

  上記の URL では、テキスト username をユーザーの YouTube ユーザー名で置き換える必要があります。

チャンネル登録フィードの各 entry には、個々のチャンネル登録についての情報が含まれます。各エントリに含まれる主なタグは次のとおりです。

• エントリ内の <gd:feedLink> タグは、そのチャンネル登録の動画を取得できる URL を示します。

• エントリ内の <category> タグには scheme 属性の値が http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat になるタグが 1 つあります。そのタグの term 属性は、エントリがチャンネルの登録 (term="channel")、別のユーザーのお気に入りの動画リスト (term="favorites")、特定のキーワードに一致する動画 (term="query") のどれかであることを示します。

• 別のユーザーのチャンネルまたはお気に入りの動画リストへのチャンネル登録の場合、そのチャンネルまたはお気に入りの動画リストを所有するユーザーを <yt:username> タグが示します。

  検索キーワードのチャンネル登録の場合、登録されたキーワードは <yt:queryString> タグに含まれます。

動画のコメント フィード

各動画エントリには <gd:comments> タグが含まれます。動画のコメント リストを取得または追加する API リクエストの送信先の URL がこのタグに含まれます。下記の XML のサンプルは、この URL が動画フィードにどのように含まれるかを示します。

<feed>
  <entry>
    ...
    <media:group>
      ...
    </media:group>
    <gd:comments>
      <gd:feedLink href='http://gdata.youtube.com/feeds/api/videos/VIDEO_ID/comments'/>
    </gd:comments>
  </entry>
</feed>

コメント フィードの各エントリには、個々のコメントの情報が含まれます。各コメントには、投稿者、タイトル、コンテンツがあります。

ユーザー プロフィール エントリ

ユーザー プロフィールには、ユーザーが YouTube のプロフィール ページに記載している情報が含まれています。

• 現在ログインしているユーザーのプロフィールを要求するには、次の URL に HTTP GET リクエストを送信します。注意: このリクエストの場合、Authorization HTTP リクエスト ヘッダーに認証トークンを指定する必要があります。この認証トークンにより、YouTube はユーザーを識別できます。

  http://gdata.youtube.com/feeds/api/users/default

• 別のユーザーのプロフィールを要求するには、次の URL に HTTP GET リクエストを送信します。このリクエストに認証は必要ありません。

  http://gdata.youtube.com/feeds/api/users/username

  上記の URL では、テキスト username をユーザーの YouTube ユーザー名で置き換える必要があります。扱っている YouTube API レスポンスのタイプによって、ユーザー名は <name> タグまたは <yt:username> タグに含まれます。

注意: API レスポンスの多くには、複数のエントリのレスポンス フィードやリストの情報が含まれますが、プロフィールを取得するリクエストには、1 つのエントリしか返されません。そのため、このリクエストの API レスポンスのルート タグは <entry> になります。

ユーザーのコンタクト フィード

ユーザーのコンタクト フィードには、指定したユーザーのすべてのコンタクトのリストが含まれます。

• 現在ログインしているユーザーのコンタクト リストを要求するには、次の URL に HTTP GET リクエストを送信します。注意: このリクエストの場合、Authorization HTTP リクエスト ヘッダーに認証トークンを指定する必要があります。認証トークンにより YouTube はユーザーを識別できます。

  http://gdata.youtube.com/feeds/api/users/default/contacts

• 別のユーザーのコンタクト リストを要求するには、次の URL に HTTP GET リクエストを送信します。このリクエストには認証は必要ありません。

  http://gdata.youtube.com/feeds/api/users/username/contacts

  上記の URL では、テキスト username をユーザーの YouTube ユーザー名で置き換える必要があります。

コンタクトは Friends か Family のどちらかに分類されます。

フィード間の移動

どのフィードやエントリでも、関連するフィードやエントリへのリンクが含まれる <link rel="relationshipID"> タグや <gd:feedLink rel="relationshipID"> 要素が使用されます。通常、<link> タグは関連するフィード間の関係 (ネスト以外) を識別します。一方 <gd:feedLink> タグは、全体のフィードが大きくなりすぎるためにネストされていない (そうでなければネストされていたかもしれない) フィードを示します。

これらのタグが示す URL を使用すると、アプリケーション内に URL をハードコーディングせずに API の機能を実装できます。たとえば、次の <link> 要素は動画エントリの中に含まれ、そのエントリの動画レスポンスを含むフィードへのリンクを提供します。

<link rel="http://gdata.youtube.com/schemas/2007#video.responses" 
    type="application/atom+xml" 
    href="http://gdata.youtube.com/feeds/api/videos/UwOA8H5Vaak/responses"/>

同様に、次の <gd:feedLink> 要素はユーザー プロフィール エントリに含まれます。このタグは、ユーザーのコンタクト フィードを取得する URL を示します。

<gd:feedLink 
    rel="http://gdata.youtube.com/schemas/2007#user.contacts" 
    href="http://gdata.youtube.com/feeds/api/users/liz/contacts"/>

デベロッパー ガイド: Data API プロトコルのユース ケースでは、異なるフィード間の移動方法を説明します。さらに下記の図は、YouTube Data API フィード間の相互接続を示します。実線の各矢印は <link> 要素を示し、点線の各矢印は <gd:feedLink> 要素を示します。青の各矢印は <link rel="related"> リンクを示します。チャンネル登録エントリには、そのエントリが示す登録のタイプに応じて、数種類のフィードのどれかを示す <gd:feedLink> タグが含まれる場合があります。

各円の最後の単語は、そのフィード内のエントリの Google Data の「タイプ」を示します。たとえば、チャンネル登録フィードには「subscription」タイプのエントリが含まれ、「videos」フィードには「video」タイプのエントリが含まれます。

YouTube Data API リクエストに対する HTTP レスポンス コード

このセクションでは、さまざまなタイプの API リクエストに YouTube が返す HTTP レスポンス コードについて説明します。

フィードの取得

• 200 レスポンス コードは、フィードを取得する HTTP GET リクエストを YouTube が正常に処理したことを示します。

• 400 レスポンス コードは、正しくないリクエストを示します。たとえば誤った URL にリクエストを送信した場合や、リクエストの中にサポートされていないまたは存在しないパラメータを含めた場合に、400 レスポンス コードを受け取ります。API レスポンスのコンテンツには、API が 400 レスポンス コードを返した理由が含まれます。

動画のアップロード

• ブラウザ ベースのアップロード

  • 200 - 動画のメタデータを正常にアップロードすると、API から 200 レスポンス コードが返されます。この処理について、デベロッパー ガイドの動画メタデータのアップロードのセクションで詳しく説明しています。

  • 301 - アプリケーションのサイトのフォームを通じてユーザーが実際の動画ファイルを直接 YouTube にアップロードする際、YouTube は 301 リダイレクトをユーザーのブラウザに送信します。このリダイレクトによって、ブラウザはアプリケーションのアップロード フォームの nexturl パラメータで指定された URL のページに移動します。 (アップロード フォームの詳しい説明をご覧ください)。YouTube では、その URL に下記の変数を付加するので、アプリケーションは、ユーザに適切な情報を提供するためにこれらの変数を取り出す必要があります。

    • id - このリクエスト パラメータは新しく作成された動画の動画 ID を示します。
    • status - このリクエスト パラメータは、ユーザーの動画が正常にアップロードされたかを示します。動画が正常にアップロードされると、値は 200 になります。アップロードが正常に終了しなかった場合の値は、4xx か 5xx (400、403、503 など) になります。
    • code - このリクエスト パラメータはアップロードが失敗した理由の詳細を指定します。このパラメータに含まれる可能性のある値は、「INVALID_TOKEN」、「MISSING_TOKEN」、「DUPLICATE」、「TOKEN_EXPIRED」、「FILE_MISSING」です。

• 直接アップロード

  • 201 - 動画のアップロードが正常に終了すると、API は 201 レスポンス コードを返します。

  • 400 (誤ったリクエスト) - 400 レスポンス コードは、リクエストの形式が誤っているか、無効な値が含まれていることを示します。たとえばリクエストに誤った形式の XML が含まれていた場合や、無効な文字を含むキーワードを登録しようとした場合、API は 400 レスポンス コードを返します。

HTTP POST による情報の追加

リソース (評価、コメント、動画レスポンス、苦情、お気に入りの動画、再生リスト、再生リスト エントリ、チャンネル登録、コンタクトなど) を追加するリクエストに対して、API は次のレスポンス コードを返します。

• 201 (作成) - 201 レスポンス コードは評価、コメント、苦情、動画レスポンス、チャンネル登録、再生リスト、コンタクトのどれかを追加する HTTP POST リクエストが正常に処理されたことを示します。

• 400 (誤ったリクエスト) - 400 レスポンス コードは、リクエストの形式が誤っているか、無効な値が含まれていることを示します。たとえば、リクエストに誤った形式の XML が含まれていた場合や、動画の評価として「16」を登録しようとした場合 (評価は 1～5 であることが必要)、API は 400 レスポンス コードを返します。API レスポンスのコンテンツには、API が 400 レスポンス コードを返した理由が含まれます。

HTTP PUT による情報の更新

リソース (動画、再生リスト、再生リスト エントリ、コンタクトなど) を更新するリクエストに対して、API は下記のレスポンス コードを返します。

• 200 (OK) - 200 レスポンス コードはリソースを更新する HTTP PUT リクエストが正常に処理されたことを示します。

• 400 (誤ったリクエスト) - 400 レスポンス コードは、リクエストの形式が誤っているか、無効な値が含まれていることを示します。API レスポンスのコンテンツには、API が 400 レスポンス コードを返した理由が含まれます。

HTTP DELETE によるリソースの削除

リソース (動画、動画レスポンス、お気に入りの動画、再生リスト、再生リスト エントリ、チャンネル登録、コンタクトなど) を削除するリクエストに対して、API は下記のレスポンス コードを返します。

• 200 (OK) - 200 レスポンス コードは、リソースを削除する HTTP DELETE リクエストを YouTube が正常に処理したことを示します。

• 401 (無許可) - 401 レスポンス コードは、リクエストに Authorization ヘッダーが含まれていないか、Authorization ヘッダーのフォーマットが無効か、ヘッダーに指定された認証トークンが無効であることを示します。

• 403 (禁止) - 403 レスポンス コードは、送信したリクエストが、要求している操作に対して正しく認証を受けていないことを示します。

• 404 (不明) - 404 レスポンス コードは、変更しようとしたリソースが存在しないことを示します。たとえば、チャンネル登録を削除しようとしてその登録の URL を誤って指定した場合に、404 レスポンス コードを受け取ります。

正常に終了しなかったリクエストのその他のレスポンス コード

API が次のレスポンス コードを返す場合もあります。

• 401 (無許可) - 401 レスポンス コードは、リクエストに Authorization ヘッダーが含まれていないか、Authorization ヘッダーのフォーマットが無効か、ヘッダーに指定された認証トークンが無効であることを示します。

• 403 (禁止) - 403 レスポンス コードは、送信したリクエストが、要求している操作に対して正しく認証を受けていないことを示します。

• 500 (内部エラー) - 500 レスポンス コードは、リクエストの処理中に YouTube でエラーが発生したことを示します。後で要求し直すことができます。

• 501 (未実装) - 501 レスポンス コードは、サポートされていない操作 (評価のリストの取得、苦情の更新など) を試みたことを示します。

• 503 (利用できないサービス) - 503 レスポンス コードは、その YouTube Data API サービスが利用できないことを示します。後で要求し直すことができます。

動画の検索

動画を検索するには、次の URL にリクエストに合わせてクエリ パラメータを付加し、HTTP GET リクエストを送信します。

http://gdata.youtube.com/feeds/api/videos

たとえば次の URL へのリクエストでは、検索キーワード「football」に一致し、キーワード「soccer」には一致しない最近アップロードされた動画の 10 本ずつのセットの 2 番目のセットを検索します。

http://gdata.youtube.com/feeds/api/videos?
    vq=football+-soccer
    &orderby=published
    &start-index=11
    &max-results=10

クエリ パラメータの定義

Standard Google Data API parameters

YouTube Data API では、次の標準の Google Data クエリ パラメータをサポートしています。

標準の Google Data API の機能や上記の特定のパラメータについての詳細は、Google Data APIs Protocol Reference をご覧ください。

Custom parameters for the YouTube Data API

標準の Google Data クエリ パラメータに加えて、YouTube Data API では次の API 固有のクエリ パラメータを定義しています。これらのパラメータは、動画フィードと再生リスト フィードに対してのみ使用できます。

動画フィードでのカテゴリ検索

YouTube の動画は次のように分類できます。

• 動画はそれぞれ、あらかじめ定義された YouTube カテゴリ (コメディー、音楽、ニュース、スポーツなど) のいずれかに関連付けることができます。動画のカテゴリは、<media:category> タグと、scheme 属性値が http://gdata.youtube.com/schemas/2007/categories.cat の <category> タグで識別されます。

• 動画はそれぞれ、任意の数のキーワード (タグとも呼ばれる) に関連付けることができます。動画のタグは、API のリクエストとレスポンスの中で <media:keywords> タグを使用して指定されます。キーワード タグは、scheme 属性値が http://gdata.youtube.com/schemas/2007/keywords.cat の <category> タグでも識別されます。

• 動画はそれぞれ、任意の数のデベロッパー タグに関連付けることができます。デベロッパー タグを使用して動画を検索できます。ただし、デベロッパー タグは YouTube のウェブサイト上には表示されないので、アプリケーションでも表示しないでください。動画のデベロッパー タグは、<media:category> タグと、scheme 属性値が http://gdata.youtube.com/schemas/2007/developertags.cat の <category> タグで識別されます。

  デベロッパー タグの割り当てについて詳しくは、デベロッパー ガイド: Data API プロトコルをご覧ください。

特定のカテゴリ内の動画、または特定のキーワードかデベロッパー タグに関連付けられた動画を取得するには、次の URL を使用します。

http://gdata.youtube.com/feeds/api/videos/-/category_or_tag

URL 内のハイフン (-) は標準の Google Data API の表記法で、URL の残りの部分が 1 つ以上の一連のタグから構成されることを示します。特定のカテゴリやタグに関連付けられた動画を要求する際の、詳しいガイドラインは次のとおりです。

• リクエストに、カテゴリと 1 つ以上のキーワードを指定する場合、またはカテゴリは指定せずに複数のキーワードを指定する場合、カテゴリやキーワード名はそれぞれスラッシュで区切ります。たとえばキーワード「bass」と「fishing」に関連する動画を要求するには、次の URL を使用します。

  http://gdata.youtube.com/feeds/api/videos/-/bass/fishing

• リクエストにはブール型演算子の NOT (-) と OR (|) を使用して、動画を除外することや、複数の検索キーワードとカテゴリのどれかに関連付けられた動画を検索することができます。たとえば、「bass」と「music」に関連する動画を表示する場合、最も効果的な検索として、下記の例に示すように、キーワード「bass」に関連付けられ、キーワード「fish」や「fishing」には関連付けられていない動画を検索することが考えられます。(「Music」のカテゴリとキーワード「bass」に関連付けられた動画を検索すると、ベース (bass) の演奏法についての教育的な動画は除外されてしまうかもしれません。)

  http://gdata.youtube.com/feeds/api/videos/-/bass/-fish/-fishing

  次の例では、「Sports」または「Howto」のどちらかのカテゴリにある野球 (baseball) の動画を検索する方法を示します。カテゴリ名は、値「%7C」で区切ります。これは URL エンコードのパイプ (|) 文字を表し、動画が 2 つのカテゴリのどちらかに関連付けられている必要があることを指定します。

  http://gdata.youtube.com/feeds/api/videos/-/Sports%7CHowto/baseball

• カテゴリ名は最初の文字を大文字にし、キーワード名は小文字にします。たとえば次のクエリでは、キーワード「comedy」に関連付けられていて「Comedy」カテゴリには含まれない動画を識別します。

  http://gdata.youtube.com/feeds/api/videos/-/comedy/-Comedy

• API レスポンス内の情報に基づいて、自動的にカテゴリやキーワードの検索を生成する場合、カテゴリ名の部分にスキーマを指定して、YouTube カテゴリをキーワード タグやデベロッパー タグと明確に区別します。次の URL では、カテゴリ名にスキーマを指定する方法を示します。

  http://gdata.youtube.com/feeds/api/videos/-/%7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007%2Fcategories.cat%7DNews
  http://gdata.youtube.com/feeds/api/videos/-/%7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007%2Fkeywords.cat%7Ddog
  http://gdata.youtube.com/feeds/api/videos/-/%7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007%2Fdevelopertags.cat%7Dexample.com
  

• 特定のデベロッパー タグに関連付けられた動画を要求する場合は、前の項目で説明したように、常にスキーマを指定します。

XML 要素の定義

YouTube Data API では、複数の XML スキーマのタグを使用します。次の表に、この API が使用するさまざまなスキーマ、各スキーマに対応する名前空間のプレフィックス、各スキーマの名前空間の URL を示します。

下記のセクションでは、YouTube Data API のリクエストとレスポンスに使用される上記の各スキーマの XML タグを定義します。各セクションでは個々のタグを定義し、タグはスキーマごとにアルファベット順にリストアップされます。

下記の定義では、子タグの横に記号が表示されている場合があります。これらの記号は、それぞれ次のような意味があります。

Atom 要素 リファレンス

author

<author>

category

<category scheme='http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat' term='channel'/>

content

<content type="text">Video comments are cool.</content>

entry

<entry>

feed

<feed xmlns='http://www.w3.org/2005/Atom' xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/' xmlns:media='http://search.yahoo.com/mrss/' xmlns:yt='http://gdata.youtube.com/schemas/2007' xmlns:gd='http://schemas.google.com/g/2005'>

generator

<generator version='beta' uri='http://gdata.youtube.com/'>YouTube data API</generator>

id

<id>http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions/5c56f45db338111c</id>

link

<link rel='http://gdata.youtube.com/schemas/2007#video.related' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/AlPqL7IUT6M/related'/>

logo

<logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo>

name

<name>andyland74</name>

published

<published>2007-10-15T15:39:34.000-07:00</published>

title

<title type='text'>andyland74's Subscriptions</title>

updated

<updated>2007-10-15T15:39:34.000-07:00</updated>

uri

<uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri>

OpenSearch 要素 リファレンス

openSearch:itemsPerPage

<openSearch:itemsPerPage>25</openSearch:itemsPerPage>

openSearch:startIndex

<openSearch:startIndex>1</openSearch:startIndex>

openSearch:totalResults

<openSearch:totalResults>36</openSearch:totalResults>

YouTube 要素 リファレンス

yt:age

<yt:age>33</yt:age>

yt:books

<yt:books>Catch-22</yt:books>

yt:company

<yt:company>Google</yt:company>

yt:description

<yt:description>My new playlist description</yt:description>

yt:duration

<yt:duration seconds='344'/>

yt:firstName

<yt:firstName>John</yt:firstName>

yt:gender

<yt:gender>m</yt:gender>

yt:hobbies

<yt:hobbies>Testing YouTube APIs</yt:hobbies>

yt:hometown

<yt:hometown>Albany, GA</yt:hometown>

yt:lastName

<yt:lastName>Smith</yt:lastName>

yt:location

<yt:location>US</yt:location>

yt:movies

<yt:movies>Aqua Teen Hungerforce</yt:movies>

yt:music

<yt:music>Elliott Smith, the Kooks</yt:music>

yt:noembed

<yt:noembed/>

yt:occupation

<yt:occupation>Technical writer</yt:occupation>

yt:position

<yt:position>4</yt:position>

yt:private

<yt:private/>

yt:queryString

<yt:queryString>Dog skateboarding</yt:queryString>

yt:racy

<yt:racy/>

yt:recorded

<yt:recorded>2003-08-03</yt:recorded>

yt:relationship

<yt:relationship>taken</yt:relationship>

yt:school

<yt:school>University of North Carolina</yt:school>

yt:state

<yt:state name="rejected" reasonCode="tooLong" helpUrl="http://www.youtube.com/t/community_guidelines">Video is too long</yt:state>

yt:statistics

<yt:statistics viewCount='9' videoWatchCount='24' subscriberCount='1' lastWebAccess='2008-02-29T13:09:48.000-08:00'/>

yt:status

<yt:status>accepted</yt:status>

yt:username

<yt:username>andyland74</yt:username>

Media RSS 要素 リファレンス

media:category

<media:category label='Sports' scheme='http://gdata.youtube.com/schemas/2007/categories.cat'>Sports</media:category>

media:content

<media:content url='http://www.youtube.com/v/8aYQ_wjmriQ' type='application/x-shockwave-flash' medium='video' isDefault='true' expression='full' duration='166' yt:format='5'/>

media:description

<media:description type="plain">Granny takes crocheting to the extreme during a rodeo and while surfing.</media:description>

media:group

<media:group>

media:keywords

<media:keywords>rodeo, surfing, crochet</media:keywords>

media:player

<media:player url='http://www.youtube.com/watch?v=8aYQ_wjmriQ'/>

media:thumbnail

<media:thumbnail url='http://img.youtube.com/vi/8aYQ_wjmriQ/2.jpg' height='97' width='130' time='00:01:23'/>

media:title

<media:title type="plain">Extreme crocheting in high surf, rodeo</media:title>

GData 要素 リファレンス

gd:comments

<gd:comments>

gd:feedLink

<gd:feedLink href='http://gdata.youtube.com/feeds/api/videos/8aYQ_wjmxiQ/comments' countHint='0'/>

gd:rating

<gd:rating min='1' max='5' numRaters='7773' average='4.75'/>

GeoRSS 要素 リファレンス

georss:where

<georss:where>

GML 要素 リファレンス

gml:Point

<gml:Point>

gml:pos

<gml:pos>47.367 8.55</gml:pos>

Atom Publishing Protocol 要素 リファレンス

app:control

<app:control>

app:draft

<app:draft>yes</app:draft>

ブラウザ ベースのアップロード API レスポンス 要素 リファレンス

response

<response>

token

<token>AEwbFAQEvf3xox...</token>

url

<url>http://uploads.gdata.youtube.com/action/FormUpload/AEF3087AUD</url>

エラー レスポンス 要素 リファレンス

code

<code>required</code>

domain

<domain>yt:validation</domain>

error

<error>

errors

<errors>

location

<location type='xpath'>media:group/media:title/text()</location>

補足情報

アップロードする動画のカテゴリ リスト

YouTube カテゴリ ドキュメント ( http://gdata.youtube.com/schemas/2007/categories.cat からダウンロード可能) では、動画のコンテンツの分類に使用できるカテゴリが指定されています。このカテゴリ ドキュメントは XML ファイルで、カテゴリを指定し、新しい動画を各カテゴリに割り当てられるかどうかと、各カテゴリを YouTube で閲覧できるかどうかを示します。

下記の抜粋では、2008 年 1 月 2 日現在の YouTube カテゴリ ドキュメントに含まれる「Entertainment」と「Nonprofit & Activism」のカテゴリのエントリを示します。どちらのカテゴリにも動画を割り当てることができますが、その時点で閲覧できるのは Entertainment カテゴリのみです。例に示すように、<yt:browsable> タグが存在することは、対応するカテゴリが YouTube で閲覧できることを示し、<yt:assignable> タグが存在することは、そのカテゴリに新しい動画を割り当てられることを示します。(<yt:assignable> タグを使用した割り当て可能のマークの付いていないカテゴリには、新しい動画を割り当てられません。)

<atom:category term='Entertainment' label='Entertainment'>
  <yt:browsable/>
  <yt:assignable/>
</atom:category>
<atom:category term='Nonprofit' label='Nonprofit & Activism'>
  <yt:assignable/>
</atom:category>

アップロード API リクエストでは、<media:category> タグの値を、対応するカテゴリの <atom:category> タグの term 属性の値に設定する必要があります。次の例では、<media:category> タグを使用して、上記のスキーマの抜粋に含まれる Nonprofit & Activism カテゴリに新しい動画を割り当てる方法を示します。

<media:category
  scheme="http://gdata.youtube.com/schemas/2007/categories.cat">Nonprofit</media:category>

URL エスケープ

HTTP 検索リクエストを作成するには、Google で HTTP リクエストが正しく解釈され、適切なレスポンスが生成されるように、特定の表記法に従う必要があります。

HTTP URL スキーマでは、HTTP URL リクエストに次の文字のみを含めるように規定しています。

• 英数字: [a-z][A-Z][0-9]
• 特殊文字: $ - _ . | + ! * ' ( )
• 予約文字: ; / ? : @ = &

Google では、URL のデコードに予約文字を使用し、検索機能のリクエストに特殊文字の一部を使用します。したがって、検索パラメータの値に含まれる英数字以外の文字はすべて URL エスケープを行う必要があります。

文字列の URL エスケープを行うには、一連の空白文字を 1 つの「+」(プラス記号) に変換し、その他の英数字以外の文字はその文字の値を表す 16 進エンコードに置き換えます。上記の特殊文字や予約文字の 16 進エンコードを、次の表に示します。上記の各文字に対して、リクエスト パラメータの値の中では、URL エスケープを行う必要があります。

Examples

URL エスケープについて詳しくは、RFC 2396 と W3C をご覧ください。