YouTube Analytics API - Data Model

Mit der YouTube Analytics API kannst du benutzerdefinierte Berichte mit YouTube Analytics-Daten erstellen. Die API unterstützt Berichte für Kanäle und Rechteinhaber. Berichtsfelder werden entweder als Dimensionen oder als Messwerte klassifiziert:

  • Dimensionen sind gängige Kriterien, die zum Aggregieren von Daten verwendet werden, z. B. das Datum, an dem eine Aktion stattgefunden hat, oder das Land, in dem sich die Nutzer befanden.

    In einem Bericht hat jede Datenzeile eine eindeutige Kombination von Dimensionswerten. Die Dimensionen, die du für einen Bericht auswählst, bestimmen also, wie YouTube die Werte für die Messwerte in diesem Bericht berechnet.

  • Messwerte sind einzelne Messungen im Zusammenhang mit Nutzeraktivitäten, Anzeigenleistung oder geschätztem Umsatz. Zu den Messwerten für Nutzeraktivitäten gehören beispielsweise die Anzahl der Videoaufrufe und Bewertungen (Likes und Dislikes).

Die Analytics API bietet Filter- und Sortierparameter, sodass die aufrufende Anwendung diese Funktionen nicht nativ unterstützen muss. Mit der API kannst du auch Daten für YouTube Analytics-Gruppen abrufen. Eine Gruppe ist eine benutzerdefinierte Sammlung von bis zu 500 Videos, Playlists, Kanälen oder Assets.

Berichtsparameter auswählen

Wenn Sie einen Bericht mit der reports.query-Methode der API anfordern, enthält die API-Anfrage fünf Parameter, die bestimmen, wie die Berichtswerte berechnet werden:

  • Mit den Parametern startDate und endDate wird der Zeitraum angegeben, für den der Bericht Daten enthalten soll. Die API-Antwort enthält tatsächlich Daten bis zum letzten angegebenen Tag, für den alle Messwerte in der Abfrage zum Zeitpunkt der Abfrage verfügbar sind.

  • Mit dem Parameter metrics werden die Messwerte angegeben, die im Bericht enthalten sein sollen. In Kanalberichten werden mit Messwerten Nutzeraktivitäten gemessen. Dazu gehören Werte wie Aufrufe und „Mag ich“-Bewertungen. Einige Messwerte messen auch die Anzeigenleistung oder den geschätzten Umsatz.

  • Der Parameter dimensions gibt an, wie die Messwerte gruppiert werden.

  • Der Parameter filters gibt an, wie die Berichtsdaten gefiltert werden. Anstatt also beispielsweise alle Daten für einen Kanal zurückzugeben, könnte ein Bericht so gefiltert werden, dass er nur Messwerte für ein bestimmtes Land, ein bestimmtes Video oder eine bestimmte Gruppe von Videos enthält.

    Hinweis: Mit der API kannst du mehrere Werte für die Filter video, playlist und channel angeben. In diesem Fall kannst du den Filter auch in die Liste der Dimensionen aufnehmen, damit die zurückgegebenen Messwerte auch nach Video, Playlist oder Kanal gruppiert werden.

Beispielberichtsoptionen

Angenommen, ein Kanalinhaber möchte einen Bericht zum Gerätetyp abrufen, um zu ermitteln, wie viele Aufrufe der Videos des Kanals auf Mobilgeräten, Spielekonsolen, Fernsehern usw. erfolgt sind.

  • Der Kanalinhaber legt den Parameter startDate auf 2015-06-01 und den Parameter endDate auf 2015-07-31 fest. Basierend auf diesen Werten enthält der Bericht Daten für einen Zeitraum von zwei Monaten.

  • Der Bericht zum Gerätetyp unterstützt die Messwerte views und estimatedMinutesWatched. Der Kanalinhaber legt daher den Parameter metrics auf views,estimatedMinutesWatched fest.

  • Für den Parameter dimensions hat der Kanalinhaber mehrere Optionen. Zwei davon sind in der folgenden Liste aufgeführt. Ein dritter wird später in diesem Abschnitt bei der Erläuterung des Parameterwerts filters behandelt.

    • Wenn Sie den Parameterwert auf deviceType festlegen, werden die Anzahl der Aufrufe und die Wiedergabezeit für den gesamten Zeitraum, den der Bericht abdeckt, nach Gerätetyp gruppiert. Mit diesem Wert werden in den Berichtsdaten Fragen wie die folgenden beantwortet:

    • Wie oft wurden die Videos des Kanals zwischen dem 1. Juni 2015 und dem 31. Juli 2015 auf Mobilgeräten angesehen?

    • Wie oft wurden die Videos des Kanals zwischen dem 1. Juni 2015 und dem 31. Juli 2015 auf Spielekonsolen angesehen?

    Der Bericht enthält die Gesamtzahl der Aufrufe und die Wiedergabezeit für jeden Gerätetyp.

    • Wenn Sie den Parameterwert auf day,deviceType festlegen, werden die Anzahl der Aufrufe und die Wiedergabezeit für jeden Tag im Berichtszeitraum nach Gerätetyp berechnet. Mit diesem Wert werden in den Berichtsdaten Fragen wie die folgenden beantwortet:

    • Wie oft wurden die Videos des Kanals am 1. Juni 2015 auf Mobilgeräten angesehen?

    • Wie oft wurden die Videos des Kanals am 14. Juli 2015 auf Fernsehern angesehen?

  • Mit dem Parameter filters kann der Kanalinhaber den Bericht schließlich so einschränken, dass er nur Daten enthält, die bestimmten Filterwerten entsprechen. Der Bericht unterstützt zu viele Filteroptionen, um sie alle zu erklären. Diese Beispiele stellen daher nur einen Bruchteil der Berichte dar, die Sie generieren können.

    • Der Kanalinhaber könnte die Anfrage so filtern, dass nur Werte für das Android-Betriebssystem zurückgegeben werden. (Wie viele Aufrufe gab es im Berichtszeitraum auf Android-Mobilgeräten?)

    • Der Kanalinhaber kann die Anfrage so filtern, dass nur Werte für ein bestimmtes Land zurückgegeben werden. (Wie oft wurden Videos in Kanada an den einzelnen Tagen des Berichtszeitraums angesehen?)

    • Der Kanalinhaber kann die Anfrage so filtern, dass nur Werte für bestimmte Videos zurückgegeben werden. Der Filter video unterstützt jedoch eine durch Kommas getrennte Liste von Werten, sodass der Bericht tatsächlich Daten für viele Videos enthalten kann.

    Wenn im Filter video mehrere Werte angegeben sind, kann video auch als Dimension angegeben werden. Das bedeutet, dass der Parameter dimensions auch die Werte deviceType,video und day,deviceType,video unterstützt.

    • Wenn der Kanalinhaber video in die Liste der Dimensionen aufnimmt, werden für die Messwerte einzelne Werte für jedes Video angegeben. (Wie oft wurde Video XYZ am 1. Juni 2015 auf einer Spielekonsole angesehen?)
    • Wenn der Kanalinhaber video nicht in die Liste der Dimensionen aufnimmt, geben die Messwerte die Gesamtwerte für alle angegebenen Videos an. (Wie oft wurden die Videos ABC, DEF und XYZ am 1. Juni 2015 auf einer Spielekonsole angesehen?)

Datenaktualität und ‑latenz

Die YouTube Analytics API unterstützt zwar gezielte Abfragen, die zugrunde liegenden Analysedaten sind jedoch nicht in Echtzeit verfügbar. Die Datenverarbeitung führt in der Regel zu einer Latenz von 48 bis 72 Stunden. Daher enthalten API-Antworten keine Daten für die letzten Tage und der endDate Ihres Berichts enthält nur Daten bis zum letzten Tag, für den alle angeforderten Messwerte vollständig verarbeitet wurden.

Aufgrund der Datenlatenz kann es zu Abweichungen zwischen den von der API zurückgegebenen Daten und den in YouTube Studio sichtbaren Echtzeitmesswerten kommen. Wenn deine Anwendung Echtzeitstatistiken für einzelne Videos erfordert, z. B. die aktuelle Anzahl der Aufrufe, Likes oder Kommentare, verwende die Methode videos.list der YouTube Data API anstelle der YouTube Analytics API.

Berichte abrufen

Wenn Sie einen Bericht abrufen möchten, senden Sie eine autorisierte GET-Anfrage an die Methode reports.query der API und geben Sie die Parameter an, die den abzurufenden Bericht definieren.

Eine Liste der von der API unterstützten Berichte findest du in der Dokumentation zu Kanalberichten und Rechteinhaberberichten. In jeder Berichtsdefinition werden die Werte angegeben, die im Bericht für die Parameter metrics, dimensions und filters zulässig sind.

Best Practices

Anwendungen, die die YouTube Analytics API verwenden, sollten immer die folgenden Best Practices befolgen:

  • Verwenden Sie die Kopfzeile einer Antwort, um die Reihenfolge der Spalten des Berichts zu bestimmen. Gehen Sie beispielsweise nicht davon aus, dass Aufrufe der erste Messwert ist, der in einer Antwort zurückgegeben wird, nur weil es der erste Messwert ist, der in einer Berichtsbeschreibung aufgeführt ist. Verwenden Sie stattdessen die Kopfzeile der Antwort, um zu ermitteln, welche Spalte diese Daten enthält.
  • Mit der YouTube Data API kannst du zusätzliche Metadaten für Ressourcen abrufen, die in Antworten der YouTube Analytics API identifiziert wurden. Gemäß den Richtlinien für Entwickler der YouTube API-Dienste (Abschnitte III.E.4.b bis III.E.4.d) müssen API-Clients gespeicherte Ressourcenmetadaten von dieser API nach 30 Tagen entweder löschen oder aktualisieren.

Zusammengefasste Messwerte und gelöschte Elemente

YouTube Analytics API-Antworten enthalten keine Messwertaufschlüsselungen für gelöschte Elemente. Wenn ein Kanalinhaber beispielsweise ein Video löscht, wird dieses Video nicht mehr in einer API-Antwort aufgeführt, die Messwerte für einzelne Videos zurückgibt. In Berichten, in denen Messwerte für eine Reihe von Ressourcen zusammengefasst werden, sind jedoch weiterhin Messwerte enthalten, die mit gelöschten Elementen verknüpft sind.

Angenommen, ein Kanalinhaber ruft zwei Berichte ab. Der erste Bericht enthält die täglichen Gesamtaufrufe für alle Videos des Kanals in einem bestimmten Zeitraum. Im zweiten Bericht werden die täglichen Aufrufe für jedes Video im selben Zeitraum aufgeführt.

In diesem Fall enthalten die Zahlen im ersten Bericht Aufrufe von Videos, die später gelöscht wurden, da der erste Bericht tägliche Gesamtwerte enthält. Der zweite Bericht enthält jedoch keine Aufrufe, die mit gelöschten Elementen verknüpft sind, da die Aufrufe darin nach Videos aufgeschlüsselt sind. Wenn also im Berichtszeitraum Videos auf dem Kanal gelöscht wurden, kann die Gesamtzahl der täglichen Aufrufe im ersten Bericht höher sein als die Summe der täglichen, videospezifischen Aufrufe im zweiten Bericht.

Datenanonymisierung

Einige YouTube Analytics-Daten sind eingeschränkt, wenn die Messwerte einen bestimmten Grenzwert nicht erreichen. Dies kann bei verschiedenen Berichten der Fall sein. In der Praxis bedeutet das, dass ein Bericht möglicherweise nicht alle (oder keine) Ihrer Daten enthält, wenn:

  1. ein Video oder Kanal während eines bestimmten Zeitraums nur wenige Zugriffe hat,

    oder

  2. Sie haben einen Filter oder eine Dimension ausgewählt, z. B. Traffic-Quelle oder Land, für die die Werte einen bestimmten Grenzwert nicht erreichen.

Bei eingeschränkten Daten können die Gesamtwerte in den verschiedenen Berichten voneinander abweichen. Dies hängt davon ab, wie die Daten darin zusammengefasst werden.

Angenommen, ein Kanalinhaber ruft zwei Berichte ab. Im ersten Bericht werden die Gesamtaufrufe für ein bestimmtes Video aufgeführt, im zweiten die Gesamtaufrufe für dieses Video nach Ländern. Im angegebenen Zeitraum nehmen wir an, dass das Video 1.000 Mal angesehen wurde. 500 Aufrufe erfolgten in den USA, 498 Aufrufe in Kanada und 2 Aufrufe in Frankreich.

In diesem Beispiel wird im ersten Bericht angezeigt, dass das Video 1.000 Mal aufgerufen wurde. Im zweiten Bericht wird nur angegeben, dass das Video in den USA 500 Mal und in Kanada 498 Mal angesehen wurde. Daher weicht hier die Gesamtzahl der Aufrufe in den beiden Berichten voneinander ab. Im zweiten Bericht wird nicht angezeigt, dass es zwei weitere Aufrufe bzw. Aufrufe in Frankreich gegeben hat.

Eingeschränkte Datentypen

Die folgenden Daten können in YouTube Analytics-Berichten eingeschränkt sein:

  • Demografische Daten wie Alter und Geschlecht.
  • Geografische Daten, einschließlich Messwerten oder Dimensionen, die sich auf die Länder oder Regionen beziehen, in denen sich die Zuschauer befinden, z. B. ihre Länder oder Regionen. Beachten Sie jedoch, dass in Berichten keine geografischen Grenzwerte auf Umsatzmesswerte angewendet werden.
  • Messwerte zu bestimmten Zugriffsquellen, z. B. Suchbegriffe oder externe URLs, über die deine Videos aufgerufen wurden. Suchbegriffe und URLs, die nur zu sehr wenigen Aufrufen führen, werden beispielsweise nicht in Berichten aufgeführt. Suchbegriffe und URLs, die viele Zuschauer zu deinen Inhalten führen, werden jedoch weiterhin angezeigt.

Weitere Informationen zu eingeschränkten Daten in YouTube Analytics-Berichten findest du in der YouTube-Hilfe.

Kontingentnutzung

Jede API-Anfrage, die Sie stellen, wird als eine Einheit Ihres API-Nutzungskontingents gezählt. Kontingentlimits werden in der Google Cloud Console im Bereich Kontingente angezeigt.