YouTube Data API Searchリソースの使い方|メソッドごとのHTTPリクエスト・HTTPレスポンスの解説【初心者向け】

eye catching image of how to use the youtube data api search resource IT・AI活用入門

この記事で扱う内容

この記事では、YouTube Data APIのSearchリソースのメソッドごとのHTTPリクエスト・HTTPレスポンスについて解説します。

前提と基本用語

必要な知識・スキル

  • API(Application Programming Interface)に関する基本知識

必要な環境

  • PC

YouTube Data APIのリソースとメソッドとは

YouTube Data APIのリソースとは、動画やチャンネルなどの対象(データの種類)のことです。

YouTube Data APIのメソッドとは、そのリソース(動画やチャンネルなど)に対して行える操作(検索・取得・更新など)のことです。

このリソースとメソッドを組み合わせることで、欲しい情報を取得したり変更したりできます。

実際には、クライアント(ブラウザやライブラリなど)からサーバー(YouTube Data API提供サーバーなど)へHTTPリクエストを送信し、そのサーバーから返信されるHTTPレスポンス(JSON形式のデータなど)を取得して利用することになります。

YouTube Data APIのプロパティとは

YouTube Data APIのプロパティとは、HTTPレスポンス(JSON形式のデータなど)の中に含まれる個々の情報項目のことです。

一般的に、フィールドや項目と表現されることもあります。

例えば、動画のタイトルやID、公開日時などがプロパティとして返されます。

割り当て使用量(quota)とは

割り当て使用量(quota)とは、APIの1日あたりの利用上限値のようなものです。

通常、Google Cloudプロジェクトを作成後、そのプロジェクトでYouTube Data APIを有効にし、認証情報(APIキーやOAuth 2.0認証情報)を作成して、それらを使用してAPIを利用します。

既定の割り当て使用量は、1つのGoogle Cloudプロジェクトにつき、1日あたり10,000ユニットです。

割り当てコスト(quota cost)とは

割り当てコスト(quota cost)とは、APIの利用値のようなものです。

APIを利用するたびに割り当てコストがかかり、割り当て使用量を超えると、その日はAPIが利用できなくなります。

APIによって割り当てコストが異なります。

Searchリソースの使い方

YouTube Data APIのSearchリソースとは、YouTube上の検索対象(動画・チャンネル・再生リスト)のことです。

このリソースのメソッドを使うことで、自作のプログラムなどから、キーワードや条件を指定して目的の動画・チャンネル・再生リストを効率的に探すことができます。

以下のメソッドが提供されています。

Noメソッド名概要割り当てコスト(ユニット)
1list指定したキーワードや条件に合う動画・チャンネル・再生リストを検索し、それらの情報を取得できる。100

listメソッド

HTTPリクエスト

以下は、このメソッドを使うために送信するHTTPリクエストの構成要素です。

リクエストライン
HTTPメソッド
GET
リクエストターゲット
https://www.googleapis.com/youtube/v3/search
HTTPバージョン

YouTube Data APIの公式リファレンスでは、HTTPバージョンが省略されています。

通常、クライアント(ブラウザやライブラリなど)とAPI提供サーバー(YouTube Data API提供サーバーなど)間の通信時、それぞれのHTTPバージョン対応状況をもとに自動的に選ばれます。

Google API提供サーバーは、以下のプロトコルに対応しているようです。

  • HTTP/1.0
  • HTTP/1.1
  • SPDY/*
  • HTTP/2
  • QUIC 

クエリ

以下は、このメソッドで使えるクエリのパラメータです。

必須パラメータ

設定は必須です。

パラメータ設定値概要
part
(検索結果に含める情報の種類)
以下から1つ以上を設定。
・snippet
(動画タイトル、動画概要、チャンネル名、公開日時などを含める)
検索結果に「どの種類の情報を含めるか」を指定するパラメータ。
part

検索結果に「どの種類の情報を含めるか」を指定します。

プログラムから実行する場合、値は「string」型で指定します。

リクエストライン例)

GET https://www.googleapis.com/youtube/v3/search?part=snippet&key=あなたのAPIキー

試しにブラウザのURLバーに“必須パラメータ「part」なし”のURLを入力し、実行してみたところ、成功の場合のHTTPレスポンスボディが返ってきました。

各リソースの各メソッドによって挙動が違うかもしれませんが、必須パラメータなしの場合、エラーのHTTPレスポンスボディが返ってくるとは限らないようです。

例)

・リクエストライン

GET https://www.googleapis.com/youtube/v3/search?q=猫&key=APIキー

・HTTPレスポンスボディ

{
  "kind": "youtube#searchListResponse",
  "etag": "BwAn5Gr12PWd7Zu7p9MuwrL-6uQ",
  "nextPageToken": "CAUQAA",
  "regionCode": "JP",
  "pageInfo": {
    "totalResults": 1000000,
    "resultsPerPage": 5
  },
  "items": [
    {
      "kind": "youtube#searchResult",
      "etag": "bC6aScBNtNGzx0ize3iAHeXlt88",
      "id": {
        "kind": "youtube#video",
        "videoId": "1KgAear9rao"
      }
    },
    {
      "kind": "youtube#searchResult",
      "etag": "00uqIQsPfjWGed3eAbd8lgbELZ4",
      "id": {
        "kind": "youtube#video",
        "videoId": "fA-Xt7ZdVvM"
      }
    },
    {
      "kind": "youtube#searchResult",
      "etag": "I0MgSWVOj8b_3MhN-DEJ1Rlg7pE",
      "id": {
        "kind": "youtube#video",
        "videoId": "5wBm2pNnLIo"
      }
    },
    {
      "kind": "youtube#searchResult",
      "etag": "VEdR2Mw2wXtJAA1c35bBzwKsfho",
      "id": {
        "kind": "youtube#video",
        "videoId": "QcvupLwTiKc"
      }
    },
    {
      "kind": "youtube#searchResult",
      "etag": "4OvU09Z6Rncd-5cmwyepugQijKg",
      "id": {
        "kind": "youtube#video",
        "videoId": "gsT6eKsnT0M"
      }
    }
  ]
}
フィルタパラメータ

設定は任意です。

もし設定する場合、「いずれか1つだけ」を設定します。

パラメータ設定値概要
forContentOwner
(コンテンツ所有者用の検索)
以下のどちらかを設定。
・true
・false
特定のチャンネル全体に限定して検索したいときに指定するパラメータ。

true:限定する
false:限定しない
forDeveloper
(開発者用の検索)
以下のどちらかを設定。
・true
・false
特定のアプリやWebサービスからアップロードされた動画に限定して検索したいときに指定するパラメータ。

true:限定する
false:限定しない
forMine
(YouTubeチャンネル所有者用の検索)
以下のどちらかを設定。
・true
・false
特定のYouTubeチャンネルの動画に限定して検索したいときに指定するパラメータ。

true:限定する
false:限定しない

いずれも、OAuth 2.0認証が必須です。
(APIキーでは利用できません)

forContentOwner

YouTubeコンテンツパートナー用のパラメータです。

特定の管理対象全体に限定して検索したいときに指定します。

プログラムから実行する場合、値は「boolean」型で指定します。

このパラメータを使うときの条件

  • OAuth 2.0 認証が必須(APIキーでは利用できない)。
  • ユーザーが「コンテンツ所有者権限」を持っていること。

このパラメータを使うときの制約

  • 任意パラメータの「type」に「video」を指定する必要がある。
  • 以下の任意パラメータは指定できない。
    • videoDefinition
    • videoDimension
    • videoDuration
    • videoEmbeddable
    • videoLicense
    • videoPaidProductPlacement
    • videoSyndicated
    • videoType

HTTPリクエスト例)

・リクエストライン

GET https://www.googleapis.com/youtube/v3/search?forContentOwner=true&type=video

・HTTPリクエストヘッダー

Authorization: Bearer {OAuth 2.0認証で取得したアクセストークン}

OAuth 2.0認証の場合、HTTPリクエストヘッダーにアクセストークンを付けてリクエストを送信する必要があります(上記の例だと「{OAuth 2.0認証で取得したアクセストークン}」の部分)。

そのため、ブラウザでURLを送信して結果を取得するような方法では利用できません。

PowerShellのInvoke-RestMethodコマンドやその他プログラムを使ってリクエストを送信することになると思います。

forDeveloper

YouTube Data API経由で動画アップロード機能を提供しているアプリやWebサービスの開発者用のパラメータです。

特定のアプリやWebサービスからアップロードされた動画だけを検索したいときに使うことがあると思います。

プログラムから実行する場合、値は「boolean」型で指定します。

このパラメータを使うときの条件

  • OAuth 2.0認証が必須(APIキーでは利用できない)。
  • 開発者のGoogle Cloud Consoleに、アプリやWebサービスのプロジェクトが存在すること。

このパラメータを使うときの制約

他の「forContentOwner」と「forMine」では、公式リファレンスに制約が明記されていますが、この「forDeveloper」には明記されていません。

しかし、対象は動画に限られるなど、機能の性質上、実際には他のパラメータ同様の制約が想定されます。

実際の挙動については、検証する必要があります。

HTTPリクエスト例)

・リクエストライン

GET https://www.googleapis.com/youtube/v3/search?forDeveloper=true&type=video

・HTTPリクエストヘッダー

Authorization: Bearer {OAuth 2.0認証で取得したアクセストークン}

OAuth 2.0認証の場合、HTTPリクエストヘッダーにアクセストークンを付けてリクエストを送信する必要があります(上記の例だと「{OAuth 2.0認証で取得したアクセストークン}」の部分)。

そのため、ブラウザでURLを送信して結果を取得するような方法では利用できません。

PowerShellのInvoke-RestMethodコマンドやその他プログラムを使ってリクエストを送信することになると思います。

forMine

YouTubeチャンネル所有者用のパラメータです。

特定のYouTubeチャンネルの動画だけを検索したいときに使うことがあると思います。

プログラムから実行する場合、値は「boolean」型で指定します。

このパラメータを使うときの条件

  • OAuth 2.0認証が必須(APIキーでは利用できない)。
  • 検索対象が自分の所有するYouTubeチャンネルの動画であること。

このパラメータを使うときの制約

  • 任意パラメータの「type」に「video」を指定する必要がある。
  • 以下の任意パラメータは指定できない。
    • videoDefinition
    • videoDimension
    • videoDuration
    • videoEmbeddable
    • videoLicense
    • videoPaidProductPlacement
    • videoSyndicated
    • videoType

HTTPリクエスト例)

・リクエストライン

GET https://www.googleapis.com/youtube/v3/search?forMine=true&type=video

・HTTPリクエストヘッダー

Authorization: Bearer {OAuth 2.0認証で取得したアクセストークン}

OAuth 2.0認証の場合、HTTPリクエストヘッダーにアクセストークンを付けてリクエストを送信する必要があります(上記の例だと「{OAuth 2.0認証で取得したアクセストークン}」の部分)。

そのため、ブラウザでURLを送信して結果を取得するような方法では利用できません。

PowerShellのInvoke-RestMethodコマンドやその他プログラムを使ってリクエストを送信することになると思います。

オプションパラメータ

設定は任意です。

もし設定する場合、中には「他のパラメータと組み合わせないと使えないもの」や「自動的に他パラメータと組み合わせられるもの」があるので注意が必要です。

パラメータ設定値概要
channelId
(チャンネルID)
任意のチャンネルID

例:UCrXUsMBcfTVqwAS7DKg9C0Q
(YouTube Japan 公式チャンネルのチャンネルID)
検索対象のチャンネルIDを指定するパラメータ。
channelType
(チャンネル種類)
以下のいずれか1つを設定。
・any
(すべて)
・show
(番組のみ)
※既定値は「any」。
検索対象のチャンネル種類を指定するパラメータ。

※番組とは、公式番組提供者向けの番組チャンネルが提供する動画のこと。通常のチャンネルの動画やライブ配信とは異なる。
eventType
(ライブ配信の状態)
以下のいずれか1つを設定。
・completed
(ライブ配信完了)
・live
(ライブ配信中)
・upcoming
(ライブ配信予定)
検索対象のライブ配信の状態を指定するパラメータ。

※あわせて「type」パラメータに「video」を指定する必要あり。
location
(地理的な中心位置)
任意の緯度と経度の座標

例:37.42307,-122.08427
検索対象の地理的な中心位置を指定するパラメータ。

※あわせて「locationRadius」パラメータを指定し、「type」パラメータに「video」を指定する必要あり。
locationRadius
(地理的な中心位置からの半径)
任意の1,000km以下の距離

例:5.5km
検索対象の位置情報の半径を指定するパラメータ。

※浮動小数点数の後に測定単位(有効はm、km、ft、mi)を付けて指定する。
※あわせて「location」パラメータを指定し、「type」パラメータに「video」を指定する必要あり。
maxResults
(検索結果の取得件数)
0~50
※既定値は「5」。
検索結果の件数を指定するパラメータ。
onBehalfOfContentOwner
(コンテンツ所有者アカウントID)
任意のコンテンツ所有者アカウントID

例:abcd1234
(Googleから付与されるID)
特定のコンテンツ所有者アカウントIDを指定するパラメータ。

※YouTubeコンテンツパートナー専用パラメータ。
※OAuth 2.0認証が必須(APIキーでは利用できない)。
order
(検索結果の並び順)
以下のいずれか1つを設定。
・date
(作成日時の新しい順)
・rating
(評価の高い順)
・relevance
(関連性の高い順)
・title
(タイトルのアルファベット順)
・videoCount
(アップロードされた動画数の多い順)
・viewCount
(動画は表示回数の多い順、ライブ配信は同時視聴者数の多い順)
※既定値は「relevance」。
検索結果の並び順を指定するパラメータ。
pageToken
(ページトークン)
任意のページトークン

例:ABCDEF
検索結果の特定ページを指定するパラメータ。

※検索結果が多い場合、検索結果はページ単位に分割され、それぞれにページトークンが割り振られる。
publishedAfter
(公開日時の下限(これ以降))
任意のRFC 3339形式の日時

例:2024-12-31T15:00:00Z
(日本時間の2025-01-01 00:00:00)
検索対象の公開日時の下限(これ以降)を指定するパラメータ。

※UTC(世界協定時刻)で解釈されるため、日本時間を指定する場合は、日本時間から9時間引いた日時を指定する。
publishedBefore
(公開日時の上限(これ以前))
任意のRFC 3339形式の日時

例:2025-12-31T14:59:59Z
(日本時間の2025-12-31 23:59:59)
検索対象の公開日時の上限(これ以前)を指定するパラメータ。

※UTC(世界協定時刻)で解釈されるため、日本時間を指定する場合は、日本時間から9時間引いた日時を指定する。
q
(検索キーワード)
任意のキーワード

例:猫
例:猫|犬
例:猫|犬 -鳥
検索キーワードを指定するパラメータ。

※「-(否定)」や「|(または)」記号をキーワード前に付けることで、特定のキーワードを除外したり、複数の検索キーワードで検索したりできる。
regionCode
(動画を視聴できる国のコード)
任意のISO 3166-1 alpha-2形式の国コード

例:JP
(日本の国コード)
検索対象の動画を視聴できる国のコードを指定するパラメータ。

※ユーザーの視聴可能性をもとに選別するだけで、動画投稿元の国を指定するものではない。
relevanceLanguage
(関連性の高い言語コード)
任意のISO 639-1(2文字)の言語コード

例:ja
(日本の言語コード)
検索対象と関連性の高い言語のコードを指定するパラメータ。
safeSearch
(検索の安全レベル)
以下のいずれか1つを設定。
・moderate
(一部のコンテンツを除外(少なくとも、ユーザーの言語・地域で制限されているコンテンツは除外))
・none
(何も除外しない)
・strict
(すべての制限付きコンテンツを除外)
※既定値は「moderate」
検索結果の安全レベルを指定するパラメータ。
topicId
(FreebaseトピックID)
任意のFreebaseのトピックID

例:/m/04rlf
(Music)
検索対象と関連性の高いFreebaseのトピックIDを指定するパラメータ。

※Freebase は既に公式に非推奨。使用可能なFreebaseトピックIDは不明。
type
(検索対象の種類)
以下から1つ以上を設定。
・channel
(チャンネル)
・playlist
(再生リスト)
・video
(動画)
※既定値は、「video,channel,playlist」。
検索するリソースの種類(動画、チャンネル、再生リスト)を指定するパラメータ。
videoCaption
(動画の字幕有無)
以下のいずれか1つを設定。
・any
(すべて)
・closedCaption
(字幕有りのみ)
・none
(字幕無しのみ)
検索対象の動画の字幕有無を指定するパラメータ。

※あわせて「type」パラメータに「video」を指定する必要あり。
videoCategoryId
(動画カテゴリーID)
任意の動画カテゴリーID

例:22
(ブログ)
検索対象の動画のカテゴリーIDを指定するパラメータ。

※あわせて「type」パラメータに「video」を指定する必要あり。
videoDefinition
(動画の解像度)
以下のいずれか1つを設定。
・any
(すべて)
・high
(高画質(HD)の動画のみ)
・standard
(標準画質(SD)の動画のみ)
検索対象の動画の解像度を指定するパラメータ。

※あわせて「type」パラメータに「video」を指定する必要あり。
videoDimension
(動画の画面次元)
以下のいずれか1つを設定。
・2d
(2D動画のみ)
・3d
(3D動画のみ)
・any
(すべて)
※既定値は「any」。
検索対象の動画の画面次元を指定するパラメータ。

※あわせて「type」パラメータに「video」を指定する必要あり。
videoDuration
(動画の再生時間)
以下のいずれか1つを設定。
・any
(すべて)
・long
(20分超)
・medium
(4~20分)
・short
(4分未満)
※既定値は「any」。
検索対象の動画の再生時間を指定するパラメータ。

※あわせて「type」パラメータに「video」を指定する必要あり。
videoEmbeddable
(動画の埋め込み可否)
以下のいずれか1つを設定。
・any
(すべて)
・true
(埋め込み可能な動画のみ)
検索対象の動画の埋め込み可否を指定するパラメータ。

※あわせて「type」パラメータに「video」を指定する必要あり。
videoLicense
(動画のライセンス種別)
以下のいずれか1つを設定。
・any
(すべて)
・creativeCommon
(クリエイティブ・コモンズライセンスを持つ動画のみ)
・youtube
(標準のYouTubeライセンスを持つ動画のみ)
検索対象の動画のライセンス種別を指定するパラメータ。

※あわせて「type」パラメータに「video」を指定する必要あり。
videoPaidProductPlacement
(動画の商品プロモーション表示有無)
以下のいずれか1つを設定。
・any
(すべて)
・true
(有料プロモーションを含む動画のみ)
検索対象の動画内の商品プロモーション有無を指定するパラメータ。

※YouTube広告の有無ではない。
※あわせて「type」パラメータに「video」を指定する必要あり。
videoSyndicated
(動画の配信範囲)
以下のいずれか1つを設定。
・any
(すべて)
・true
(シンジケーション動画(youtube.com以外でも再生できる動画)のみ)
検索対象の動画の配信範囲を指定するパラメータ。
※あわせて「type」パラメータに「video」を指定する必要あり。
videoType
(動画種類)
以下のいずれか1つを設定。
・any
(すべて)
・episode
(番組エピソードのみ)
・movie
(映画のみ)
検索対象の動画種類を指定するパラメータ。

※映画とは、YouTubeが公式に提供している映画動画のこと。通常の動画とは異なる。
※あわせて「type」パラメータに「video」を指定する必要あり。
channelId

検索するチャンネルのIDを指定するパラメータです。

特定のチャンネルに限定した検索ができます。

プログラムから実行する場合、値は「string」型で指定します。

リクエストライン例)

GET https://www.googleapis.com/youtube/v3/search?part=snippet&channelId=UCrXUsMBcfTVqwAS7DKg9C0Q&key=あなたのAPIキー
channelType

検索対象のチャンネル種類を指定するパラメータです。

番組チャンネルが提供する番組動画に限定した検索ができます。

プログラムから実行する場合、値は「string」型で指定します。

リクエストライン例)

GET https://www.googleapis.com/youtube/v3/search?part=snippet&channelType=show&key=あなたのAPIキー

番組チャンネルとは、公式番組提供者向けの特殊チャンネルです。

番組チャンネルが提供する動画のことを「番組」と呼び、通常の動画やライブ配信とは異なります。

eventType

検索対象のライブ配信の状態を指定するパラメータです。

動画のライブ配信状態で限定した検索ができます。

プログラムから実行する場合、値は「string」型で指定します。

このパラメータを使うときの制約

  • 「type」パラメータに「video」を指定する必要がある。

リクエストライン例)

GET https://www.googleapis.com/youtube/v3/search?part=snippet&eventType=completed&type=video&key=あなたのAPIキー
location

検索対象の地理的な中心位置を指定するパラメータです。

「locationRadius」パラメータと組み合わせて、円形の地理的範囲を指定します。

指定した地理的範囲をメタデータ(タイトル、説明文、タグなど)に設定している動画に限定した検索ができます。

プログラムから実行する場合、値は「string」型で指定します。

このパラメータを使うときの制約

  • 「type」パラメータに「video」を指定する必要がある。
  • 「locationRadius」パラメータに値を指定する必要がある。

リクエストライン例)

GET https://www.googleapis.com/youtube/v3/search?part=snippet&location=37.42307,-122.08427&locationRadius=5.5km&type=video&key=あなたのAPIキー
locationRadius

検索対象の位置情報の半径を指定するパラメータです。

「location」パラメータと組み合わせて、円形の地理的範囲を指定します。

指定した地理的範囲をメタデータ(タイトル、説明文、タグなど)に設定している動画に限定した検索ができます。

設定値は、浮動小数点数の後に測定単位を付けて指定する必要があり、有効な測定単位は以下の通りです。

  • m(メートル)
  • km(キロメートル)
  • ft(フィート)
  • mi(マイル)

※1,000kmを超える設定値には、対応していません。

プログラムから実行する場合、値は「string」型で指定します。

このパラメータを使うときの制約

  • 「type」パラメータに「video」を指定する必要がある。
  • 「location」パラメータに値を指定する必要がある。

リクエストライン例)

GET https://www.googleapis.com/youtube/v3/search?part=snippet&location=37.42307,-122.08427&locationRadius=5.5km&type=video&key=あなたのAPIキー
maxResults

検索結果の件数を指定するパラメータです。

検索結果の件数を制御できます。

プログラムから実行する場合、値は「unsigned integer」型で指定します。

リクエストライン例)

GET https://www.googleapis.com/youtube/v3/search?part=snippet&maxResults=50&key=あなたのAPIキー

実際の検索結果が「maxResults」で設定した件数より多い場合

実際の検索結果が「maxResults」で設定した件数より多い場合、検索結果に「nextPageToken」プロパティの値が含まれて返ってきます。

再度、この「nextPageToken」の値を「pageToken」パラメータに設定して検索することで、前回の「maxResults」で設定した件数より多い部分の情報を取得できます。

また、「nextPageToken」の他に「prevPageToken」プロパティがあり、検索結果の前後の結果をページ移動するように検索して取得することができます。

onBehalfOfContentOwner

YouTubeコンテンツパートナー専用パラメータで、特定のコンテンツ所有者アカウントIDを指定するパラメータです。

Googleから付与されるIDを指定します。

プログラムから実行する場合、値は「string」型で指定します。

このパラメータを使うときの条件

  • OAuth 2.0 認証が必須(APIキーでは利用できない)。
  • ユーザーが「コンテンツ所有者権限」を持っていること。

HTTPリクエスト例)

・リクエストライン

GET https://www.googleapis.com/youtube/v3/search?part=snippet&onBehalfOfContentOwner=abcd1234

・HTTPリクエストヘッダー

Authorization: Bearer {OAuth 2.0認証で取得したアクセストークン}

OAuth 2.0認証の場合、HTTPリクエストヘッダーにアクセストークンを付けてリクエストを送信する必要があります(上記の例だと「{OAuth 2.0認証で取得したアクセストークン}」の部分)。

そのため、ブラウザでURLを送信して結果を取得するような方法では利用できません。

PowerShellのInvoke-RestMethodコマンドやその他プログラムを使ってリクエストを送信することになると思います。

order

検索結果の並び順を指定するパラメータです。

検索結果の並び順を制御できます。

プログラムから実行する場合、値は「string」型で指定します。

リクエストライン例)

GET https://www.googleapis.com/youtube/v3/search?part=snippet&order=date&key=あなたのAPIキー
pageToken

検索結果の特定ページを指定するパラメータです。

検索結果が多い場合、検索結果はページ単位に分割され、それぞれにページトークンが割り振られます。

そのような場合、割り振られたページトークンを指定することで、特定のページを検索できます。

プログラムから実行する場合、値は「string」型で指定します。

リクエストライン例)

GET https://www.googleapis.com/youtube/v3/search?part=snippet&pageToken=ABCDEF&key=あなたのAPIキー
publishedAfter

検索対象の公開日時の下限(これ以降)を指定するパラメータです。

日時は、RFC 3339形式で指定する必要があります。

また、日時は、UTC(世界協定時刻)で解釈されるため、日本時間を指定する場合は、日本時間から9時間引いた日時を指定する必要があります。

プログラムから実行する場合、値は「datetime」型で指定します。

リクエストライン例)

GET https://www.googleapis.com/youtube/v3/search?part=snippet&publishedAfter=2024-12-31T15:00:00Z&key=あなたのAPIキー
publishedBefore

検索対象の公開日時の上限(これ以前)を指定するパラメータです。

日時は、RFC 3339形式で指定する必要があります。

また、日時は、UTC(世界協定時刻)で解釈されるため、日本時間を指定する場合は、日本時間から9時間引いた日時を指定する必要があります。

プログラムから実行する場合、値は「datetime」型で指定します。

リクエストライン例)

GET https://www.googleapis.com/youtube/v3/search?part=snippet&publishedBefore=2025-12-31T14:59:59Z&key=あなたのAPIキー
q

検索キーワードを指定するパラメータです。

キーワードに関連する情報を検索できます。

キーワードに「-(否定)」や「|(または)」記号を付けることで、特定のキーワードを除外したり、複数の検索キーワードに関連する情報を検索したりできます。

プログラムから実行する場合、値は「string」型で指定します。

リクエストライン例)

GET https://www.googleapis.com/youtube/v3/search?part=snippet&q=猫&key=あなたのAPIキー
regionCode

検索対象の動画を視聴できる国のコードを指定するパラメータです。

設定値は、ISO 3166-1 alpha-2形式の国コードを指定する必要があります。

プログラムから実行する場合、値は「string」型で指定します。

リクエストライン例)

GET https://www.googleapis.com/youtube/v3/search?part=snippet®ionCode=JP&key=あなたのAPIキー

ユーザーの視聴可能性をもとに選別するだけであって、「動画の投稿元の国を指定するものではない」ことに注意してください。

relevanceLanguage

検索対象と関連性の高い言語のコードを指定するパラメータです。

特定の言語と関連性が高い動画を検索できます。

リクエストライン例)

GET https://www.googleapis.com/youtube/v3/search?part=snippet&relevanceLanguage=ja&key=あなたのAPIキー

完全にその言語だけに限定されるわけではない」ことに注意してください。動画のメタデータ(タイトル、説明文、タグなど)に基づいて関連性が決まるようです。

safeSearch

検索結果の安全レベルを指定するパラメータです。

制限付きコンテンツの有無で限定した検索ができます。

プログラムから実行する場合、値は「string」型で指定します。

リクエストライン例)

GET https://www.googleapis.com/youtube/v3/search?part=snippet&safeSearch=strict&key=あなたのAPIキー
topicId

検索対象と関連性の高いFreebaseのトピックIDを指定するパラメータです。

FreebaseのトピックIDに限定した検索ができます。

プログラムから実行する場合、値は「string」型で指定します。

リクエストライン例)

GET https://www.googleapis.com/youtube/v3/search?part=snippet&topicId=/m/04rlf&key=あなたのAPIキー

Freebase は既に公式に非推奨です。

公式リファレンスを確認しましたが、使用可能なFreebaseトピックIDは明記されていませんでした。

type

検索するリソースの種類(動画、チャンネル、再生リスト)を指定するパラメータです。

特定のリソースの種類(動画、チャンネル、再生リスト)に限定した検索ができます。

プログラムから実行する場合、値は「string」型で指定します。

リクエストライン例)

GET https://www.googleapis.com/youtube/v3/search?part=snippet&type=video&key=あなたのAPIキー
videoCaption

検索対象の動画の字幕有無を指定するパラメータです。

動画の字幕有無で限定した検索ができます。

プログラムから実行する場合、値は「string」型で指定します。

このパラメータを使うときの制約

  • 「type」パラメータに「video」を指定する必要がある。

リクエストライン例)

GET https://www.googleapis.com/youtube/v3/search?part=snippet&videoCaption=closedCaption&type=video&key=あなたのAPIキー
videoCategoryId

検索対象の動画のカテゴリーIDを指定するパラメータです。

特定のカテゴリーが設定された動画に限定した検索ができます。

具体的なカテゴリーIDについては、「VideoCategoriesリソースのlistメソッド」で取得できます。

このパラメータを使うときの制約

  • 「type」パラメータに「video」を指定する必要がある。

リクエストライン例)

GET https://www.googleapis.com/youtube/v3/search?part=snippet&videoCategoryId=22&type=video&key=あなたのAPIキー
videoDefinition

検索対象の動画の解像度を指定するパラメータです。

動画の解像度で限定した検索ができます。

プログラムから実行する場合、値は「string」型で指定します。

このパラメータを使うときの制約

  • 「type」パラメータに「video」を指定する必要がある。

リクエストライン例)

GET https://www.googleapis.com/youtube/v3/search?part=snippet&videoDefinition=high&type=video&key=あなたのAPIキー
videoDimension

検索対象の動画の画面次元を指定するパラメータです。

動画の画面次元で限定した検索ができます。

プログラムから実行する場合、値は「string」型で指定します。

このパラメータを使うときの制約

  • 「type」パラメータに「video」を指定する必要がある。

リクエストライン例)

GET https://www.googleapis.com/youtube/v3/search?part=snippet&videoDimension=2d&type=video&key=あなたのAPIキー
videoDuration

検索対象の動画の再生時間を指定するパラメータです。

特定の再生時間の動画に限定した検索ができます。

このパラメータを使うときの制約

  • 「type」パラメータに「video」を指定する必要がある。

リクエストライン例)

GET https://www.googleapis.com/youtube/v3/search?part=snippet&videoDuration=short&type=video&key=あなたのAPIキー
videoEmbeddable

検索対象の動画の埋め込み可否を指定するパラメータです。

動画の埋め込み可否で限定した検索ができます。

プログラムから実行する場合、値は「string」型で指定します。

このパラメータを使うときの制約

  • 「type」パラメータに「video」を指定する必要がある。

リクエストライン例)

GET https://www.googleapis.com/youtube/v3/search?part=snippet&videoEmbeddable=true&type=video&key=あなたのAPIキー
videoLicense

検索対象の動画のライセンス種別を指定するパラメータです。

動画のライセンス種別で限定した検索ができます。

プログラムから実行する場合、値は「string」型で指定します。

このパラメータを使うときの制約

  • 「type」パラメータに「video」を指定する必要がある。

リクエストライン例)

GET https://www.googleapis.com/youtube/v3/search?part=snippet&videoLicense=creativeCommon&type=video&key=あなたのAPIキー
videoPaidProductPlacement

検索対象の動画内の商品プロモーション有無を指定するパラメータです。

動画内の商品プロモーション有無で限定した検索ができます。

プログラムから実行する場合、値は「string」型で指定します。

このパラメータを使うときの制約

  • 「type」パラメータに「video」を指定する必要がある。

リクエストライン例)

GET https://www.googleapis.com/youtube/v3/search?part=snippet&videoPaidProductPlacement=true&type=video&key=あなたのAPIキー
videoSyndicated

検索対象の動画の配信範囲を指定するパラメータです。

動画の配信範囲に限定した検索ができます。

プログラムから実行する場合、値は「string」型で指定します。

このパラメータを使うときの制約

  • 「type」パラメータに「video」を指定する必要がある。

リクエストライン例)

GET https://www.googleapis.com/youtube/v3/search?part=snippet&videoSyndicated=true&type=video&key=あなたのAPIキー
videoType

検索対象の動画種類を指定するパラメータです。

動画種類に限定した検索ができます。

プログラムから実行する場合、値は「string」型で指定します。

このパラメータを使うときの制約

  • 「type」パラメータに「video」を指定する必要がある。

リクエストライン例)

GET https://www.googleapis.com/youtube/v3/search?part=snippet&videoType=movie&type=video&key=あなたのAPIキー
オプションパラメータの使用頻度別一覧

個人的な使用感ですが、オプションパラメータを使用頻度別に分けしてみました

もちろん、APIの利用用途によって変わる部分なので、すべての方に当てはまるとは思いませんが、初学者の方でしたら、以下の優先順位で覚えるのも良いのではないかと思います。

よく使う
  • maxResults(検索結果の取得件数)
  • order(検索結果の並び順)
  • pageToken(ページトークン)
  • q(検索キーワード)
  • type(検索対象の種類)
まあまあ使う
  • channelId(チャンネルID)
  • publishedAfter(公開日時の下限(これ以降))
  • publishedBefore(公開日時の上限(これ以前))
  • videoCategoryId(動画カテゴリーID)
  • videoDuration(動画の再生時間)
たまに使う
  • eventType(ライブ配信の状態)
  • regionCode(動画を視聴できる国のコード)
  • relevanceLanguage(関連性の高い言語コード)
ほぼ使わない
  • channelType(チャンネル種類)
  • location(地理的な中心位置)
  • locationRadius(地理的な中心位置からの半径)
  • onBehalfOfContentOwner(コンテンツ所有者アカウントID)
  • safeSearch(検索の安全レベル)
  • topicId(FreebaseトピックID)
  • videoCaption(動画の字幕有無)
  • videoDefinition(動画の解像度)
  • videoDimension(動画の画面次元)
  • videoEmbeddable(動画の埋め込み可否)
  • videoLicense(動画のライセンス種別)
  • videoPaidProductPlacement(動画の商品プロモーション表示有無)
  • videoSyndicated(動画の配信範囲)
  • videoType(動画種類)
HTTPリクエストヘッダー
Authorization

OAuth 2.0認証を使う場合に必須です。

HTTPリクエストヘッダー例)

Authorization: Bearer {OAuth 2.0認証で取得したアクセストークン}
If-Match

ETagを使用してキャッシュ制御をしたいときに使います。

「ETag が一致する場合」にAPIを実行します。

HTTPリクエストヘッダー例)

If-Match: "W/\"{過去に取得したレスポンスに含まれていたETag}\""
If-None-Match

ETagを使用してキャッシュ制御をしたいときに使います。

「ETag が一致しない場合」にAPIを実行します。

HTTPリクエストヘッダー例)

If-None-Match: "W/\"{過去に取得したレスポンスに含まれていたETag}\""
Accept-Encoding: gzip

HTTPレスポンスをgzip圧縮したいときに使います。

YouTube Data APIは、「gzip圧縮」に対応しています。

HTTPリクエストヘッダー例)

Accept-Encoding: gzip
User-Agent: {プログラム名} (gzip)

YouTube Data APIではgzip圧縮を利用する場合、HTTPリクエストヘッダーに「Accept-Encoding: gzip」を指定することに加え、「User-Agent」に「gzip」という文字列を含めて指定する必要があります。

HTTPリクエストボディ

このメソッドでは不要なため、指定しないこと。

HTTPレスポンス

HTTPリクエストを送信すると、HTTPレスポンスが返ってきます。

HTTPレスポンスボディ
成功の場合

HTTPレスポンスボディは大きく分けて、以下の要素で構成されています。

  • Searchリソースのlistメソッドのレスポンス全体(youtube#searchListResponseという種類のリソース)
    ※以降、「Search:listレスポンス」 と呼びます。
  • 検索結果(youtube#searchResultという種類のリソース)

1つのSearch:listレスポンスの中に、1つ~複数の検索結果が含まれます。

以下のようなHTTPレスポンスボディが返ってきます。

{
  "kind": "youtube#searchListResponse",
  "etag": etag,
  "nextPageToken": string,
  "prevPageToken": string,
  "regionCode": string,
  "pageInfo": {
    "totalResults": integer,
    "resultsPerPage": integer
  },
  "items": [
    {
      "kind": "youtube#searchResult",
      "etag": etag,
      "id": {
        "kind": string,
        "videoId": string,
        "channelId": string,
        "playlistId": string
      },
      "snippet": {
        "publishedAt": datetime,
        "channelId": string,
        "title": string,
        "description": string,
        "thumbnails": {
          "default": {
            "url": string,
            "width": unsigned integer,
            "height": unsigned integer
          },
          "medium": {
            "url": string,
            "width": unsigned integer,
            "height": unsigned integer
          },
          "high": {
            "url": string,
            "width": unsigned integer,
            "height": unsigned integer
          },
          "standard": {
            "url": string,
            "width": unsigned integer,
            "height": unsigned integer
          },
          "maxres": {
            "url": string,
            "width": unsigned integer,
            "height": unsigned integer
          },
        },
        "channelTitle": string,
        "liveBroadcastContent": string
      }
    }
  ]
}
失敗(エラー)の場合

HTTPリクエストに失敗すると以下のようにHTTPレスポンスボディが返ってきます。

以下はAPIキーを設定しなかった場合のHTTPレスポンスボディです。

{
  "error": {
    "code": 403,
    "message": "Method doesn't allow unregistered callers (callers without established identity). Please use API Key or other form of API consumer identity to call this API.",
    "errors": [
      {
        "message": "Method doesn't allow unregistered callers (callers without established identity). Please use API Key or other form of API consumer identity to call this API.",
        "domain": "global",
        "reason": "forbidden"
      }
    ],
    "status": "PERMISSION_DENIED"
  }
}
youtube#searchListResponseリソースのプロパティ
プロパティ値の型と例概要
kind文字列(string)

例:”youtube#searchListResponse”
HTTPレスポンスボディのリソース種類。
固定値。
etag文字列(string)

例:”pV8eQZStdeClPWW92xVaB4piKe8″
リソースのEtag。

※Etagは、キャッシュ制御や変更検出に使う識別子のこと。
nextPageToken文字列(string)

例:”CGQQAA”
次のページを取得するときに指定するトークン。
prevPageToken文字列(string)

例:”CDIQAQ”
前のページを取得するときに指定するトークン。
regionCode文字列(string)

例:”JP”
※既定値は「US」。
検索時に指定された国コード。
オプションパラメータ「regionCode」に指定した値。
pageInfoオブジェクト(object)

例:
{
“totalResults”: 1000000,
“resultsPerPage”: 50
}
ページ情報。
以下のプロパティを含むオブジェクト。
・totalResults
・resultsPerPage
pageInfo.totalResults数値(integer)

例:1000000
検索結果の総件数(近似値)。
最大値は、1,000,000。
pageInfo.resultsPerPage数値(integer)

例:50
検索結果1ページあたりの件数。
HTTPリクエストで指定したオプションパラメータ「maxResults」で制御される。
itemsリスト(list)

例:
[
{
“kind”: “youtube#searchResult”,
(省略)
},
{
“kind”: “youtube#searchResult”,
(省略)
},
(省略)
]
検索結果(youtube#searchResultリソース)のリスト。
動画/チャンネル/再生リストごとの情報が含まれる。
youtube#searchResultリソースのプロパティ
プロパティ値の型と例概要
kind文字列(string)

例:”youtube#searchResult”
検索結果のリソース種類。
固定値。
etag文字列(string)

例:”hcqmUk7eiRuvRxF9tP89uH4c4NA”
リソースのEtag。
※Etagは、キャッシュ制御や変更検出に使う識別子のこと。
idオブジェクト(object)

例:
{
“kind”: “youtube#video”,
“videoId”: “p6h57WqRRl8”
}
ID情報。
以下のプロパティを含むオブジェクト。
・kind
・videoId、channelId、playlistIdのいずれか
id.kind文字列(string)

例:”youtube#video”
例:”youtube#channel”
例:”youtube#playlist”
検索結果のリソース種類。
固定値。
動画、チャンネル、再生リストごとに値が変わる。
id.videoId文字列(string)

例:”p6h57WqRRl8″
動画ID。

※このプロパティは、id.kindプロパティの値が「”youtube#video”」の場合に存在する。
id.channelId文字列(string)

例:”UCTDMT3aL30noTVFgNPA9XtQ”
チャンネルID。

※このプロパティは、id.kindプロパティの値が「”youtube#channel”」の場合に存在する。
id.playlistId文字列(string)

例:”PLmnMiSXtJEB1MLExnImqhHsHG6MevUrG-“
再生リストID。

※このプロパティは、id.kindプロパティの値が「”youtube#playlist”」の場合に存在する。
snippetオブジェクト(object)

例:
{
“publishedAt”: “2024-12-04T15:00:58Z”,
“channelId”: “UCTDMT3aL30noTVFgNPA9XtQ”,
“title”: “劇場版『名探偵コナン 隻眼の残像(せきがんのフラッシュバック)』特報【2025年4月18日(金)公開】”,
“description”: “ついてくるな、遊びじゃねえんだー。 劇場版『名探偵コナン』シリーズ28作目、遂に始動…!! 見えない左眼を押さえ …”,
“thumbnails”: {
“default”: {
“url”: “https://i.ytimg.com/vi/p6h57WqRRl8/default.jpg”,
“width”: 120,
“height”: 90
},
“medium”: {
“url”: “https://i.ytimg.com/vi/p6h57WqRRl8/mqdefault.jpg”,
“width”: 320,
“height”: 180
},
“high”: {
“url”: “https://i.ytimg.com/vi/p6h57WqRRl8/hqdefault.jpg”,
“width”: 480,
“height”: 360
}
},
“channelTitle”: “東宝MOVIEチャンネル”,
“liveBroadcastContent”: “none”,
“publishTime”: “2024-12-04T15:00:58Z”
}
検索結果の基本情報。
以下のプロパティを含むオブジェクト。
・publishedAt
・channelId
・title
・description
・thumbnails
・channelTitle
・liveBroadcastContent
・publishTime
snippet.publishedAtRFC 3339形式の日時(datetime)

例:2024-12-31T15:00:00Z
(日本時間の2025-01-01 00:00:00)
公開日時。
snippet.channelId文字列(string)

例:”UCTDMT3aL30noTVFgNPA9XtQ”
チャンネルID。
snippet.title文字列(string)

例:”劇場版『名探偵コナン 隻眼の残像(せきがんのフラッシュバック)』特報【2025年4月18日(金)公開】”
タイトル。
snippet.description文字列(string)

例:”ついてくるな、遊びじゃねえんだー。 劇場版『名探偵コナン』シリーズ28作目、遂に始動…!! 見えない左眼を押さえ …”
説明。
snippet.thumbnailsオブジェクト(object)

例:
{
“default”: {
“url”: “https://i.ytimg.com/vi/p6h57WqRRl8/default.jpg”,
“width”: 120,
“height”: 90
},
“medium”: {
“url”: “https://i.ytimg.com/vi/p6h57WqRRl8/mqdefault.jpg”,
“width”: 320,
“height”: 180
},
“high”: {
“url”: “https://i.ytimg.com/vi/p6h57WqRRl8/hqdefault.jpg”,
“width”: 480,
“height”: 360
}
}
サムネイル情報。
以下のプロパティを含むオブジェクト。
・default
・medium
・high
・standard
・maxres

※default・medium・highは必ず含まれるが、standard・maxresは高解像度サムネイルがアップロードされている場合のみ含まれる。

snippet.thumbnails.defaultオブジェクト(object)

例:
{
“url”: “https://i.ytimg.com/vi/p6h57WqRRl8/default.jpg”,
“width”: 120,
“height”: 90
}
既定のサムネイル情報。
snippet.thumbnails.default.url文字列(string)

例:”https://i.ytimg.com/vi/p6h57WqRRl8/default.jpg”
既定のサムネイルのURL。
snippet.thumbnails.default.width符号なし整数値(unsigned integer)

例:120
例:88
既定のサムネイルの横幅。

※動画とチャンネルでサイズが異なる。動画は120px、チャンネルは88px。
snippet.thumbnails.default.height符号なし整数値(unsigned integer)

例:90
例:88
既定のサムネイルの高さ。

※動画とチャンネルでサイズが異なる。動画は90px、チャンネルは88px。
snippet.thumbnails.medium.url文字列(string)

例:”https://i.ytimg.com/vi/4Uh02uy3Tlk/mqdefault.jpg”
中画質のサムネイルのURL。
snippet.thumbnails.medium.width符号なし整数値(unsigned integer)

例:320
例:240
中画質のサムネイルの横幅。

※動画とチャンネルでサイズが異なる。動画は320px、チャンネルは240px。
snippet.thumbnails.medium.height符号なし整数値(unsigned integer)
例:180
例:240
中画質のサムネイルの高さ。

※動画とチャンネルでサイズが異なる。動画は90px、チャンネルは88px。
snippet.thumbnails.high.url文字列(string)

例:”https://i.ytimg.com/vi/4Uh02uy3Tlk/hqdefault.jpg”
高画質のサムネイルのURL。
snippet.thumbnails.high.width符号なし整数値(unsigned integer)

例:480
例:800
高画質のサムネイルの横幅。

※動画とチャンネルでサイズが異なる。動画は480px、チャンネルは800px。
snippet.thumbnails.high.height符号なし整数値(unsigned integer)

例:360
例:800
高画質のサムネイルの横幅。

※動画とチャンネルでサイズが異なる。動画は360px、チャンネルは800px。
snippet.thumbnails.standard.url文字列(string)

例:”https://i.ytimg.com/vi/Ks-_Mh1QhMc/sddefault.jpg”
標準画質のサムネイルのURL。

※高解像度サムネイルがアップロードされている場合のみ含まれる。
※動画のみ。
snippet.thumbnails.standard.width符号なし整数値(unsigned integer)

例:640
標準画質のサムネイルの横幅。

※高解像度サムネイルがアップロードされている場合のみ含まれる。
※動画のみ。640px。
snippet.thumbnails.standard.height符号なし整数値(unsigned integer)

例:480
標準画質のサムネイルの横幅。

※高解像度サムネイルがアップロードされている場合のみ含まれる。
※動画のみ。480px。
snippet.thumbnails.maxres.url文字列(string)

例:”https://i.ytimg.com/vi/Ks-_Mh1QhMc/maxresdefault.jpg”
最高画質のサムネイルのURL。

※高解像度サムネイルがアップロードされている場合のみ含まれる。
※動画のみ。
snippet.thumbnails.maxres.width符号なし整数値(unsigned integer)

例:1280
最高画質のサムネイルの横幅。

※高解像度サムネイルがアップロードされている場合のみ含まれる。
※動画のみ。1,280px。
snippet.thumbnails.maxres.height符号なし整数値(unsigned integer)

例:720
最高画質のサムネイルの横幅。

※高解像度サムネイルがアップロードされている場合のみ含まれる。
※動画のみ。720px。
snippet.channelTitle文字列(string)

例:”東宝MOVIEチャンネル”
チャンネルのタイトル。
snippet.liveBroadcastContent文字列(string)

以下のいずれかの値が含まれる。
・upcoming
(動画の場合はライブ配信予定の動画、チャンネルの場合はライブ配信予定の動画があること)
・live
(動画の場合はライブ配信中の動画、チャンネルの場合はライブ配信中の動画があること)
・none
(ライブ配信との関連性なし)
ライブ配信コンテンツとの関連性を示す。

publishTimeRFC 3339形式の日時(datetime)

例:2024-12-31T15:00:00Z
(日本時間の2025-01-01 00:00:00)
公開時間(?)。
publishedAtプロパティと同値(?)。

※APIを使うと含まれていることが確認できるが、公式リファレンスに明記なし。
※将来的にどうなるか不明なため、使わない方が良いと思います。

無料かつコードなしでAPIを試す

Googleは、APIを無料かつコードなしで試せるように公式ツールを用意してくれています。

その名も「API Explorer」。

YouTube Data APIに限らず、Googleが提供している各種APIを無料かつコードなしで試すことができます。

無制限にAPIを実行できるわけではないですが、お試しやテストに最適のツールなので、ぜひ利用していきましょう。

このブログでも使い方の記事を書いているので、見て試してみてください。

おすすめの関連記事

参考

タイトルとURLをコピーしました