techhorizonlabs/creator-audience

クリエイターの視聴者属性

YouTubeは視聴者属性を公開していません。youtube-channel-profile が使用するData APIにもありません。信頼できる情報源は2つだけです：チャンネル所有者自身のアナリティクス（同意を得て共有されたもの）か、人間が承認した有料の第三者推定値です。それ以外は推測に過ぎません。その旨を明言してください。

同意ルール

1. 所有者のデータは所有者から提供されます。所有者は、何を、どの期間について、誰に共有するかを選択します。アクセスを依頼する前に、書面（メールまたはメッセージ）で合意を得てください。
2. 所有者は自身のアカウントでサインインします。パスワードやサインインコードを要求したり、代わりに入力したりしないでください。
3. 有料の利用には「はい」の確認が必要です。人間に事前に費用を伝え、承認を得てから有料のルックアップを実行してください。
4. 名前、顔、声、コメント、サムネイルから年齢、性別、地域を推測しないでください。
5. データはジョブの目的にのみ使用し、所有者と所有者が承認した人だけに表示してください（YouTubeポリシー III.E.3.b）。リクエストから7日以内に削除してください（III.E.4.g）。保持する場合は、30日ごとに所有者の同意を再確認してください（III.E.4.b）。

ルート1：所有者がYouTube Studioから共有する（ここから始める）

API作業は不要です。単発の概要に適しています。

オプションA（エクスポート）：所有者にYouTube Studioを開き、「アナリティクス」→「視聴者」タブに移動してもらいます。日付範囲（過去90日が良いデフォルトです）を選択し、年齢、性別、上位国のスクリーンショットまたはエクスポートを共有してもらいます。

オプションB（読み取り専用アクセス）：所有者がYouTube Studioを開き、「設定」→「権限」→「招待」に進みます。人間のGoogleアカウントのメールアドレスを入力し、役割として「閲覧者（制限付き）」を選択します。この役割はアナリティクスを表示できますが、収益は表示できません。招待は30日で期限切れになります。ジョブ終了後、所有者は同じ画面からアクセスを削除します。ブランドアカウントチャンネルの場合は、事前にチャンネル権限に移動する必要があります。

ルート2：YouTube Analytics API（反復タスクまたは大規模ジョブ向け）

これは、所有者またはそのチームが実行する場合、または書面による同意を得た継続的なエンゲージメントに使用します。

1. Google Cloudでプロジェクトを作成します。YouTube Analytics APIとYouTube Data API v3を有効にします。
2. OAuth同意画面を設定します：ユーザータイプは「外部」、公開ステータスは「テスト」。所有者のGoogleアカウントをテストユーザーとして追加します。
3. OAuthクライアントID（種類：デスクトップアプリケーション）を作成し、クライアントファイルをダウンロードします。これは機密情報として扱ってください。
4. 以下のスコープのみをリクエストします：
   • https://www.googleapis.com/auth/yt-analytics.readonly
   • https://www.googleapis.com/auth/youtube.readonly（reports.queryリファレンスでも現在必要とされています）
   • yt-analytics-monetary.readonlyは、所有者が収益共有に同意した場合のみ追加します。
5. 所有者自身がサインインするマシンでサインインを実行します。例：

# pip install google-auth-oauthlib requests
from google_auth_oauthlib.flow import InstalledAppFlow
import requests
SCOPES = ["https://www.googleapis.com/auth/yt-analytics.readonly",
          "https://www.googleapis.com/auth/youtube.readonly"]
creds = InstalledAppFlow.from_client_secrets_file("client_secret.json", SCOPES).run_local_server(port=0)
base = "https://youtubeanalytics.googleapis.com/v2/reports"
common = {"ids": "channel==MINE", "startDate": "2026-08-01", "endDate": "2026-10-31"}
auth = {"Authorization": f"Bearer {creds.token}"}
age_gender = requests.get(base, headers=auth, params={**common,
    "metrics": "viewerPercentage", "dimensions": "ageGroup,gender"}).json()
countries = requests.get(base, headers=auth, params={**common,
    "metrics": "views,estimatedMinutesWatched", "dimensions": "country",
    "sort": "-views", "maxResults": 10}).json()

6. Googleが選択を求めた場合、所有者が適切なチャンネルを選択します。channel==MINE は所有者がサインインしたチャンネルを意味します。
7. columnHeaders と rows を読み取ります。viewerPercentage はサインインしている視聴者のみをカバーします。データがない場合、YouTubeは rows を省略します。その場合は「利用不可」と報告し、決してゼロとして報告しないでください。
8. トークンはメモリ内にのみ保持します。使用後は破棄します。所有者は myaccount.google.com/permissions でトークンを取り消すことができます。テストアプリのリフレッシュトークンも7日後に期限切れになります。

ルート3：有料推定（Influencers Club MCP）

Influencers Club は公開YouTubeチャンネルの視聴者属性を推定します。これは第三者のモデルであり、YouTubeデータではありません。各ルックアップでクレジットを消費します。

1. check_credits（無料）を実行し、残高を確認します。
2. 人間にツール名と費用を伝え、「はい」の回答を待ちます。2026年11月5日時点のサーバーREADMEによる費用：enrich_by_handle_analytics は0.8クレジットで視聴者属性を返します。enrich_by_handle は1クレジットです。古いサーバーでは、視聴者セクションを得るために include_audience_data をtrueに設定します。enrich_by_handle_raw は0.03クレジットで、視聴者データはありません。バージョンによって異なるため、まずツール自体の説明を読んでください。
3. 1チャンネルにつき1回の呼び出しを行い、platform を youtube に、handle をハンドルまたはチャンネルIDに設定します。
4. 呼び出しが制限またはクレジットエラーを返した場合は、そこで停止します。再試行せず、実行されたルックアップ数を報告してください。
5. この目的で get_audience_locations や get_audience_interests は使用しないでください。これらはフィルター値の無料リストであり、クリエイターの視聴者データではありません。

結果には「Influencers Club による推定」とラベルを付け、ルックアップ日を記載し、所有者の数値と混在させる場合はどれがどちらかを明示してください。

概要に記載する内容

• 各数値の出典：所有者のYouTube Analyticsとその日付範囲、所有者のStudioエクスポート、または第三者推定値。
• サインイン視聴者の年齢・性別シェア、および再生回数上位の国。
• 同意がなく、承認された支出もない場合は、「視聴者属性：所有者のアナリティクスまたは有料推定なしでは利用できません」と記載します。これで完全な回答です。

2026年11月5日、YouTube Analytics APIリファレンス、メトリクスおよび認証ページ、YouTubeヘルプのチャンネル権限、Influencers Club MCPのREADMEおよび利用制限に基づいて確認済み。