Reports: Query

Wichtig: API-Anfragen an diese Methode benötigen jetzt Zugriff auf den Bereich https://www.googleapis.com/auth/youtube.readonly.

Mit dieser Methode lassen sich viele verschiedene Analytics-Berichte abrufen. In jeder Anfrage werden Abfrageparameter verwendet, um eine Kanal-ID oder einen Rechteinhaber, ein Startdatum, ein Enddatum und mindestens einen Messwert anzugeben. Sie können auch zusätzliche Suchparameter wie Dimensionen, Filter und Sortieranweisungen angeben.

  • Messwerte sind individuelle Messungen der Nutzeraktivität, wie z. B. Videoaufrufe oder Bewertungen („Mag ich“- und „Mag ich nicht“-Bewertungen).
  • Dimensionen sind gängige Kriterien, mit denen Daten zusammengefasst werden, z. B. das Datum, an dem die Nutzeraktivität stattgefunden hat, oder das Land, in dem sich die Nutzer befanden. In einem Bericht hat jede Datenzeile eine eindeutige Kombination von Dimensionswerten.
  • Filter sind Dimensionswerte, die die abzurufenden Daten angeben. So lassen sich beispielsweise Daten für ein bestimmtes Land, ein bestimmtes Video oder eine Gruppe von Videos abrufen.

Hinweis: Berichte zu Rechteinhabern sind nur für YouTube-Contentpartner verfügbar, die am YouTube-Partnerprogramm teilnehmen.

Gängige Anwendungsfälle

Anfragen

HTTP-Anfrage

GET https://youtubeanalytics.googleapis.com/v2/reports

Alle Anfragen an die YouTube Analytics API müssen autorisiert werden. Im Autorisierungsleitfaden wird erläutert, wie mithilfe des OAuth 2.0-Protokolls Autorisierungstokens abgerufen werden.

YouTube Analytics API-Anfragen verwenden die folgenden Autorisierungsbereiche:

Ebenen
https://www.googleapis.com/auth/yt-analytics.readonly Sieh dir YouTube Analytics-Berichte für deine YouTube-Inhalte an. Über diesen Bereich erhalten Sie Zugriff auf Messwerte zur Nutzeraktivität, z. B. die Anzahl der Aufrufe und Bewertungen.
https://www.googleapis.com/auth/yt-analytics-monetary.readonly YouTube Analytics-Finanzberichte für deine YouTube-Inhalte abrufen. So erhalten Sie Zugriff auf Messwerte zur Nutzeraktivität sowie auf Messwerte zum geschätzten Umsatz und zur Anzeigenleistung.
https://www.googleapis.com/auth/youtube Verwalte dein YouTube-Konto. In der YouTube Analytics API verwenden Kanalinhaber diesen Bereich, um Gruppen und Gruppenelemente in YouTube Analytics zu verwalten.
https://www.googleapis.com/auth/youtubepartner YouTube-Assets und zugehörige Inhalte auf YouTube abrufen und verwalten. In der YouTube Analytics API können Rechteinhaber diesen Bereich nutzen, um Gruppen und Gruppenelemente in YouTube Analytics zu verwalten.

Parameter

In den folgenden Tabellen sind die erforderlichen und optionalen Abfrageparameter für API-Anfragen zum Abrufen von Anfrageberichten aufgeführt. Die in der Tabelle aufgeführten Standardsuchparameter sind ebenfalls optional und werden von vielen Google APIs unterstützt.

Parameter
Erforderliche Parameter
endDate string
Das Enddatum für das Abrufen von YouTube Analytics-Daten. Der Wert muss das Format YYYY-MM-DD haben.

Die API-Antwort enthält Daten bis zum letzten Tag, für den zum Zeitpunkt der Abfrage alle Messwerte in der Abfrage verfügbar sind. Wenn in der Anfrage beispielsweise der 5. Juli 2017 als Enddatum angegeben ist und die Werte für alle angeforderten Messwerte nur bis zum 3. Juli 2017 verfügbar sind, werden in der Antwort keine Daten mehr berücksichtigt. Das gilt auch dann, wenn Daten für einige der angeforderten Messwerte für den 4. Juli 2017 verfügbar sind.
Hinweis: In Version 1 der API wurde dieser Parameter end-date genannt.
ids string
Identifiziert den YouTube-Kanal oder Rechteinhaber, für den du YouTube Analytics-Daten abrufst.

  • Wenn du Daten für einen YouTube-Kanal anfordern möchtest, setze den ids-Parameterwert entweder auf channel==MINE oder channel==CHANNEL_ID, wobei CHANNEL_ID den YouTube-Kanal des aktuell authentifizierten Nutzers identifiziert.
  • Wenn du Daten für einen YouTube-Rechteinhaber anfordern möchtest, setze den ids-Parameterwert auf contentOwner==OWNER_NAME, wobei OWNER_NAME der content owner ID für den Nutzer ist.

metrics string
Eine durch Kommas getrennte Liste von YouTube Analytics-Messwerten, z. B. views oder likes,dislikes. In der Dokumentation zu Kanalberichten und Berichten zu Rechteinhabern findest du eine Liste der Berichte, die du abrufen kannst, und der Messwerte, die in den einzelnen Berichten verfügbar sind. Das Dokument Messwerte enthält Definitionen für alle Messwerte.
startDate string
Das Startdatum für das Abrufen von YouTube Analytics-Daten Der Wert muss das Format YYYY-MM-DD haben.
Hinweis: In Version 1 der API wurde dieser Parameter start-date genannt.
Optionale Parameter
currency string
Die Währung, in der die API die folgenden geschätzten Umsatzmesswerte angibt: estimatedRevenue, estimatedAdRevenue, estimatedRedPartnerRevenue, grossRevenue, cpm, playbackBasedCpm Die vom API zurückgegebenen Werte für diese Messwerte sind Schätzungen, die auf Grundlage von Wechselkursen berechnet werden, die sich täglich ändern. Wird keiner dieser Messwerte angefordert, wird der Parameter ignoriert.

Der Parameterwert ist ein dreistelliger Währungscode gemäß ISO 4217 aus der Liste der Währungen unten. Die API gibt einen Fehler zurück, wenn eine nicht unterstützte Währung angegeben ist. Der Standardwert ist USD.
dimensions string
Eine durch Kommas getrennte Liste von YouTube Analytics-Dimensionen, z. B. video oder ageGroup,gender. In der Dokumentation zu Kanalberichten und Berichten zu Rechteinhabern findest du eine Liste der Berichte, die du abrufen kannst, und der dafür verwendeten Dimensionen. Das Dokument Dimensionen enthält Definitionen für alle Dimensionen.
filters string
Eine Liste von Filtern, die beim Abrufen von YouTube Analytics-Daten angewendet werden sollen. In der Dokumentation zu Kanalberichten und Berichten zu Rechteinhabern sind die Dimensionen aufgeführt, die zum Filtern der einzelnen Berichte verwendet werden können. Im Dokument Dimensionen sind diese Dimensionen definiert.

Wenn in einer Anfrage mehrere Filter verwendet werden, führen Sie diese mit einem Semikolon (;) zusammen. Die zurückgegebene Ergebnistabelle erfüllt dann beide Filter. Beispiel: Wenn der filters-Parameterwert video==dMH0bHeiRNg;country==IT lautet, werden nur Daten für das jeweilige Video in Italien berücksichtigt.

Mehrere Werte für einen Filter angeben

Die API unterstützt die Möglichkeit, mehrere Werte für die Filter video, playlist und channel anzugeben. Geben Sie dazu eine separate Liste der Video-, Playlist- oder Kanal-IDs an, für die die API-Antwort gefiltert werden soll. Wenn der Parameterwert filters beispielsweise video==pd1FJh59zxQ,Zhawgd0REhA;country==IT lautet, werden nur Daten für die angegebenen Videos in Italien berücksichtigt. Für den Parameterwert können bis zu 500 IDs angegeben werden.

Wenn Sie mehrere Werte für denselben Filter angeben, können Sie ihn der Liste der Dimensionen hinzufügen, die Sie für die Anfrage angeben. Das gilt auch dann, wenn der Filter für einen bestimmten Bericht nicht als unterstützte Dimension aufgeführt ist. Wenn Sie den Filter zur Liste der Dimensionen hinzufügen, verwendet die API die Filterwerte auch zum Gruppieren der Ergebnisse.

Angenommen, du rufst den Bericht zu Zugriffsquellen eines Kanals ab, in dem Statistiken zu Aufrufen zusammengefasst werden, die darauf basieren, wie Zuschauer auf die Videoinhalte des Kanals zugegriffen haben. Angenommen, die Parameteranfrage filters Ihrer Anfrage enthält eine Liste mit zehn Videos, für die Daten zurückgegeben werden sollen.
  • Wenn du video zum Wert des dimensions-Parameters hinzufügst, liefert die API-Antwort für jedes der zehn Videos separate Statistiken zu Zugriffsquellen.
  • Wenn du video nicht zum Wert des dimensions-Parameters hinzufügst, werden in der API-Antwort die Statistiken zu Zugriffsquellen für alle zehn Videos zusammengefasst.
includeHistoricalChannelData boolean
Hinweis:Dieser Parameter gilt nur für Berichte zu Rechteinhabern.

Gibt an, ob die API-Antwort die Wiedergabezeit- und Aufrufdaten der Kanäle aus dem Zeitraum vor der Verknüpfung der Kanäle mit dem Rechteinhaber enthalten soll. Der Standardparameterwert lautet false. Das bedeutet, dass die API-Antwort nur Daten zu Wiedergabezeit und Aufrufen für die Zeiträume enthält, an denen Kanäle mit dem Rechteinhaber verknüpft wurden.

Es kann sein, dass verschiedene Kanäle zu unterschiedlichen Zeiten mit einem Rechteinhaber verknüpft wurden. Wenn mit der API-Anfrage Daten für mehrere Kanäle abgerufen werden und der Parameterwert false lautet, enthält die API-Antwort Daten, die auf dem Verknüpfungsdatum für den jeweiligen Kanal basieren. Wenn der Parameterwert true lautet, enthält die API-Antwort Daten, die mit den in der API-Anfrage angegebenen Datumsangaben übereinstimmen.
Hinweis: In Version 1 der API wurde dieser Parameter include-historical-channel-data genannt.
maxResults integer
Die maximale Anzahl von Zeilen, die in die Antwort aufgenommen werden sollen.
Hinweis: In Version 1 der API wurde dieser Parameter max-results genannt.
sort string
Eine durch Kommas getrennte Liste von Dimensionen oder Messwerten, mit denen die Sortierreihenfolge der YouTube Analytics-Daten festgelegt wird. standardmäßig ist die Sortierfolge aufsteigend Das Präfix - sorgt für eine absteigende Sortierreihenfolge.
startIndex integer
Der 1-basierte Index der ersten abzurufenden Entität. Der Standardwert ist 1. Verwenden Sie diesen Parameter als Paginierungsmechanismus zusammen mit dem Parameter max-results.
Hinweis: In Version 1 der API wurde dieser Parameter start-index genannt.
Standardparameter
access_token OAuth 2.0-Token für den aktuellen Nutzer.
alt Dieser Parameter wird in Version 2 der API, die nur JSON-Antworten unterstützt, nicht unterstützt. Das Datenformat für die API-Antwort.
  • Gültige Werte: json, csv
  • Standardwert: json
callback Callback-Funktion
  • Name der JavaScript Callback-Funktion für die Antwortbehandlung.
  • Wird in JavaScript-JSON-P-Anfragen verwendet.
prettyPrint

Gibt die Antwort mit Einzügen und Zeilenumbrüchen zurück.

  • Gibt die Antwort in einem visuell lesbaren Format zurück, wenn true.
  • Standardwert: true.
  • Wenn dieser Wert auf false gesetzt ist, kann die Nutzlastgröße der Antwort reduziert werden, was in einigen Umgebungen zu einer besseren Leistung führen kann.
quotaUser Dieser Parameter wurde in Version 1 der API unterstützt, die jetzt eingestellt ist. Dieser Parameter wird in Version 2 der API nicht unterstützt.
userIp Dieser Parameter wurde in Version 1 der API unterstützt, die jetzt eingestellt ist. Dieser Parameter wird in Version 2 der API nicht unterstützt.

Anfragetext

Beim Aufrufen dieser Methode wird kein Anfragetext gesendet.

Antwort

Wie in der Parameterdefinition alt angegeben, kann die API Antworten im JSON- oder CSV-Format zurückgeben. Informationen zum Antworttext für jeden Typ finden Sie unten:

JSON
{
  "kind": "youtubeAnalytics#resultTable",
  "columnHeaders": [
    {
      "name": string,
      "dataType": string,
      "columnType": string
    },
    ... more headers ...
  ],
  "rows": [
    [
      {value}, {value}, ...
    ]
  ]
}
Attribute
kind string
Dieser Wert gibt den Datentyp an, der in der API-Antwort enthalten ist. Für die Methode query ist der Attributwert kind youtubeAnalytics#resultTable. Wenn die API jedoch weitere Methoden unterstützt, können API-Antworten für diese Methoden andere kind-Attributwerte einführen.
columnHeaders[] list
Dieser Wert gibt Informationen zu den Daten an, die in den rows-Feldern zurückgegeben werden. Jedes Element in der columnHeaders-Liste identifiziert ein Feld, das im rows-Wert zurückgegeben wird, der eine Liste mit durch Kommas getrennten Daten enthält.

Die Liste columnHeaders beginnt mit den in der API-Anfrage angegebenen Dimensionen, gefolgt von den in der API-Anfrage angegebenen Messwerten. Die Reihenfolge von Dimensionen und Messwerten entspricht der Reihenfolge in der API-Anfrage.

Wenn die API-Anfrage beispielsweise die Parameter dimensions=ageGroup,gender&metrics=viewerPercentage enthält, gibt die API-Antwort Spalten in dieser Reihenfolge zurück: ageGroup, gender, viewerPercentage.
columnHeaders[].name string
Der Name der Dimension oder des Messwerts.
columnHeaders[].columnType string
Der Typ der Spalte (DIMENSION oder METRIC).
columnHeaders[].dataType string
Der Typ der Daten in der Spalte (STRING, INTEGER, FLOAT usw.).
rows[] list
Die Liste enthält alle Zeilen der Ergebnistabelle. Jedes Element in der Liste ist ein Array mit durch Kommas getrennten Daten, die einer einzelnen Datenzeile entsprechen. Die Reihenfolge der durch Kommas getrennten Datenfelder entspricht der Reihenfolge der im Feld columnHeaders aufgeführten Spalten.

Wenn für die gegebene Abfrage keine Daten verfügbar sind, wird das Element rows in der Antwort weggelassen.

Die Antwort auf eine Abfrage mit der Dimension day enthält keine Zeilen für die letzten Tage.

CSV
day, views, likes, ...
"2012-01-01", 12.0, 3, ...
"2012-01-02", 16.0, 2, ...
"2012-01-03", 18.0, 8, ...
...

Beispiele

Hinweis:Die folgenden Codebeispiele repräsentieren möglicherweise nicht alle unterstützten Programmiersprachen. Eine Liste der unterstützten Sprachen finden Sie in der Dokumentation zu Clientbibliotheken.

JavaScript

In diesem Beispiel wird die YouTube Analytics API aufgerufen, um die täglichen Aufrufe und andere Messwerte für den Kanal des autorisierenden Nutzers für das Kalenderjahr 2017 abzurufen. In diesem Beispiel wird die Google API-Clientbibliothek für JavaScript verwendet.

Bevor Sie dieses Beispiel zum ersten Mal lokal ausführen, müssen Sie Anmeldedaten für die Autorisierung für Ihr Projekt einrichten:
  1. Erstelle ein Projekt in der Google API Console oder wähle eines aus.
  2. Aktiviere die YouTube Analytics API für dein Projekt.
  3. Wählen Sie oben auf der Seite Anmeldedaten den Tab OAuth-Zustimmungsbildschirm aus. Wählen Sie eine E-Mail-Adresse aus, geben Sie einen Produktnamen ein, falls noch nicht festgelegt, und klicken Sie auf die Schaltfläche Speichern.
  4. Klicken Sie auf der Seite Anmeldedaten auf die Schaltfläche Anmeldedaten erstellen und wählen Sie OAuth-Client-ID aus.
  5. Wählen Sie den Anwendungstyp „Webanwendung“ aus.
  6. Geben Sie im Feld „Autorisierte JavaScript-Quellen“ die URL ein, von der aus Sie das Codebeispiel bereitstellen. Sie können z. B. http://localhost:8000 oder http://yourserver.example.com verwenden. Sie können das Feld „Autorisierte Weiterleitungs-URIs“ leer lassen.
  7. Klicken Sie auf Erstellen, um die Erstellung Ihrer Anmeldedaten abzuschließen.
  8. Bevor Sie das Dialogfeld schließen, kopieren Sie die Client-ID, die Sie in das Codebeispiel eingeben müssen.

Speichern Sie das Sample dann in einer lokalen Datei. Suchen Sie im Beispiel die folgende Zeile und ersetzen Sie YOUR_CLIENT_ID durch die Client-ID, die Sie beim Einrichten Ihrer Autorisierungsanmeldedaten erhalten haben.

gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'});

Jetzt können Sie das Beispiel tatsächlich testen:

  1. Öffnen Sie die lokale Datei in einem Webbrowser und dann die Debugging-Konsole im Browser. Es sollte eine Seite mit zwei Schaltflächen angezeigt werden.
  2. Klicken Sie auf die Schaltfläche Autorisieren und laden, um die Nutzerautorisierung zu starten. Wenn Sie die App zum Abrufen Ihrer Kanaldaten autorisieren, sollten die folgenden Zeilen in der Konsole im Browser ausgegeben werden: 
    Sign-in successful
GAPI client loaded for API
  3. Wenn anstelle der oben genannten Zeilen eine Fehlermeldung angezeigt wird, prüfen Sie, ob Sie das Skript über den autorisierten Weiterleitungs-URI laden, den Sie für Ihr Projekt eingerichtet haben, und ob Sie Ihre Client-ID wie oben beschrieben in den Code eingefügt haben.
  4. Klicken Sie auf die Schaltfläche execute, um die API aufzurufen. Es sollte ein response-Objekt angezeigt werden, das im Browser an die Konsole gedruckt wird. In diesem Objekt ist die Eigenschaft result einem Objekt zugeordnet, das die API-Daten enthält.
<script src="https://apis.google.com/js/api.js"></script>
<script>
  function authenticate() {
    return gapi.auth2.getAuthInstance()
        .signIn({scope: "https://www.googleapis.com/auth/yt-analytics.readonly"})
        .then(function() { console.log("Sign-in successful"); },
              function(err) { console.error("Error signing in", err); });
  }
  function loadClient() {
    return gapi.client.load("https://youtubeanalytics.googleapis.com/$discovery/rest?version=v2")
        .then(function() { console.log("GAPI client loaded for API"); },
              function(err) { console.error("Error loading GAPI client for API", err); });
  }
  // Make sure the client is loaded and sign-in is complete before calling this method.
  function execute() {
    return gapi.client.youtubeAnalytics.reports.query({
      "ids": "channel==MINE",
      "startDate": "2017-01-01",
      "endDate": "2017-12-31",
      "metrics": "views,estimatedMinutesWatched,averageViewDuration,averageViewPercentage,subscribersGained",
      "dimensions": "day",
      "sort": "day"
    })
        .then(function(response) {
                // Handle the results here (response.result has the parsed body).
                console.log("Response", response);
              },
              function(err) { console.error("Execute error", err); });
  }
  gapi.load("client:auth2", function() {
    gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'});
  });
</script>
<button onclick="authenticate().then(loadClient)">authorize and load</button>
<button onclick="execute()">execute</button>

yt_analytics_v2.html

Python

In diesem Beispiel wird die YouTube Analytics API aufgerufen, um die täglichen Aufrufe und andere Messwerte für den Kanal des autorisierenden Nutzers für das Kalenderjahr 2017 abzurufen. In diesem Beispiel wird die Google API-Clientbibliothek für Python verwendet.

Bevor Sie dieses Beispiel zum ersten Mal lokal ausführen, müssen Sie Anmeldedaten für die Autorisierung für Ihr Projekt einrichten:
  1. Erstelle ein Projekt in der Google API Console oder wähle eines aus.
  2. Aktiviere die YouTube Analytics API für dein Projekt.
  3. Wählen Sie oben auf der Seite Anmeldedaten den Tab OAuth-Zustimmungsbildschirm aus. Wählen Sie eine E-Mail-Adresse aus, geben Sie einen Produktnamen ein, falls noch nicht festgelegt, und klicken Sie auf die Schaltfläche Speichern.
  4. Klicken Sie auf der Seite Anmeldedaten auf die Schaltfläche Anmeldedaten erstellen und wählen Sie OAuth-Client-ID aus.
  5. Wähle den Anwendungstyp Andere aus, gib den Namen „YouTube Analytics API Kurzanleitung“ ein und klicke auf die Schaltfläche „Erstellen“.
  6. Klicken Sie auf OK, um das angezeigte Dialogfeld zu schließen.
  7. Klicken Sie rechts neben der Client-ID auf die Schaltfläche (JSON herunterladen).
  8. Verschieben Sie die heruntergeladene Datei in Ihr Arbeitsverzeichnis.

Sie müssen auch die Google APIs-Clientbibliothek für Python und einige zusätzliche Bibliotheken installieren:

pip install --upgrade google-api-python-client
pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2

Jetzt können Sie das Beispiel tatsächlich testen:

  1. Kopieren Sie das Codebeispiel unten in Ihr Arbeitsverzeichnis.
  2. Aktualisieren Sie im Beispiel den Wert der Variablen CLIENT_SECRETS_FILE so, dass er mit dem Speicherort der Datei übereinstimmt, die Sie nach Einrichtung Ihrer Anmeldedaten für die Autorisierung heruntergeladen haben.
  3. Führen Sie den Beispielcode in einem Terminalfenster aus: 
    python yt_analytics_v2.py
  4. Autorisierungsvorgang durchlaufen. Der Autorisierungsablauf wird möglicherweise automatisch im Browser geladen oder Sie müssen die Authentifizierungs-URL in ein Browserfenster kopieren. Fügen Sie am Ende des Autorisierungsvorgangs, falls erforderlich, den im Browser angezeigten Autorisierungscode in Ihr Terminalfenster ein und klicken Sie auf [return].
  5. Die API-Abfrage wird ausgeführt und die JSON-Antwort wird im Terminalfenster ausgegeben.
# -*- coding: utf-8 -*-

import os
import google.oauth2.credentials
import google_auth_oauthlib.flow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
from google_auth_oauthlib.flow import InstalledAppFlow

SCOPES = ['https://www.googleapis.com/auth/yt-analytics.readonly']

API_SERVICE_NAME = 'youtubeAnalytics'
API_VERSION = 'v2'
CLIENT_SECRETS_FILE = 'YOUR_CLIENT_SECRET_FILE.json'
def get_service():
  flow = InstalledAppFlow.from_client_secrets_file(CLIENT_SECRETS_FILE, SCOPES)
  credentials = flow.run_console()
  return build(API_SERVICE_NAME, API_VERSION, credentials = credentials)

def execute_api_request(client_library_function, **kwargs):
  response = client_library_function(
    **kwargs
  ).execute()

  print(response)

if __name__ == '__main__':
  # Disable OAuthlib's HTTPs verification when running locally.
  # *DO NOT* leave this option enabled when running in production.
  os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1'

  youtubeAnalytics = get_service()
  execute_api_request(
      youtubeAnalytics.reports().query,
      ids='channel==MINE',
      startDate='2017-01-01',
      endDate='2017-12-31',
      metrics='estimatedMinutesWatched,views,likes,subscribersGained'
      dimensions='day',
      sort='day'
  )

yt_analytics_v2.py

Jetzt testen

Verwenden Sie APIs Explorer, um diese API aufzurufen und die API-Anfrage und -Antwort anzusehen.