Videos: list

API リクエストのパラメータに一致する動画のリストを返します。

割り当てへの影響: このメソッドを呼び出すと、1 ユニットの割り当てコストが発生します。

一般的なユースケース

リクエスト

HTTP リクエスト

GET https://www.googleapis.com/youtube/v3/videos

パラメータ

次の表に、このクエリでサポートされているパラメータを示します。このリストのパラメータはすべてクエリ パラメータです。

パラメータ
必須パラメータ
part string
part パラメータは、API レスポンスに含める 1 つ以上の video リソース プロパティのカンマ区切りのリストを指定します。

パラメータが子プロパティを含むプロパティを識別する場合、子プロパティはレスポンスに含まれます。たとえば、video リソースでは、snippet プロパティに channelId、title、description、tags、categoryId プロパティが含まれています。そのため、part=snippet を設定すると、API レスポンスにはそれらのプロパティがすべて含まれます。

次のリストは、パラメータ値に含めることができる part 名を示しています。
  • brandPartner
  • contentDetails
  • fileDetails
  • id
  • liveStreamingDetails
  • localizations
  • paidProductPlacementDetails
  • player
  • processingDetails
  • recordingDetails
  • snippet
  • statistics
  • status
  • suggestions
  • topicDetails
フィルタ （次のパラメータのいずれか 1 つを指定）
chart string
chart パラメータは、取得するチャートを指定します。

使用できる値は次のとおりです。
id string
id パラメータは、取得するリソースの YouTube 動画 ID のカンマ区切りのリストを指定します。video リソースの id プロパティは、動画の ID を指定します。
myRating string

このパラメータは、適切に承認されたリクエストでのみ使用できます。このパラメータの値を like または dislike に設定すると、認証済みユーザーが高評価または低評価した動画のみを返すよう API に指示できます。



API は、返される結果セットを最大 1,000 件の動画に制限します。レスポンスの pageInfo.totalResults プロパティでより大きな合計が示されている場合でも、pageToken パラメータを使用したページネーションでは、最新の 1, 000 個のアイテムのみを取得できます。



このパラメータは次の値を受け入れます。

  • dislike - 認証済みユーザーが低評価した動画のみを返します。
  • like - 認証済みユーザーが高く評価した動画のみを返します。
オプション パラメータ
hl string
hl パラメータは、YouTube ウェブサイトがサポートする特定のアプリ言語のローカライズされたリソース メタデータを取得するよう API に指示します。パラメータ値は、i18nLanguages.list メソッドから返されるリストに含まれる言語コードにする必要があります。

その言語でローカライズされたリソースの詳細が利用可能な場合、リソースの snippet.localized オブジェクトにはローカライズされた値が含まれます。ただし、ローカライズされた詳細が利用できない場合、snippet.localized オブジェクトにはリソースのデフォルト言語のリソースの詳細が含まれます。
maxHeight unsigned integer
maxHeight パラメータは、player.embedHtml プロパティで返される埋め込みプレーヤーの最大高さを指定します。このパラメータを使用すると、デフォルトのディメンションではなく、アプリケーション レイアウトに適した高さを使用するように埋め込みコードを指定できます。maxWidth パラメータも指定されている場合、最大幅を超えないように、プレーヤーの高さが maxHeight より短くなることがあります。有効な値は 72～8192 です。
maxResults unsigned integer
maxResults パラメータは、結果セットで返されるアイテムの最大数を指定します。

注: このパラメータは、myRating パラメータと組み合わせて使用できますが、id パラメータと組み合わせて使用することはできません。有効な値は 1～50 です。デフォルト値は 5 です。
maxWidth unsigned integer
maxWidth パラメータは、player.embedHtml プロパティで返される埋め込みプレーヤーの最大幅を指定します。このパラメータを使用すると、デフォルトのサイズではなく、アプリケーション レイアウトに適した幅を埋め込みコードで使用するように指定できます。

maxHeight パラメータも指定されている場合、最大高さを超えないように、プレーヤーの幅が maxWidth より狭くなることがあります。有効な値は 72 から 8192 です。
onBehalfOfContentOwner string
このパラメータは、適切に承認されたリクエストでのみ使用できます。注: このパラメータは、YouTube コンテンツ パートナー専用です。

onBehalfOfContentOwner パラメータは、リクエストの認証情報が、パラメータ値で指定されたコンテンツ所有者の代理として動作する YouTube CMS ユーザーを識別することを示します。このパラメータは、複数の YouTube チャンネルを所有、管理している YouTube コンテンツ パートナーを対象にしています。このパラメータを使用すると、コンテンツ所有者は一度認証されれば、すべての動画やチャンネル データにアクセスできるようになります。チャンネルごとに認証情報を指定する必要はありません。ユーザー認証に使用する CMS アカウントは、指定された YouTube コンテンツ所有者にリンクされていなければなりません。
pageToken string
pageToken パラメータは、返される結果セット内の特定のページを識別します。API レスポンスでは、nextPageToken プロパティと prevPageToken プロパティで、取得可能な他のページを識別します。

注: このパラメータは myRating パラメータと組み合わせて使用できますが、id パラメータと組み合わせて使用することはできません。
regionCode string
regionCode パラメータは、指定された地域で利用可能な動画チャートを選択するよう API に指示します。このパラメータは、chart パラメータと組み合わせてのみ使用できます。パラメータ値は ISO 3166-1 alpha-2 形式の国コードです。
videoCategoryId string
videoCategoryId パラメータは、チャートを取得する動画カテゴリを識別します。このパラメータは、chart パラメータと組み合わせてのみ使用できます。デフォルトでは、グラフは特定のカテゴリに制限されていません。デフォルト値は 0 です。

リクエストの本文

このメソッドを呼び出す場合は、リクエストの本文を指定しないでください。

Response

成功すると、このメソッドは次の構造を含むレスポンスの本文を返します。

{
  "kind": "youtube#videoListResponse",
  "etag": etag,
  "nextPageToken": string,
  "prevPageToken": string,
  "pageInfo": {
    "totalResults": integer,
    "resultsPerPage": integer
  },
  "items": [
    video Resource
  ]
}

プロパティ

次の表は、このリソースで使用されているプロパティの定義を示したものです。

プロパティ
kind string
API リソースのタイプを識別します。値は youtube#videoListResponse になります。
etag etag
このリソースの Etag。
nextPageToken string
結果セットの次のページを取得するために pageToken パラメータの値として使用できるトークン。
prevPageToken string
結果セットの前のページを取得するために pageToken パラメータの値として使用できるトークン。
pageInfo object
pageInfo オブジェクトは、結果セットのページング情報をカプセル化します。
pageInfo.totalResults integer
結果セット内の結果の総数。
pageInfo.resultsPerPage integer
API レスポンスに含まれる結果の数です。
items[] list
リクエスト条件に一致する動画のリスト。

エラー

次の表に、このメソッドの呼び出しに対して API から返されるエラー メッセージを示します。詳細については、エラー メッセージのドキュメントをご覧ください。

エラーのタイプ エラーの詳細 説明
badRequest (400) videoChartNotFound リクエストされた動画チャートはサポートされていないか、使用できません。
forbidden (403) forbidden リクエストに、動画ファイルまたは処理情報にアクセスするための適切な認可がありません。fileDetails、processingDetails、suggestions の部分は、その動画の所有者のみが利用できます。
forbidden (403) forbidden リクエストは、ユーザー評価情報にアクセスできません。このエラーは、myRating パラメータを使用するリクエストが適切に承認されていない場合に発生することがあります。
notFound (404) videoNotFound 取得しようとしている動画が見つかりません。リクエストの id パラメータの値が正しいことを確認します。

試してみよう:

APIs Explorer を使用してこの API を呼び出し、API リクエストとレスポンスを確認します。