Reports: Query

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

Mit dieser Methode können Sie viele verschiedene Analytics-Berichte abrufen. Bei jeder Anfrage werden Suchparameter 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 Sortierungsanweisungen angeben.

  • Messwerte sind individuelle Messungen der Nutzeraktivität, beispielsweise Videoaufrufe oder Bewertungen (positive und negative Bewertungen).
  • Dimensionen sind gängige Kriterien, die zum Aggregieren von Daten verwendet werden, z. B. das Datum, an dem die Nutzeraktivität stattgefunden hat, oder das Land, in dem die Nutzer ansässig waren. In einem Bericht hat jede Datenzeile eine eindeutige Kombination aus Dimensionswerten.
  • Filter sind Dimensionswerte, die angeben, welche Daten abgerufen werden. Sie können beispielsweise Daten für ein bestimmtes Land, ein bestimmtes Video oder eine Gruppe von Videos abrufen.

Hinweis: Rechteinhaberberichte 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 Sie Autorisierungstokens mit dem OAuth 2.0-Protokoll abrufen.

YouTube Analytics API-Anfragen verwenden die folgenden Autorisierungsbereiche:

Sucher
https://www.googleapis.com/auth/yt-analytics.readonly Sieh dir YouTube Analytics-Berichte für deine YouTube-Inhalte an. Dieser Bereich bietet Zugriff auf Messwerte zur Nutzeraktivität, wie Anzahl der Aufrufe und Anzahl der Bewertungen.
https://www.googleapis.com/auth/yt-analytics-monetary.readonly Sieh dir die YouTube Analytics-Finanzberichte für deine YouTube-Inhalte an. Dieser Bereich bietet Zugriff auf Messwerte zur Nutzeraktivität sowie auf geschätzte Umsatz- und Anzeigenleistungsmesswerte.
https://www.googleapis.com/auth/youtube YouTube-Konto verwalten In der YouTube Analytics API können Kanalinhaber mit diesem Bereich YouTube-Gruppen und ‐Gruppen verwalten.
https://www.googleapis.com/auth/youtubepartner YouTube-Assets und zugehörige Inhalte auf YouTube ansehen und verwalten In der YouTube Analytics API können Rechteinhaber diesen Bereich verwenden, um YouTube Analytics-Gruppen und -Gruppenelemente zu verwalten.

Parameter

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

Parameter
Erforderliche Parameter
endDate string
Das Enddatum zum 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 die alle Messwerte in der Abfrage zum Zeitpunkt der Abfrage verfügbar sind. Wenn die Anfrage beispielsweise ein Enddatum vom 5. Juli 2017 enthält und die Werte für alle angeforderten Messwerte nur bis zum 3. Juli 2017 verfügbar sind, ist dies das letzte Datum, für das Daten in die Antwort aufgenommen werden. 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 hieß dieser Parameter end-date.
ids string
Kennzeichnet den YouTube-Kanal oder den Rechteinhaber, für den Sie YouTube Analytics-Daten abrufen.

  • Um Daten für einen YouTube-Kanal anzufordern, setze den Parameterwert ids 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 Parameterwert ids auf contentOwner==OWNER_NAME. Dabei ist OWNER_NAME der content owner ID für den Nutzer.

metrics string
Eine durch Kommas getrennte Liste von YouTube Analytics-Messwerten, z. B. views oder likes,dislikes. In der Dokumentation für Kanalberichte oder Rechteinhaberberichte findest du eine Liste der Berichte, die du abrufen kannst, sowie die in den einzelnen Berichten verfügbaren Messwerte. Das Dokument Messwerte enthält Definitionen für alle Messwerte.
startDate string
Das Startdatum zum Abrufen von YouTube Analytics-Daten Der Wert muss das Format YYYY-MM-DD haben.
Hinweis:In Version 1 der API hieß dieser Parameter start-date.
Optionale Parameter
currency string
Die Währung, die die API verwendet, um die folgenden geschätzten Umsatzmesswerte anzugeben: estimatedRevenue, estimatedAdRevenue, estimatedRedPartnerRevenue, GrossRevenue, cpm und playbackBasedCpm. Die Werte, die die API für diese Messwerte zurückgibt, sind Schätzungen, die sich anhand von Wechselkursen ergeben, die sich täglich ändern. Wenn keiner dieser Messwerte angefordert wird, wird der Parameter ignoriert.

Der Parameterwert ist ein dreistelliger ISO 4217-Währungscode 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 der YouTube Analytics-Dimensionen wie video oder ageGroup,gender. In der Dokumentation zu Kanalberichten und Rechteinhaberberichten finden Sie eine Liste der Berichte, die Sie abrufen können, sowie die Dimensionen, die für diese Berichte verwendet werden. 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 Channelberichten und Berichten zu Rechteinhabern sind die Dimensionen aufgeführt, die zum Filtern der einzelnen Berichte verwendet werden können. Diese Dimensionen werden im Dokument Dimensionen definiert.

Wenn in einer Anfrage mehrere Filter verwendet werden, müssen Sie diese mit einem Semikolon (;) verknüpfen. Die zurückgegebene Ergebnistabelle erfüllt dann beide Filter. Beispielsweise wird durch den Parameterwert filters von video==dMH0bHeiRNg;country==IT die Ergebnismenge auf Daten für das entsprechende Video in Italien beschränkt.

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, nach denen die API-Antwort gefiltert werden soll. Beispielsweise wird durch den Parameterwert filters von video==pd1FJh59zxQ,Zhawgd0REhA;country==IT die Ergebnismenge auf Daten für bestimmte Videos in Italien beschränkt. Im Parameterwert können bis zu 500 IDs angegeben werden.

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

Angenommen, du ruft den Bericht zu Zugriffsquellen für einen Kanal ab. In diesem Bericht werden Aufrufstatistiken basierend auf der Methode zusammengefasst, wie Zuschauer zu den Videoinhalten des Kanals gelangt sind. Außerdem wird mit der Anfrage filters des Parameters eine Liste von 10 Videos ermittelt, für die Daten zurückgegeben werden sollen.
  • Wenn du video zum Wert des Parameters dimensions hinzufügst, liefert die API-Antwort separate Statistiken zu den Zugriffsquellen für jedes der zehn Videos.
  • Wenn du video nicht zum Wert des dimensions-Parameters hinzufügst, werden in der API-Antwort die Zugriffsquellenstatistiken für alle zehn Videos zusammengefasst.
includeHistoricalChannelData boolean
Hinweis:Dieser Parameter gilt nur für Rechteinhaberberichte.

Gibt an, ob die API-Antwort die Wiedergabezeit von Kanälen und die Daten vor dem Zeitpunkt der Verknüpfung mit dem Rechteinhaber berücksichtigen soll. Der Standardparameterwert lautet false. Die API-Antwort enthält also nur Wiedergabezeit und Aufrufe ab dem Datum, an dem Kanäle mit dem Rechteinhaber verknüpft wurden.

Denke daran, dass verschiedene Kanäle möglicherweise an verschiedenen Tagen mit einem Rechteinhaber verknüpft wurden. Wenn die API-Anfrage Daten für mehrere Kanäle abruft und der Parameterwert false lautet, enthält die API-Antwort Daten basierend auf dem Verknüpfungsdatum für jeden Kanal. Wenn der Parameterwert true lautet, enthält die API-Antwort Daten, die mit den in der API-Anfrage angegebenen Daten übereinstimmen.
Hinweis:In Version 1 der API hieß dieser Parameter include-historical-channel-data.
maxResults integer
Die maximale Anzahl der Zeilen, die in die Antwort aufgenommen werden sollen.
Hinweis:In Version 1 der API hieß dieser Parameter max-results.
sort string
Eine durch Kommas getrennte Liste von Dimensionen oder Messwerten, die die Sortierreihenfolge für YouTube Analytics-Daten bestimmen. standardmäßig ist die Sortierfolge aufsteigend Das Präfix - bewirkt eine absteigende Sortierreihenfolge.
startIndex integer
Der 1-basierte Index der ersten abzurufenden Entität. Der Standardwert ist 1. Verwenden Sie diesen Parameter zusammen mit dem Parameter max-results als Paginierungsmechanismus.
Hinweis: In Version 1 der API hieß dieser Parameter start-index.
Standardparameter
access_token OAuth 2.0-Token für den aktuellen Nutzer.
alt Dieser Parameter wird in Version 2 der API nicht unterstützt. In ihr werden nur JSON-Antworten 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 JSON-P-JavaScript-Anfragen verwendet.
prettyPrint

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

  • Gibt die Antwort in einem für Menschen lesbaren Format zurück, wenn true.
  • Standardwert: true.
  • Bei false kann die Nutzlast der Antwort reduziert werden, was in einigen Umgebungen zu einer besseren Leistung führt.
quotaUser Dieser Parameter wurde in Version 1 der API unterstützt, die inzwischen 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 inzwischen eingestellt ist. Dieser Parameter wird in Version 2 der API nicht unterstützt.

Anfragetext

Beim Aufrufen dieser Methode darf kein Anfragetext gesendet werden.

Antwort

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

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

Die Liste columnHeaders beginnt mit den in der API-Anfrage angegebenen Dimensionen, gefolgt von den in der API-Anfrage angegebenen Messwerten. Die Reihenfolge der Dimensionen und Messwerte 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, das durch Kommas getrennte Daten enthält, die einer einzelnen Datenzeile entsprechen. Die Reihenfolge der durch Kommas getrennten Datenfelder entspricht der Reihenfolge der Spalten im Feld columnHeaders.

Wenn für die 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 stehen möglicherweise nicht für alle unterstützten Programmiersprachen zur Verfügung. Eine Liste der unterstützten Sprachen finden Sie in der Dokumentation zu Clientbibliotheken.

JavaScript

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

Bevor Sie dieses Beispiel zum ersten Mal lokal ausführen, müssen Sie Anmeldedaten für Ihr Projekt einrichten:
  1. Erstellen oder wählen Sie ein Projekt in der Google API Console aus.
  2. Aktivieren Sie die YouTube Analytics API für Ihr 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 geschehen, und klicken Sie auf die Schaltfläche „Speichern“.
  4. Klicken Sie auf der Seite Anmeldedaten auf 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, über die Sie das Codebeispiel bereitstellen möchten. Beispiel: http://localhost:8000 oder http://yourserver.example.com. Sie können das Feld für die autorisierten Weiterleitungs-URIs leer lassen.
  7. Klicken Sie auf Erstellen, um die Erstellung Ihrer Anmeldedaten abzuschließen.
  8. Kopieren Sie vor dem Schließen des Dialogfelds die Client-ID, die Sie in das Codebeispiel einfügen müssen.

Speichern Sie das Beispiel dann in einer lokalen Datei. Suchen Sie im Beispiel nach der folgenden Zeile und ersetzen Sie YOUR_CLIENT_ID durch die Client-ID, die Sie beim Einrichten Ihrer Anmeldedaten für die Autorisierung erhalten haben.

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

Jetzt können Sie das Beispiel 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 den Nutzerautorisierungsvorgang zu starten. Wenn du der App das Abrufen deiner Kanaldaten erlaubst, sollten die folgenden Zeilen in der Konsole im Browser angezeigt werden:
    Sign-in successful
    GAPI client loaded for API
  3. Wenn Sie anstelle der oben genannten Zeilen eine Fehlermeldung sehen, prüfen Sie, ob Sie das Skript aus dem autorisierten Weiterleitungs-URI geladen haben, den Sie für Ihr Projekt eingerichtet haben. Fügen Sie dann Ihre Client-ID wie oben beschrieben in den Code ein.
  4. Klicken Sie auf die Schaltfläche Ausführen, um die API aufzurufen. Es sollte ein response-Objekt auf der Konsole im Browser angezeigt werden. In diesem Objekt wird die Property 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>

Python

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

Bevor Sie dieses Beispiel zum ersten Mal lokal ausführen, müssen Sie Anmeldedaten für Ihr Projekt einrichten:
  1. Erstellen oder wählen Sie ein Projekt in der Google API Console aus.
  2. Aktivieren Sie die YouTube Analytics API für Ihr 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 geschehen, und klicken Sie auf die Schaltfläche „Speichern“.
  4. Klicken Sie auf der Seite Anmeldedaten auf Anmeldedaten erstellen und wählen Sie OAuth-Client-ID aus.
  5. Wähle den Anwendungstyp Sonstiges aus, gib den Namen „YouTube Analytics API Quickstart“ ein und klicke auf die Schaltfläche „Erstellen“.
  6. Klicken Sie auf OK, um das 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.

Außerdem müssen Sie 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 testen:

  1. Kopieren Sie das Codebeispiel unten in Ihr Arbeitsverzeichnis.
  2. Aktualisieren Sie im Beispiel den Wert der Variablen CLIENT_SECRETS_FILE entsprechend dem Speicherort der Datei, die Sie nach dem Einrichten der Anmeldedaten für die Autorisierung heruntergeladen haben.
  3. Führen Sie den Beispielcode in einem Terminalfenster aus:
    python yt_analytics_v2.py
  4. Folgen Sie der Anleitung zur Autorisierung. Der Authentifizierungsvorgang wird möglicherweise automatisch in Ihrem Browser geladen oder Sie müssen die Authentifizierungs-URL in ein Browserfenster kopieren. Fügen Sie gegebenenfalls am Ende des Autorisierungsvorgangs den im Browser angezeigten Autorisierungscode in Ihr Terminalfenster ein und klicken Sie auf „Zurück“.
  5. Die API-Abfrage wird ausgeführt und die JSON-Antwort wird an das 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'
  )

Testen!

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