結論
YouTube API(YouTube Data API v3)は、Google Cloud でプロジェクトを作り、YouTube Data API v3 を有効にして API キーを作れば、公開されている動画・チャンネル・再生リストの情報を取得できます。2026年6月1日からクォータは枠が分かれ、既定は「search.list が1日100回」「videos.insert が1日100回」「そのほかのメソッドの合計が1日10,000ユニット」です(2026年11月18日時点の公式の記載)。
この記事でわかること
- API キーの取得と制限の手順(Google Cloud コンソールの画面名つき)
- 新しいクォータの枠と、用途別に実際に計算した消費量の表
- 公式の Python クライアントで動画情報を取得・集計し、エラーを出したときの出力
この記事で実際に動かしたもの:公式の Python クライアント(google-api-python-client)を、同梱の YouTube Data API v3 の定義のまま、手元の 127.0.0.1 で動く模擬サーバーに向けて動かしました。本物の YouTube・Google Cloud には一度も接続していません。
flowchart TD
H[チャンネルのハンドル] --> C[channels.list<br>1ユニット]
C --> U[uploads の再生リスト ID]
U --> P[playlistItems.list<br>50件ごとに1ユニット]
P --> V[videos.list<br>50本ごとに1ユニット]
V --> S[再生数・長さを集計]
Q[キーワードで探す] --> SL[search.list<br>1日100回の別枠]
SL --> V
よく調べられることの答えを先にまとめます。
| 知りたいこと | 答え | 詳しい節 |
|---|---|---|
| YouTube API とは | YouTube の動画・チャンネル・再生リストなどの情報を、プログラムから取得・操作する Google の API | YouTube Data APIとは |
| YouTube API キーの取得方法 | プロジェクト作成 → YouTube Data API v3 を有効化 → 「認証情報」→「認証情報を作成」→「API キー」 | APIキーの取得手順と制限 |
| API キーと OAuth の違い | 公開データの取得だけなら API キー。登録・更新・削除と、本人のデータには OAuth 2.0 | APIキーとOAuth 2.0の使い分け |
| YouTube API のクォータ(上限) | search.list 1日100回・videos.insert 1日100回・ほかの合計 1日10,000ユニット | YouTube APIのクォータとは |
| YouTube API は無料か | 公式の資料に API の料金表は見当たらず、上限はクォータで決まる。増やすには申請フォーム | YouTube APIのクォータとは |
| チャンネルの全動画を取る | channels.list で uploads の ID → playlistItems.list → videos.list。120本で7ユニット | クォータのコスト表と計算 |
| quotaExceeded が出た | その日の枠を使い切った。再送しても戻らない。太平洋時間の0時(日本時間16時か17時)に戻る | YouTube APIのエラーと直し方 |
| Python での使い方 | google-api-python-client の build() に developerKey を渡し、list().execute() | Pythonで動画情報を取得する |
確認環境:Ubuntu 24.04.5 LTS・Python 3.13.18 の作業用の仮想環境に、google-api-python-client 2.202.0(google-auth 2.62.2・httplib2 0.32.1)を入れました。クライアントは同梱の YouTube Data API v3 の定義(revision 20261104)を読み込み、接続先だけを client_options で 127.0.0.1 の模擬サーバーに向けています。模擬サーバーは Python の標準ライブラリで自作し、応答の形(項目名・入れ子・nextPageToken・エラーの reason)は developers.google.com の YouTube Data API v3 のリファレンスを写しました。データ(チャンネル1つ・動画120本)は架空で、エラーの文言(message)は模擬サーバーのものです。API キーは本物ではなく、環境変数を空にした状態(env -i)で動かしました。Google Cloud コンソールの操作、本物の API の応答、クォータの申請は、ログインせずに Google の公式ドキュメント(YouTube Data API のリファレンス・クォータ計算ツール・改訂履歴・デベロッパー ポリシー、Google Cloud の API キーの説明)で確かめた範囲だけを書いています。図は mermaid 11.16.0 で描画を確かめました(確認日 2026年11月18日)。
本記事の内容は、ご自由にお使いください。
ご利用の際は、出典として本ページへのリンクを記載いただけますようお願いします。
(記載例)出典:株式会社RJC「YouTube APIの使い方|APIキー取得と新クォータの計算・Python実例」
YouTube Data APIとは(できること)
この節では、YouTube Data API で何が取得・操作できるのかと、API の入口の URL が分かります。
YouTube Data API は、YouTube の動画・チャンネル・再生リスト・コメントなどの情報を、HTTP のリクエストで取得したり、登録・更新したりするための Google の API です。 一般に「YouTube API」と呼ばれるのは、多くの場合この Data API の v3 です。リファレンスでは、たとえば videos.list は GET https://www.googleapis.com/youtube/v3/videos と書かれています。
| リソース | 主なメソッド | 取れる情報・できること | クォータ |
|---|---|---|---|
| search(検索) | search.list | キーワード・チャンネル・期間・長さで動画などを探す | 別枠(1日100回) |
| videos(動画) | videos.list | タイトル・説明・長さ・再生数・いいね数・コメント数 | 1 |
| videos(統計だけ) | videos.batchGetStats | 再生数・いいね数・コメント数・長さ(2026年6月3日に追加) | 別枠(1日10,000) |
| channels(チャンネル) | channels.list | チャンネル名・登録者数・動画数・アップロード再生リストの ID | 1 |
| playlistItems(再生リストの中身) | playlistItems.list | 再生リストに入っている動画の ID(チャンネルの全動画もここから) | 1 |
| commentThreads(コメント) | commentThreads.list | 動画のコメントのスレッド | 1 |
| videos(投稿) | videos.insert | 動画をアップロードする(OAuth 2.0 が必要) | 別枠(1日100回) |
手元の Python クライアントが読み込む定義ファイルでは、接続先の根元が https://youtube.googleapis.com/ になっていました。リファレンスの www.googleapis.com と表記は違いますが、どちらも Google の公式の記載で、SDK を使う場合は自分で URL を組み立てる場面はほとんどありません。
この記事は情報の取得(読み取り)を中心に扱います。動画のダウンロードは扱いません。デベロッパー ポリシーは、YouTube の事前の書面による承認なしに動画の音声・映像をダウンロード・保存することを認めていません(提供元の説明。詳しくは後の節)。
APIキーとOAuth 2.0の使い分け
この節では、API キーだけで足りる場面と、OAuth 2.0 の認可が要る場面の見分け方が分かります。
公開されている情報を読むだけなら API キー、登録・更新・削除や、ログインした本人のデータを扱うなら OAuth 2.0 です。 Google の「Obtaining authorization credentials」は、OAuth 2.0 のトークンを付けないリクエストには API キーを付ける、と説明しています。
API キーで足りる
公開動画の検索(search.list)
公開動画の情報・再生数(videos.list の id 指定)
チャンネルの情報・アップロード一覧
人気の動画の一覧(videos.list の chart=mostPopular)
OAuth 2.0 が要る
動画のアップロード・更新・削除
mine=true(自分のチャンネル)・myRating
非公開の動画の統計(batchGetStats の非公開分)
コメントの投稿・再生リストの編集
エラーの一覧では、mine を付けたのに認可されていないリクエストは authorizationRequired(401)になります。OAuth 2.0 そのものの仕組みは、関連記事「OAuth 2.0とOpenID Connectの違いをわかりやすく解説」で扱っています。
APIキーの取得手順と制限(Google Cloud コンソール)
この節では、YouTube API のキーを作るまでの流れと、作ったキーに付ける制限が分かります。
流れは「プロジェクトを作る → YouTube Data API v3 を有効にする → API キーを作る → 制限を付ける」の4段階です。 画面の名前は、Google Cloud の日本語の説明「API キーを管理」に出てくる語をそのまま「」で書いています。この記事の作業ではログインしていないので、画面の配置は版によって変わることがあります。
プロジェクトを作るか選ぶ
Google アカウントで Google Cloud コンソールに入り、プロジェクトを作るか、既存のものを選ぶ。デベロッパー ポリシーは、1つの API クライアントにつきプロジェクトを1つだけ作る、と定めている。
YouTube Data API v3 を有効にする
API の一覧(API Library)から YouTube Data API v3 を探して有効にする。API の制限で選べるのは、プロジェクトで有効にした API だけ。
API キーを作る
「認証情報」ページで「認証情報を作成」をクリックし、「API キー」を選ぶ。「作成」をクリックすると、「API キーを作成しました」のダイアログにキーの文字列が表示される。その場でコピーして安全な場所に保管する。
アプリケーションの制限を付ける
「認証情報」ページでキーの名前をクリックし、「アプリケーションの制限」で「HTTP リファラー」「IP アドレス」「Android アプリ」「iOS アプリ」のどれか1種類を選ぶ。「項目を追加」で値を入れ、「完了」→「保存」。サーバーから呼ぶなら IP アドレス、ブラウザから呼ぶなら HTTP リファラー。
API の制限を付ける
同じ画面の「API の制限」で「キーを制限」をクリックし、YouTube Data API v3 だけを選んで「保存」。こうすると、キーが漏れても他の API には使えない。
Google Cloud の説明では、制限のないキーは安全ではないとされ、本番ではアプリケーションの制限と API の制限の両方を付けることが求められています。キーは定期的に作り直し(同じ制限の新しいキーを作ってアプリを切り替え、前のキーを消す)、1プロジェクトに作れるキーは300個までです。
キーの置き場所は、コードに直接書かず環境変数や設定ファイルにします。書き方は関連記事「.envの使い方と注意点|APIキーを安全に管理する方法」で扱っています。Google Cloud 全体の始め方は、関連記事「GCPとは|Google Cloudの主要サービス・料金・無料枠・始め方」が入口です。
YouTube APIのクォータとは(2026年6月からの枠)
この節では、クォータの意味と、2026年6月1日に変わった枠の分け方、リセットの時刻が分かります。
クォータは、1つのプロジェクトが1日に使える API の量の上限です。 呼び出しごとに決まったコスト(ユニット)が引かれ、上限に達するとその日は quotaExceeded のエラーになります。改訂履歴によると、2026年6月1日から「granular quota system(細かな枠のしくみ)」に移り、videos.insert と search.list がそれぞれ専用の枠を持つようになりました。
2026年6月3日に追加された videos.batchGetStats も、専用の枠(既定 1日10,000ユニット、1回1ユニット)です。
| 時期 | search.list の扱い | 動画のアップロード | 出典 |
|---|---|---|---|
| 2014年11月11日の改訂 | 1回100ユニットに変更(共通の枠から引く) | (この項には記載なし) | 改訂履歴 |
| 2025年12月4日の改訂 | (この項には記載なし) | 約1,600 → 約100ユニットに下がった | 改訂履歴 |
| 2026年6月1日から | 専用の枠で1日100回(1回1) | videos.insert も専用の枠で1日100回 | 改訂履歴・クォータ計算ツール |
以前の版の解説では「search.list は100ユニット、10,000ユニットで1日100回」と書かれていることがあります。1日100回という回数は今も同じですが、いまは search.list を何回呼んでも、videos.list などの10,000ユニットは減りません。逆に、search.list の100回を使い切ると、10,000ユニットが残っていても検索はできません。
リセットの時刻(日本時間)
公式の説明では、1日のクォータは太平洋時間の0時に戻ります。夏時間の有無で日本時間が変わるので、Python の zoneinfo で計算しました。
[6] リセット時刻(太平洋時間の 0 時)を日本時間で
2026-11-18 0:00 PT (PST) = 11/18 17:00 JST
2026-07-01 0:00 PT (PDT) = 07/01 16:00 JST
2026-03-09 0:00 PT (PDT) = 03/09 16:00 JST
2026-03-08 0:00 PT (PST) = 03/08 17:00 JST
11月〜3月上旬は日本時間17時、夏時間の間は16時です。2026年は3月8日に夏時間が始まり、その日の0時はまだ標準時なので17時でした。使った量は、Google Cloud コンソールの割り当て(Quotas)のページで確かめられます。
YouTube API は無料か
確認した YouTube Data API の公式の資料(概要・クォータ計算ツール・改訂履歴)には、API の呼び出しの料金表はありませんでした。上限はクォータで決まり、足りないときは「Quota extension request form(クォータ拡張の申請フォーム)」で申し込む、と書かれています。申請が通るかどうかは提供元の審査によります。サーバー代や、Google Cloud の別のサービスを使った分は別にかかります。
クォータのコスト表と計算
この節では、主なメソッドのクォータのコストと、用途ごとに1日に何回回せるかを計算した結果が分かります。
読み取りの list はほとんどが1ユニット、書き込みは多くが50ユニットです。 公式のクォータ計算ツール(2026年11月12日更新)から、よく使うものを抜き出しました。
| メソッド | コスト | 既定の枠で1日に呼べる回数 |
|---|---|---|
| search.list | 専用の枠 1回1 | 100回 |
| videos.list・channels.list・playlistItems.list・playlists.list・commentThreads.list | 1 | 10,000回(合計) |
| videos.batchGetStats | 専用の枠 1回1 | 10,000回 |
| liveChatMessages.list | 5 | 2,000回 |
| captions.list | 50 | 200回 |
| videos.update・playlistItems.insert・comments.insert・thumbnails.set | 50 | 200回 |
| captions.insert | 400 | 25回 |
| videos.insert | 専用の枠 1回1 | 100回 |
公式の注意点は2つです。無効なリクエストも最低1ユニットかかる、次のページを取るたびに同じコストがかかる。
用途別に計算した消費量
上の表の値で、よくある使い方の消費量を Python で計算しました(quota_calc.py の出力)。
[1] チャンネルの全動画(アップロード再生リスト経由)
120本 {'channels.list': 1, 'playlistItems.list': 3, 'videos.list': 3, 'default_units': 7, 'search_calls': 0} 1日に回せる回数 1428
1000本 {'channels.list': 1, 'playlistItems.list': 20, 'videos.list': 20, 'default_units': 41, 'search_calls': 0} 1日に回せる回数 243
5000本 {'channels.list': 1, 'playlistItems.list': 100, 'videos.list': 100, 'default_units': 201, 'search_calls': 0} 1日に回せる回数 49
[2] search.list で同じことをした場合
120本 {'search_calls': 3, 'videos.list': 3, 'default_units': 3, 'note': ''} 1日に回せる回数 33
1000本 {'search_calls': 10, 'videos.list': 10, 'default_units': 10, 'note': 'channelId+type=video は500本まで'} 1日に回せる回数 10
[3] K チャンネルを毎時、最新50本の統計を取る(uploads の ID は保存して再利用)
K= 10: 1日 480 ユニット OK
K= 50: 1日 2400 ユニット OK
K=200: 1日 9600 ユニット OK
K=250: 1日 12000 ユニット 超える
毎時で収まる最大チャンネル数 208 / 3時間ごとなら 625
[5] 書き込みの目安(既定の枠 10,000 ユニット)
playlistItems.insert: 50 ユニット → 1日 200 回
captions.insert: 400 ユニット → 1日 25 回
liveChatMessages.insert: 20 ユニット → 1日 500 回
1全動画は search より再生リスト
120本のチャンネルなら、uploads の再生リスト経由で7ユニット。10,000ユニットの枠で1日1,428回回せる。search.list だと100回の枠のうち3回を使う。
2search には500本の上限
search.list のリファレンスでは、channelId と type=video の検索は500本までと書かれている。1,000本のチャンネルは search では取り切れない。
3毎時の監視は208チャンネルまで
1チャンネル毎時2ユニット(playlistItems.list と videos.list)なら、1日48ユニット。10,000ユニットで208チャンネルまで。3時間ごとなら625チャンネル。
計算に使ったスクリプトの中心は次のとおりです。50件ずつ取れるので、件数を50で割って切り上げた数がページ数になります。
import math
SEARCH_PER_DAY, DEFAULT_UNITS = 100, 10000 # 公式の既定(2026年11月18日時点)
def channel_all(n):
pages = math.ceil(n / 50)
# channels.list 1 + playlistItems.list pages + videos.list pages
return 1 + 2 * pages
for n in (120, 1000, 5000):
u = channel_all(n)
print(n, u, DEFAULT_UNITS // u)
主なメソッドとpart・fieldsの指定
この節では、search.list・videos.list・channels.list・playlistItems.list の要点と、必須の part、応答を絞る fields の書き方が分かります。
取得系のリクエストには必ず part(どの部分を返すか)を付けます。 概要のページは「API は部分的なリソースの取得を認めているだけでなく、求めている」と説明しています。part を付けないと missingRequiredParameter になり、公式の Python クライアントは送る前に止めます(後の節で実行結果を示します)。
search.list
part=snippet だけ。maxResults は0〜50(既定5)、order は relevance(既定)・date・viewCount など。
長さで絞るなら type=video
videos.list
id にカンマ区切りで動画 ID。part は snippet・contentDetails・statistics など。
id 指定では maxResults は使えない
channels.list
forHandle(@ を付けてもよい)・id・mine のどれか1つ。contentDetails に uploads の再生リスト ID。
登録者数は3桁に丸めた値
playlistItems.list
playlistId を指定。maxResults は0〜50(既定5)。pageToken で次のページ。
後で見る・履歴は取れない
search.list のよく使うパラメーター
| パラメーター | 値の例 | 注意 |
|---|---|---|
| q | python 入門 | - で除外、|(%7C)で OR |
| type | video | 既定は video,channel,playlist |
| order | date・viewCount・relevance | relevance 以外は結果が少なくなることがある |
| publishedAfter | 2026-11-01T00:00:00Z | RFC 3339 の日時 |
| videoDuration | short・medium・long | short は4分未満、medium は4〜20分、long は20分超。type=video が必要 |
| regionCode | JP | ISO 3166-1 alpha-2 |
pageInfo.totalResults は概数で、上限は1,000,000です。リファレンスは、この値をページ送りのリンク作りに使わないよう勧めています。
fields で応答を絞る
part が「どの部分」を決めるのに対し、fields は「その中のどの項目」を決めます。概要のページの例では、次の指定で snippet の中身が channelId・title・categoryId だけになります。
GET https://www.googleapis.com/youtube/v3/videos?id=動画ID&part=snippet,statistics
&fields=items(id,snippet(channelId,title,categoryId),statistics)&key=API_KEY
fields は転送量と処理の量を減らすための指定です。クォータ計算ツールのコストはメソッドごとに決まっていて、fields による違いは書かれていません。
Pythonで動画情報を取得する(google-api-python-client)
この節では、公式の Python クライアントでの基本の書き方と、送る前にクライアントが止めるものが分かります。
build('youtube', 'v3', developerKey=キー) でクライアントを作り、yt.videos().list(...).execute() の形で呼びます。 手元では、接続先だけを 127.0.0.1 の模擬サーバーに向けました。本物に向けるときは client_options の行を消し、キーを環境変数から渡します。
python3 -m venv .venv
.venv/bin/pip install google-api-python-client
export YT_API_KEY='作ったキーの文字列' # コードに直接書かない
import os
from googleapiclient.discovery import build
yt = build('youtube', 'v3',
developerKey=os.environ['YT_API_KEY'],
static_discovery=True, # 同梱の定義を使う
client_options={'api_endpoint': 'http://127.0.0.1:18646/'}) # 手元の模擬サーバー。本物では消す
ch = yt.channels().list(part='contentDetails,statistics',
forHandle='@demo-channel').execute()
uploads = ch['items'][0]['contentDetails']['relatedPlaylists']['uploads']
res = yt.videos().list(part='snippet,contentDetails,statistics',
id='DEMOvid0001,DEMOvid0002').execute()
for v in res['items']:
print(v['id'], v['snippet']['title'], v['statistics']['viewCount'])
実行すると、クライアントは次の URL にリクエストを送りました(模擬サーバーの記録。キーは伏せています)。キーは key のクエリ パラメーターで送られ、alt=json が自動で付きます。
200 /youtube/v3/channels?part=contentDetails%2Cstatistics&forHandle=%40demo-channel&key=***&alt=json
送る前にクライアントが止めるもの
同梱の定義に必須の項目や選べる値が書かれているので、part の書き忘れや order の打ち間違いは、リクエストを送る前に TypeError になります。クォータも減りません。
[B] part なし -> TypeError: Missing required parameter "part"
[B] order に無い値 -> TypeError: Parameter "order" value "popular" is not an allowed value in "['searchSortUnspecified', 'date', 'rating', 'viewCount', 'relevance', 'title', 'videoCount']"
一方、part に存在しない名前(例:snippet,brandNew)を入れた場合は送られ、サーバー側で unknownPart(400)になりました。
SDK を使わずに HTTP で呼ぶ
Google Cloud の「API キーを使用して API にアクセスする」では、キーを x-goog-api-key ヘッダーで渡す形を勧め、ヘッダーが使えないときは key のクエリ パラメーターを使えるが URL にキーが残る、と説明しています。標準ライブラリだけで書くと次の形です。
import json, os, urllib.request
url = 'http://127.0.0.1:18646/youtube/v3/videos?part=statistics&id=DEMOvid0001'
req = urllib.request.Request(url, headers={'x-goog-api-key': os.environ['YT_API_KEY']})
print(json.load(urllib.request.urlopen(req))['items'][0]['statistics'])
[G] header -> {'viewCount': '8919', 'likeCount': '633', 'favoriteCount': '0', 'commentCount': '97'}
数値が文字列で返る点に注意します。リファレンスでは型は unsigned long ですが、JSON では "8919" のような文字列なので、足し算の前に int() で変換します。requests での再試行やタイムアウトの書き方は、関連記事「Pythonのrequestsの使い方|タイムアウト・エラー処理・再試行まで」で扱っています。
ページングで全件を取る(nextPageToken)
この節では、50件を超える結果を最後まで取る書き方と、そのときのクォータの減り方が分かります。
応答に nextPageToken があれば、それを pageToken に入れて次のページを取ります。 公式の Python クライアントには list_next() があり、トークンの受け渡しを代わりにしてくれます。最後のページで None が返ります。
ids = []
req = yt.playlistItems().list(part='contentDetails', playlistId=uploads, maxResults=50)
while req is not None:
res = req.execute()
ids += [it['contentDetails']['videoId'] for it in res['items']]
req = yt.playlistItems().list_next(req, res)
videos = []
for i in range(0, len(ids), 50): # 50本ずつまとめて videos.list
r = yt.videos().list(part='snippet,contentDetails,statistics',
id=','.join(ids[i:i + 50])).execute()
videos += r['items']
架空のチャンネル(動画120本)で実行した結果と、模擬サーバーに届いたリクエストです。
[C] channel UCdemoChannel00000000001 uploads UUdemoChannel00000000001 videoCount 120
[C] playlistItems pages 3 ids 120
[C] videos.list calls 3 items 120
[D] quota used (mock) {'search': 0, 'default': 7, 'batch': 0}
200 /youtube/v3/playlistItems?part=contentDetails&playlistId=UUdemoChannel00000000001&maxResults=50&key=***&alt=json
200 /youtube/v3/playlistItems?part=contentDetails&playlistId=UUdemoChannel00000000001&maxResults=50&key=***&alt=json&pageToken=p50
200 /youtube/v3/playlistItems?part=contentDetails&playlistId=UUdemoChannel00000000001&maxResults=50&key=***&alt=json&pageToken=p100
channels.list 1回・playlistItems.list 3回・videos.list 3回で、合計7ユニットでした。前の節の計算と一致します。maxResults を既定の5のままにすると、playlistItems.list が24回になり、それだけで24ユニットかかります。一覧を取るときは maxResults=50 を明示します。
チャンネルの全動画を集める
見分ける問い:「探したいのか、一覧がほしいのか」
取得した統計を集計する(再生数・長さ)
この節では、videos.list で取った再生数・いいね数・動画の長さを集計する書き方と、長さの形式(ISO 8601)の読み方が分かります。
動画の長さ(contentDetails.duration)は PT15M33S のような ISO 8601 の形式で返ります。 リファレンスでは、1時間未満は PT#M#S、1時間以上は PT#H#M#S、1日以上は P#DT#H#M#S です。秒に直す関数を書いて確かめました。
import re
def iso(d):
m = re.fullmatch(r'P(?:(\d+)D)?T?(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?', d)
dd, h, mi, s = (int(x or 0) for x in m.groups())
return dd * 86400 + h * 3600 + mi * 60 + s
views = [int(v['statistics']['viewCount']) for v in videos]
likes = [int(v['statistics'].get('likeCount', 0)) for v in videos]
print(sum(views), round(sum(views) / len(views)), round(100 * sum(likes) / sum(views), 2))
[C] total views 3111660 avg 25930 like/view % 1.79
[C] duration buckets {'short(<4m)': 13, 'medium(4-20m)': 70, 'long(>20m)': 37}
[C] top DEMOvid0101 デモ動画 101 50819 PT3M47S 227
[C] top DEMOvid0082 デモ動画 082 50358 PT22M4S 1324
[C] top DEMOvid0063 デモ動画 063 49897 PT10M21S 621
[C] iso PT15M33S 933
[C] iso PT1H2M 3720
[C] iso P1DT2H 93600
[C] iso PT45S 45
長さの区分は、search.list の videoDuration と同じ境目(4分未満・4〜20分・20分超)にしました。数値は架空のデータのものです。
統計の項目で気をつけること
| 項目 | 公式の説明 | 集計での扱い |
|---|---|---|
| statistics.viewCount | 再生が始まった時点で数える。2026年11月16日の改訂で、テレビで一緒に見た人(co-viewers)も公開の再生数に含める | 時期をまたぐ比較では数え方の変更に注意 |
| statistics.dislikeCount | 2021年12月13日から非公開。動画の持ち主が認可したときだけ | API キーでは取れない前提で作る |
| statistics.favoriteCount | 2015年8月28日から使われず、常に0 | 集計に使わない |
| channels の subscriberCount | 3桁の有効数字に切り捨てた値 | 12,345人は 12,300 と返る |
| snippet.thumbnails | default 120×90 から maxres 1280×720 など。大きいサイズは一部の動画だけ | 無いキーに備えて get() で読む |
統計だけを多く取るなら、2026年6月3日に追加された videos.batchGetStats も選べます。専用の枠なので、videos.list の10,000ユニットを減らしません。リファレンスの応答には、取れなかった動画の ID を返す summary があります。模擬サーバーで同じ形を返したときの出力です。
[I] batchGetStats {'requestedVideoCount': 3, 'succeededVideoCount': 2, 'failedVideoCount': 1, 'failedVideoIds': ['NOPEvid9999']}
このメソッドの id に何本まで入れられるかは、確認したリファレンスには書かれていませんでした。公開動画は認可なしで取れる、と書かれていますが、API キーだけで呼べるかの明記も見つからなかったので、使う前にリファレンスの最新の記載を確かめます。
YouTube APIのエラーと直し方
この節では、YouTube API でよく出るエラーの reason ごとの原因と直し方が分かります。
エラーは HTTP のステータスと、応答の中の reason(例:quotaExceeded)の組で見分けます。 公式の Python クライアントでは HttpError が出て、e.status_code と e.error_details[0]['reason'] で読めます。模擬サーバーで出した例です(message の文言は模擬サーバーのもの)。
<HttpError 403 when requesting http://127.0.0.1:18646/youtube/v3/search?part=snippet&q=%E3%83%87%E3%83%A2&type=video&key=DUMMY-KEY-FOR-LOCAL-MOCK&alt=json returned "The request cannot be completed because you have exceeded your <a href="/youtube/v3/getting-started#quota">quota</a>.". Details: "[{'message': 'The request cannot be completed because you have exceeded your <a href="/youtube/v3/getting-started#quota">quota</a>.', 'domain': 'youtube.quota', 'reason': 'quotaExceeded'}]">
status 403 reason quotaExceeded
HttpError の文字列には、リクエストの URL がキーごと入ります。ログに残すときは key= の部分を伏せます。
| reason(HTTP) | 公式の説明の要旨 | よくある原因 | 直し方 |
|---|---|---|---|
| quotaExceeded(403) | クォータを超えた | search.list の100回を使い切った・ループで呼びすぎた | リセットを待つ・結果を保存して使い回す・申請フォーム |
| forbidden(403) | アクセスが拒否された。認可が正しくない | fileDetails など持ち主だけの part を API キーで求めた | part を見直す・OAuth 2.0 を使う |
| missingRequiredParameter(400) | 必須のパラメーターが無い | part の付け忘れ | part=snippet などを付ける |
| unknownPart(400) | part に分からない値がある | part の綴り違い・別のリソースの part | リファレンスの part の一覧と照らす |
| invalidSearchFilter(400) | 検索の条件の組み合わせが正しくない | videoDuration などを type=video なしで使った | type=video を付ける |
| invalidPageToken(400) | ページのトークンが正しくない | 別の条件のときのトークンを使い回した | 同じ条件のまま nextPageToken を渡す |
| authorizationRequired(401) | mine を使ったが認可されていない | API キーだけで mine=true | OAuth 2.0 で認可する |
| playlistNotFound(404) | playlistId の再生リストが見つからない | ID の写し間違い・非公開 | channels.list の uploads を使う |
| videoNotFound(404) | 動画が見つからない | id の値の誤り | id の値を確かめる |
API キーそのものが無効なときの reason は、YouTube のエラーの一覧では確かめられませんでした。キーまわりで 400・403 が出たら、キーの文字列・API の制限に YouTube Data API v3 が入っているか・アプリケーションの制限(IP アドレスなど)と呼び出し元が合っているか、の順に確かめます。
よくあるつまずき
| 症状 | 原因 | 確かめ方 | 直し方 |
|---|---|---|---|
| TypeError: Missing required parameter "part" | part を付けていない | 呼び出しの引数を見る | part='snippet' などを付ける |
| 検索だけ止まり、videos.list は動く | search.list の専用の枠を使い切った | 割り当てのページで search の使用量を見る | 結果を保存して検索の回数を減らす |
| 結果が5件しか返らない | maxResults の既定は5 | 応答の pageInfo.resultsPerPage | maxResults=50 を付ける |
| 再生数の足し算がおかしい | 数値が文字列で返る | type() で型を見る | int() で変換してから足す |
| totalResults とページの数が合わない | totalResults は概数 | nextPageToken が尽きるまで回した数と比べる | nextPageToken の有無で終わりを判定する |
| dislikeCount が無い | 2021年12月から非公開 | リファレンスの statistics の説明 | 使わない前提で作る |
| 日本時間の朝に戻っていない | リセットは太平洋時間の0時 | この記事のリセット時刻の表 | 日本時間16時か17時を待つ |
再試行の判断(quotaExceededとrateLimitExceeded)
この節では、エラーのときに再送してよいものと、待っても戻らないものの見分け方を、公式の Python クライアントの動きで示します。
quotaExceeded は1日の枠の使い切りなので、数秒待って再送しても戻りません。 一方、rateLimitExceeded(短い時間に送りすぎ)は、公式のエラーの一覧(posts.list の項)で、送る間隔を落とし指数バックオフで再送するよう勧められています。公式の Python クライアントの execute(num_retries=3) は、5xx・429 と、403 のうち reason が rateLimitExceeded・userRateLimitExceeded のときだけ再送します(同梱の googleapiclient/http.py の _should_retry_response で確かめました)。
模擬サーバーで、同じ num_retries=3 を付けて2つを返し分けた結果です。動作を見やすくするため、模擬サーバーでは search.list の枠を1日3回に縮めています(3回のうち1回は rateLimitExceeded の試験で使いました)。
[H] rateLimitExceeded x2 -> 3回目で youtube#searchListResponse elapsed 2.23 s
[E] search ok 2 -> HttpError 403 (message は省略) | details quotaExceeded
[E] num_retries=3 -> 403 quotaExceeded elapsed 0.0 s
403 /youtube/v3/search?part=snippet&q=ratelimit&key=***&alt=json
403 /youtube/v3/search?part=snippet&q=ratelimit&key=***&alt=json
200 /youtube/v3/search?part=snippet&q=ratelimit&key=***&alt=json
403 /youtube/v3/search?part=snippet&q=%E3%83%87%E3%83%A2&key=***&alt=json
rateLimitExceeded は2回待って再送し、3回目で成功しました(待ち時間は乱数で、合計2.23秒)。quotaExceeded は1回で止まり、再送されませんでした。quotaExceeded を受けたら、その日の残りの検索を止め、リセット後に再開する作りにします。待ち時間の決め方は、関連記事「指数バックオフとは?リトライ間隔の決め方とジッターの実装」で扱っています。
- 1400(missingRequiredParameter・unknownPart など)→ 再送しないリクエストを直す。同じものを送っても同じ結果
- 2401・403 の forbidden → 再送しない認可・キーの制限・part を見直す
- 3403 quotaExceeded → その日は止める太平洋時間の0時まで待つ。足りなければ申請
- 4403 rateLimitExceeded・429 → 間をあけて再送指数バックオフ。num_retries で自動
- 55xx → 間をあけて再送続くなら時間をおく
利用規約・ポリシーで確かめること
この節では、YouTube API Services のデベロッパー ポリシーのうち、取得したデータの扱いで作りに関わる点が分かります。
取得したデータの保存期間・更新・表示には決まりがあります。 以下は提供元のポリシーの記載の要旨で、ここに書いたことで利用の可否を保証するものではありません。商用の利用や、個人の情報を含むデータを扱うときは、事前に提供元の最新の規約とポリシーを確かめます。
- 1動画の音声・映像を保存しない事前の書面の承認なしに、ダウンロード・バックアップ・キャッシュ・保存をしない(III.E.1)。オフライン再生もできるようにしない
- 2保存したデータは30日以内に更新か削除認可を伴わないデータの一時的な保存は30暦日まで(III.E.4)。結果を保存して使い回す作りは、この期限に合わせる
- 3表示は最新のデータで利用者に見せるときは手に入る最新の API データを表示し、自分で計算した似た数値に置き換えない(III.E.4)
- 4キーは自分のプロジェクトのものだけ1つの API クライアントにプロジェクトは1つ。キーを第三者に渡したり、他人のキーを使ったりしない(III.D.1)
保存の期限(30日)は、クォータを節約するために結果を保存する作りと関わります。たとえば「1日1回取得して保存し、画面では保存した値を出す」なら、保存した値は毎日更新され、期限の中に収まります。
どの方法を選ぶか(判断表)
この節では、やりたいことごとに、どのメソッドとどの認証を使い、クォータがどれだけ減るかが分かります。
| やりたいこと | 使うメソッド | 認証 | 1回の消費 |
|---|---|---|---|
| キーワードで動画を探す | search.list(type=video)→ videos.list | API キー | 検索の枠1回+1ユニット |
| 特定の動画の再生数を見る | videos.list(id をカンマ区切りで並べる) | API キー | 1ユニット |
| 統計だけを大量に追う | videos.batchGetStats | 公開動画は認可なしと記載 | 専用の枠1 |
| チャンネルの全動画の一覧 | channels.list → playlistItems.list → videos.list | API キー | 1+50件ごとに2ユニット |
| 人気の動画の一覧 | videos.list(chart=mostPopular・regionCode=JP) | API キー | 1ユニット |
| 自分のチャンネルの情報 | channels.list(mine=true) | OAuth 2.0 | 1ユニット |
| 動画をアップロードする | videos.insert | OAuth 2.0 | 専用の枠1回 |
chart=mostPopular の一覧は、2025年7月21日から音楽・映画・ゲームの急上昇から選ぶ形に変わった、と改訂履歴にあります。videos.list の id に入れられる本数の上限はリファレンスに書かれていませんでした。この記事のコードは playlistItems.list の1ページ(最大50件)に合わせて50本ずつに分けています。
よくある質問
Q. YouTube API とは何ですか? A. YouTube の動画・チャンネル・再生リスト・コメントなどの情報を、プログラムから取得したり登録したりする Google の API です。多くの場合、YouTube Data API v3 を指します。
Q. YouTube API キーの取得方法は? A. Google Cloud コンソールでプロジェクトを作り、YouTube Data API v3 を有効にして、「認証情報」→「認証情報を作成」→「API キー」で作ります。作ったら「アプリケーションの制限」と「API の制限」を付けます。
Q. YouTube API は無料で使えますか? A. 確認した YouTube Data API の公式の資料には API の料金表はなく、使える量はクォータで決まります。既定は search.list が1日100回、そのほかの合計が1日10,000ユニットです(2026年11月18日時点)。
Q. YouTube API のクォータ(上限)はいくつですか? A. 2026年6月1日から枠が分かれ、search.list が1日100回、videos.insert が1日100回、そのほかのメソッドの合計が1日10,000ユニットです。videos.batchGetStats は別に1日10,000ユニットです。
Q. search.list は100ユニットではないのですか? A. 改訂履歴では、2014年11月11日に1回100ユニットへ変わったと記されています。2026年6月1日からは専用の枠で1回1、1日100回です。回数の上限は同じですが、10,000ユニットの枠は減らなくなりました。
Q. quotaExceeded が出たらどうしますか? A. その日の枠を使い切っています。再送しても戻らないので、太平洋時間の0時(日本時間16時か17時)を待ちます。結果を保存して使い回す、search.list を playlistItems.list に置き換える、で消費を減らせます。足りなければ申請フォームで増枠を申し込みます。
Q. クォータのリセットは日本時間で何時ですか? A. 太平洋時間の0時です。標準時の間(11月〜3月上旬)は日本時間17時、夏時間の間は16時でした(Python の zoneinfo で計算)。
Q. API キーと OAuth 2.0 はどちらを使いますか? A. 公開されている情報を読むだけなら API キーです。動画の登録・更新・削除、mine=true などログインした本人のデータには OAuth 2.0 が必要です。
Q. チャンネルの全動画を取るには? A. channels.list の contentDetails.relatedPlaylists.uploads で再生リストの ID を取り、playlistItems.list を maxResults=50 で最後のページまで回し、videos.list で50本ずつ情報を取ります。120本で7ユニットでした。
Q. Python ではどう書きますか?
A. pip install google-api-python-client のあと、build('youtube', 'v3', developerKey=キー) でクライアントを作り、yt.videos().list(part='statistics', id='動画ID').execute() の形で呼びます。次のページは list_next() で取れます。
Q. dislike(よくない)の数は取れますか? A. statistics.dislikeCount は2021年12月13日から非公開で、動画の持ち主が認可したリクエストにだけ返ります。API キーでは取れません。
Q. YouTube API で動画をダウンロードできますか? A. この記事では扱いません。デベロッパー ポリシーは、YouTube の事前の書面による承認なしに、動画の音声・映像をダウンロード・保存することを認めていません(提供元の説明)。
まとめ
- YouTube API(Data API v3)は、Google Cloud でプロジェクトを作り、YouTube Data API v3 を有効にして API キーを作れば使える。公開データの読み取りは API キー、登録・更新と本人のデータは OAuth 2.0。
- キーには「アプリケーションの制限」と「API の制限」の両方を付け、コードに直接書かない。
- 2026年6月1日からクォータは枠が分かれ、search.list 1日100回・videos.insert 1日100回・そのほか合計1日10,000ユニット。リセットは太平洋時間の0時(日本時間16時か17時)。
- チャンネルの全動画は search.list ではなく uploads の再生リスト経由で取る。架空の120本のチャンネルで7ユニット、maxResults=50 を明示する。
- 公式の Python クライアントは part の書き忘れを送る前に止め、num_retries は rateLimitExceeded だけ再送して quotaExceeded は再送しなかった。quotaExceeded ではその日の処理を止める。
次に読むとよい記事です。Google Cloud の全体像は関連記事「GCPとは|Google Cloudの主要サービス・料金・無料枠・始め方」、キーの置き場所は関連記事「.envの使い方と注意点|APIキーを安全に管理する方法」で扱っています。
参考・出典
確認日はいずれも 2026年11月18日です。
- Google for Developers「YouTube Data API Overview」(Before you start・Quota usage・Partial resources):https://developers.google.com/youtube/v3/getting-started
- Google for Developers「Quota Calculator」(2026年11月12日更新):https://developers.google.com/youtube/v3/determine_quota_cost
- Google for Developers「YouTube Data API - Revision History」(2014年11月11日・2025年12月4日・2026年6月1日・6月3日・11月16日の項):https://developers.google.com/youtube/v3/revision_history
- Google for Developers「Search: list」:https://developers.google.com/youtube/v3/docs/search/list
- Google for Developers「Videos: list」:https://developers.google.com/youtube/v3/docs/videos/list
- Google for Developers「Videos」(リソースの項目):https://developers.google.com/youtube/v3/docs/videos
- Google for Developers「Videos: batchGetStats」:https://developers.google.com/youtube/v3/docs/videos/batchGetStats
- Google for Developers「Channels: list」「Channels」:https://developers.google.com/youtube/v3/docs/channels/list ・ https://developers.google.com/youtube/v3/docs/channels
- Google for Developers「PlaylistItems: list」:https://developers.google.com/youtube/v3/docs/playlistItems/list
- Google for Developers「YouTube Data API - Errors」:https://developers.google.com/youtube/v3/docs/errors
- Google for Developers「Obtaining authorization credentials」:https://developers.google.com/youtube/registering_an_application
- Google for Developers「YouTube API Services - Developer Policies」(III.D.1・III.E.1・III.E.4):https://developers.google.com/youtube/terms/developer-policies
- Google Cloud「API キーを管理」:https://docs.cloud.google.com/docs/authentication/api-keys?hl=ja
- Google Cloud「API キーを使用して API にアクセスする」:https://docs.cloud.google.com/docs/authentication/api-keys-use?hl=ja
- google-api-python-client 2.202.0 のソース(googleapiclient/http.py の _should_retry_response・同梱の youtube.v3.json):https://github.com/googleapis/google-api-python-client
本記事の内容は、ご自由にお使いください。
ご利用の際は、出典として本ページへのリンクを記載いただけますようお願いします。
(記載例)出典:株式会社RJC「YouTube APIの使い方|APIキー取得と新クォータの計算・Python実例」
株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。
WE ARE HIRING
RJCで一緒に開発しながら、
成長を楽しみませんか?
RJCは、Web・モバイル・AIを活用した開発プロジェクトで、テックリードやPM・PMOも活躍するシステム開発会社です。会社を知る、待遇を確かめる、話を聞いてみる。気になるところ見てみてください!
- 127日年間休日
- 12時間平均残業時間
- 毎日ガチャ遊びココロも大切にする福利厚生。アマギフなどの賞品ラインナップ!
ほかにも、チケットレストラン、書籍読み放題、2年ごとの慰労報奨(休暇 or 金一封)、11期連続の黒字決算。