YouTube Data API v3

導入

APIキー (API keys)

APIの利用にはAPIキーが必要です。これを作成するにはGoogle Developers Consoleを開き、まず[Create Project]からプロジェクトを作成します。

次に作成したプロジェクトのページを開き、[Enable an API]をクリックします。

[YouTube Data API v3]の右にある[OFF]をクリックして、STATUSを[ON]にします。

利用条件への同意を求められます。これに同意すると、このAPIが有効となります。

続けて左のサイドバーの[Credentials]をクリックします。そして[Create new Key]をクリックします。

用途に合わせたキーを選択します。ここでは[Server Key]を選択するものとします。

リクエストを許可するサーバーのIPアドレスを入力します。テストと本番で異なるIPアドレスからアクセスするならば、それら複数の登録が必要です。複数のアドレスは、1行に1つずつ記述します。

作成したキーは、先ほどの[Credentials]のページの表にある[API KEY]で確認できます。

なお作成したキーが有効となるまで、少し時間がかかります。

Google Cloud Platformでは、この情報は認証情報 – API とサービスで確認できます。

APIキーに関するエラー

APIキーを指定しなかった場合は、次のようにレスポンスがあります。

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "reason": "dailyLimitExceededUnreg",
    "message": "Daily Limit for Unauthenticated Use Exceeded. Continued use requires signup.",
    "extendedHelp": "https://code.google.com/apis/console"
   }
  ],
  "code": 403,
  "message": "Daily Limit for Unauthenticated Use Exceeded. Continued use requires signup."
 }
}
https://www.googleapis.com/youtube/v3/search?part=id

許可していないIPアドレスからアクセスした場合には、次のようになります。許可した直後にも、このように返される場合があります。

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "reason": "accessNotConfigured",
    "message": "Access Not Configured. Please use Google Developers Console to activate the API for your project."
   }
  ],
  "code": 403,
  "message": "Access Not Configured. Please use Google Developers Console to activate the API for your project."
 }
}

OAuthのID

OAuthのIDを入手する手順は、基本的にAPIキーのそれと同じです。違いはCredentialsのページからの操作で、ここで[Create new Client ID]をクリックします。

利用制限

APIのリクエスト数には制限が設けられています。それはユニットという単位で規定され、リクエストごとに消費されていきます。クォータの使用量 - YouTube Data API の概要 | YouTube Data API (v3) | Google Developers

たとえば検索では1回のリクエストで100ユニット消費されることから、1日で検索できるのは500,000回までです。

この割り当ての「Queries /日 (Queries per day)」が予期せず0となった場合には、プロジェクトを作成し直します。YouTube Queries per day becomes to 0 - Stack Overflow

ライブラリ

Data APIを各種言語から簡単に利用するための、ライブラリが用意されています。

JavaScript

JavaScriptのライブラリからData APIにアクセスするには、Google Developers ConsoleのJAVASCRIPT ORIGINSの設定が重要で、これが正しくないと「origin_mismatch」としてエラーとなります。

参考

参考

APIの利用方法

基本的に、次のようにAPIのURLへリクエストします。

操作 https://www.googleapis.com/youtube/v3/リソース?クエリ

各種のリクエストに対するレスポンスは、YouTube Data API v3 - Google APIs Explorerで確認できます。

操作 (operations)

操作 (operations) はHTTPメソッドであり、リソースに対する操作によって下表のように使い分けます。

リソースに対する操作 メソッド APIでの用語
リソースを取得 GET list
リソースを作成 POST insert
リソースを変更 PUT update
リソースを削除 DELETE delete

リソース (resources) には次項の文字列を指定します。このとき、そのリソースがサポートされる操作に注意が必要です。

リソース (resources)

リソース サポートされる操作
表記 意味 list insert update delete その他
activities アクティビティ ○ ○ × ×  
Captions   ○ ○ ○ ○ download
channelBanners チャンネルバナー × ○ × ×  
channelSections   ○ ○ ○ ○  
channels チャンネル ○ × × ×  
CommentThreads   ○ ○ ○ ×  
Comments   ○ ○ ○ ○ markAsSpam、setModerationStatus
guideCategories ガイドカテゴリ ○ × × ×  
i18nLanguages 国際化言語 ○ × × ×  
i18nRegions 国際化地域 ○ × × ×  
liveBroadcasts   ○ ○ ○ ○ bind、control、transition
liveStreams   ○ ○ ○ ○  
playlistItems 再生リストの項目 ○ ○ ○ ○  
playlists 再生リスト ○ ○ ○ ○  
search 検索 ○ × × ×  
subscriptions サブカテゴリ ○ × × ×  
thumbnails サムネイル × × × ×  
VideoAbuseReportReasons   ○ × × ×  
videoCategories 動画カテゴリ ○ × × ×  
videos 動画 ○ ○ ○ ○  
watermarks ウォーターマーク × × × × set、unset
リソースの種類 - API Reference | YouTube Data API (v3) | Google Developers

クエリ (query)

クエリ (query) に指定できる値はリソースにより異なりますが、下表のパラメータはすべてに共通です。

共通のクエリ (query)
パラメータ 意味
key APIキー (必須)
access_token 現在のユーザーのOAuth 2.0トークン
callback コールバック関数
fields レスポンスに含めるフィールドのサブセット
prettyPrint レスポンスをインデントと改行により書式を整えて返すかどうか
userIp ユーザーのIPアドレス
quotaUser ユーザーのIPアドレス (userIp) の代替
標準クエリパラメータ - YouTube | Google Developers

このうちfieldsパラメータは、etag,items(id,snippet)の形式で指定します。実際にはこれをURLエンコードするため、クエリに含めるときにはfields=etag%2Citems%28id%2Csnippet%29とします。fields パラメータについて - YouTube Data API の概要 - YouTube | Google Developers

この他にもリソースを取得する操作、つまりGETでリクエストするAPIではpartパラメータが必須となります。part パラメータについて - YouTube Data API の概要 - YouTube | Google Developers

アクティビティ (Activities)

特定のYouTubeチャンネル、または現在認証されているユーザーがYouTubeで行った操作に関する情報の取得や、お知らせメッセージの投稿を行えます。

リソースの取得 (list)

パラメータには、

  • channelId … YouTubeチャンネルID
  • home … 認証されているユーザーの、YouTubeホームページに表示されるアクティビティ フィード
  • mine … 認証されているユーザーの、アクティビティ フィード

のいずれかを指定します。さもなくば「No filter selected.」としてエラーとなります。

参考

チャンネル (Channels)

YouTubeチャンネルに関する情報を取得できます。このリソースの可能な操作は、取得 (list) のみです。パラメータには、次のいずれかを指定します。

  • id … 特定のチャンネル (YouTubeチャンネルID)
  • forUsername … 特定のチャンネル (YouTubeユーザー名)
  • categoryId … ガイドカテゴリに関連付けられているチャンネル (チャンネル カテゴリID)
  • managedByMe … コンテンツ所有者が管理するチャンネル
  • mine … 認証されたユーザーが所有するチャンネル
  • mySubscribers … (このパラメータのサポートは終了している) 認証されたユーザーの登録チャンネル

たとえば「音楽」のカテゴリに関連付けられているチャンネルを取得するには、categoryIdでそのチャンネル カテゴリIDを指定して、次のようにリクエストします。

GET https://www.googleapis.com/youtube/v3/channels
    ?part=snippet&categoryId=GCTXVzaWM&key=API_KEY

チャンネルID (Channel IDs)

Data API v3ではチャンネルの指定にYouTubeユーザー名 (YouTube ID) は指定できず、すべてチャンネルIDで指定する必要があります。YouTube Data API - チャンネル ID への対応 - YouTube | Google Developers

YouTubeユーザー名からチャンネルIDを得るには、

GET https://www.googleapis.com/youtube/v3/channels
    ?part=id&forUsername=GoogleDevelopers&key=API_KEY

のように、channelsリソースへGETリクエストします。この結果は次のように返され、この例では「UC_x5XG1OV2P6uZZ5FSM9Ttw」がチャンネルIDです。

"{
    "kind": "youtube#channelListResponse",
    "etag": "\"gMjDJfS6nsym0T-NKCXALC_u_rM/9Uu_LJKSiIBlJOBZoZLkKcjhUUE\"",
    "pageInfo": {
        "totalResults": 1,
        "resultsPerPage": 5
    },
    "items": [
        {
            "kind": "youtube#channel",
            "etag": "\"gMjDJfS6nsym0T-NKCXALC_u_rM/JgZIwrlCnsd1wzjssCxaCFp8mRU\"",
            "id": "UC_x5XG1OV2P6uZZ5FSM9Ttw"
        }
    ]
}
"

このとき該当するチャンネルIDが存在しないときはtotalResultsが0となり、itemsは空の配列となります。

なおチャンネルIDは、つねに"UC"から始まる24文字の文字列です。YouTube ユーザー ID とチャンネル ID - YouTube ヘルプ

簡易な方法

さしあたってチャンネルIDを知りたいだけならば、youtube.channels.list - Google APIs Explorerでリクエストすることで得られます。

またはユーザーのページ、たとえばwww.youtube.com/user/GoogleDevelopersからそのユーザーの動画ページを開きます。そして下図のユーザーのチャンネルへのリンクのURLを調べるとwww.youtube.com/channel/UC_x5XG1OV2P6uZZ5FSM9Ttwとなっており、ここからチャンネルIDを知ることもできます。

参考

ガイドカテゴリ (GuideCategories)

ガイドカテゴリはYouTubeのシステムによって自動で割り当てられるカテゴリであり、ユーザーによって割り当てられる動画カテゴリとは異なります。

たとえば日本で有効なガイドカテゴリを取得するには、regionCodeをjpとして

GET https://www.googleapis.com/youtube/v3/guideCategories
    ?part=snippet&regionCode=jp&key=API_KEY

とリクエストします。

なおレスポンスで返されるチャンネルID「UCBR8-60-B28hp2BmDPdntcQ」は、YouTube Spotlight - YouTubeのIDです。

レスポンスの一部
レスポンス 意味
items.id チャンネル カテゴリID
items.snippet.channelId チャンネルID

参考

国際化地域 (i18n Regions)

YouTubeでサポートされる地域の一覧を取得できます。

GET https://www.googleapis.com/youtube/v3/i18nRegions
    ?part=snippet&key=API_KEY

検索 (Search)

条件に一致する、

  • 動画 (video)
  • チャンネル (channel)
  • 再生リスト (playlist)

に関する情報を取得できます。たとえばキーワードで検索するならば、次のようにします。

GET https://www.googleapis.com/youtube/v3/search
    ?part=snippet&q=KEYWORD&key=API_KEY

このときpartに指定できるのはidもしくはsnippetのみで、さらに詳細まで知るには得られた個々のIDを動画でリクエストします。

またqパラメータには論理演算子、NOT (-) およびOR (|) を指定できます。たとえばAまたはBであるが、Cではないという条件ならば、"A|B -C"とします。ただしパラメータに含めるときにはURLエンコードが必要なため、実際には"A%7CB%20-C"となります。

チャンネルを検索するには、そのチャンネルIDで次のように検索します。

GET https://www.googleapis.com/youtube/v3/search
    ?part=snippet&channelId=CHANNEL_ID&key=API_KEY

必須のパラメータはpartだけとされていますが、クエリを指定するqパラメータを指定しないと、レスポンスのitemsパラメータが空のリストとして返されることがあります。

既定では一致する動画、チャンネル、再生リストのすべてが返されますが、typeパラメータによりそれを制限できます。

  • channel
  • playlist
  • video

以下のパラメータを指定する場合は、typeパラメータをvideoとしなければなりません。Errors - Search: list - YouTube | Google Developers

  • eventType
  • videoCaption
  • videoCategoryId … 動画カテゴリのID
  • videoDefinition
  • videoDimension
  • videoDuration
  • videoEmbeddable
  • videoLicense
  • videoSyndicated
  • videoType

さもなくばbadRequest (400) エラーとなり、「Invalid combination of search filters and/or restrictions.」と返されます。またchannelTypeパラメータを指定する場合には、typeはchannelとします。さもなくば、これも同様にinvalidSearchFilterとなります。

パラメータの一部
パラメータ 意味
publishedAfter 指定日時より後に作成されたリソースにのみ制限する (RFC 3339形式)
publishedBefore 指定日時より前に作成されたリソースにのみ制限する (RFC 3339形式)
レスポンスの一部
レスポンス 意味
items.snippet.liveBroadcastContent 動画またはチャンネルに、ライブ配信が含まれているかどうか
  • live … アクティブなライブ配信がある
  • upcoming … まだライブ配信を開始していない動画、または配信予定があるチャンネル
  • none … ライブ配信をしていない
snippet.liveBroadcastContent - Search | YouTube Data API | Google Developers

参考

動画カテゴリ (VideoCategories)

パラメータには次のいずれかを指定し、動画カテゴリの情報を取得できます。

  • id … 特定の1つの動画カテゴリの情報
  • regionCode … 地域ごとにサポートされる、複数の動画カテゴリの情報

特定の動画カテゴリの情報を取得するには、YouTubeのカテゴリ一覧にあるカテゴリごとに割り当てられたIDを、idパラメータに指定します。

GET https://www.googleapis.com/youtube/v3/videoCategories
    ?part=snippet&id=1&key=API_KEY

特定の地域でサポートされるカテゴリの一覧を取得するには、regionCodeパラメータを指定します。このパラメータの値はISO 3166-1 alpha-2の国コードで、たとえば日本はそれが「jp」であるから、

GET https://www.googleapis.com/youtube/v3/videoCategories
    ?part=snippet&regionCode=jp&key=API_KEY

とすると、日本で使用できる動画カテゴリの一覧を取得できます。

レスポンスの一部
レスポンス 意味
snippet.channelId 動画カテゴリを作成したYouTubeチャンネル
snippet.title 動画カテゴリのタイトル
snippet.assignable 動画がそのカテゴリに関連付けられるかどうか

参考

動画 (Videos)

個別の動画を操作できます。

リソースの取得 (list)

GET https://www.googleapis.com/youtube/v3/videos
    ?part=snippet&id=VIDEO_ID&key=API_KEY

partパラメータに指定できるのは以下の値であり、これらの情報を取得できます。

  • id … 動画を一意に識別するためにYouTubeによって使用されるID
  • snippet … タイトル、説明、カテゴリなどの動画の基本的な情報
  • contentDetails … 動画の長さとアスペクト比を含む、動画コンテンツに関する情報
  • fileDetails … ファイルの解像度、長さ、オーディオと動画のコーデック、ストリーミングのビットレートなど (動画の所有者のみ)
  • liveStreamingDetails
  • player … 埋め込みプレーヤーでの動画の再生に使用される情報
  • processingDetails … アップロードされた動画ファイルの処理の進捗状況に関する情報 (動画の所有者のみ)
  • recordingDetails … 動画が録画された場所、日付、住所に関する情報
  • statistics … 動画に関する統計情報
  • status … 動画のアップロード、処理、プライバシーのステータスに関する情報
  • suggestions … アップロード済み動画の動画品質を向上させる方法やメタデータを示す提案 (動画の所有者のみ)
  • topicDetails … 動画に関連付けられているFreebaseトピックに関する情報
プロパティ - Videos | YouTube Data API (v3) | Google Developers

idではビデオIDを指定します。これはYouTubeの再生ページでは、https://www.youtube.com/watch?v=VIDEO_IDにあるVIDEO_IDです。このIDはカンマで区切って複数指定できるため、複数の動画の情報を一括して取得できます。

レスポンスの一部
レスポンス 意味
statistics.viewCount 動画の再生回数
fileDetails.creationTime アップロードされた動画ファイルの作成日時 (動画の所有者のみ)
topicDetails.topicIds[] 動画に関連付けられている中心的なFreebaseトピックIDのリスト。各トピックの詳細は、そのIDを検索のパラメータでtopicIdに指定することで得られる。google api - How to use `relevantTopicIds` from YouTube Data API v3? - Stack Overflow

参考

参考

APIのテスト