YouTube Analytics API - Data Model

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

  • Dimensionen sind gängige Kriterien, mit denen Daten aggregiert werden, z. B. das Datum, an dem eine Aktion ausgeführt wurde, oder das Land, in dem sich die Nutzer befanden.

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

  • Messwerte sind einzelne Messungen, die sich auf Nutzeraktivitäten, Anzeigenleistung oder geschätzten Umsatz beziehen. Zu den Messwerten für Nutzeraktivitäten gehören unter anderem die Anzahl der Videoaufrufe und Bewertungen („Mag ich“ und „Mag ich nicht“).

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

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 enthält. Die API-Antwort enthält 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 Messungen angegeben, die im Bericht enthalten sein sollen. In Channel-Berichten werden Messwerte zur Messung der Nutzeraktivität verwendet. Dazu gehören Werte wie Aufrufe und Likes. Einige Messwerte beziehen sich auch auf 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 beispielsweise alle Daten für einen Kanal zurückzugeben, kann 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 können Sie mehrere Werte für die Filter video, playlist und channel angeben. Wenn Sie das tun, können Sie diesen 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 für Videos abrufen, um herauszufinden, wie viele Aufrufe der Videos des Kanals auf Mobilgeräten, Spielekonsolen, Fernsehern usw. erzielt wurden.

  • Der Channelinhaber legt den Parameter startDate auf 2015-06-01 und den Parameter endDate auf 2015-07-31 fest. Anhand dieser Werte enthält der Bericht Daten für einen Zeitraum von zwei Monaten.

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

  • Für den Parameter dimensions hat der Kanalinhaber mehrere Optionen. Zwei davon sind in der folgenden Liste aufgeführt. Eine dritte wird später in diesem Abschnitt in der Erklärung des Parameterwerts filters behandelt.

    • Wenn Sie den Parameterwert auf deviceType festlegen, werden die Aufruf- und Wiedergabezeit für den gesamten Zeitraum, den der Bericht abdeckt, nach Gerätetyp gruppiert. Mit diesem Wert lassen sich mit den Berichtsdaten Fragen wie die folgenden beantworten:

      • 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 aufgerufen?

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

    • Wenn Sie den Parameterwert auf day,deviceType festlegen, werden die Aufruf- und Wiedergabezeit für jeden Tag im Berichtszeitraum nach Gerätetyp berechnet. Mit diesem Wert lassen sich mit den Berichtsdaten Fragen wie die folgenden beantworten:

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

  • Mit dem Parameter filters kann der Kanalinhaber den Bericht auf Daten beschränken, die bestimmten Filterwerten entsprechen. Der Bericht unterstützt so viele Filteroptionen, dass es unmöglich ist, alle zu erläutern. Die folgenden Beispiele stellen daher nur einen Bruchteil der Berichte dar, die Sie generieren könnten.

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

    • Der Kanalinhaber könnte die Anfrage filtern, um nur Werte für ein bestimmtes Land zurückzugeben. (Wie oft wurden Videos in Kanada an jedem Tag des Berichtszeitraums angesehen?)

    • Der Kanalinhaber kann die Anfrage filtern, um nur Werte für bestimmte Videos zurückzugeben. Der Filter Video unterstützt jedoch eine kommagetrennte Liste von Werten. Der Bericht kann also Daten für viele Videos enthalten.

      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 Channelinhaber Video in die Liste der Dimensionen aufnimmt, geben die Messwerte einzelne Werte für jedes Video an. (Wie oft wurde Video XYZ am 1. Juni 2015 auf einer Spielekonsole aufgerufen?)
      • Wenn der Kanalinhaber video nicht in die Liste der Dimensionen aufnimmt, geben die Messwerte Gesamtwert für alle angegebenen Videos an. (Wie oft wurden die Videos ABC, DEF und XYZ am 1. Juni 2015 auf einer Spielekonsole aufgerufen?)

Berichte abrufen

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

Eine Liste der von der API unterstützten Berichte finden Sie in der Dokumentation zu Kanalberichten und Berichten für Rechteinhaber. In jeder Berichtsdefinition werden die Werte angegeben, die für die Parameter metrics, dimensions und filters zulässig sind.

Best Practices

Anwendungen, die die YouTube Analytics API verwenden, sollten immer die folgenden Richtlinien einhalten:

  • Anhand der Kopfzeile einer Antwort können Sie die Reihenfolge der Spalten im Bericht bestimmen. Gehen Sie beispielsweise nicht davon aus, dass Aufrufe der erste Messwert ist, der in einer Antwort zurückgegeben wird, nur weil er der erste Messwert ist, der in einer Berichtsbeschreibung aufgeführt ist. Verwenden Sie stattdessen die Kopfzeile der Antwort, um zu ermitteln, in welcher Spalte sich diese Daten befinden.
  • Mit der YouTube Data API können Sie zusätzliche Metadaten für Ressourcen abrufen, die in YouTube Analytics API-Antworten identifiziert wurden. Wie in den Richtlinien für Entwickler der YouTube API-Dienste (Abschnitte III.E.4.b bis III.E.4.d) beschrieben, müssen API-Clients gespeicherte Ressourcenmetadaten aus 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 es nicht mehr in einer API-Antwort aufgeführt, in der Messwerte auf Videoebene zurückgegeben werden. Berichte, in denen Messwerte für eine Reihe von Ressourcen zusammengefasst werden, enthalten jedoch weiterhin Messwerte, die mit gelöschten Elementen verknüpft sind.

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

In diesem Fall enthält der erste Bericht Aufrufe von Videos, die später gelöscht wurden, da er tägliche Aggregate enthält. Der zweite Bericht enthält jedoch keine Aufrufe, die mit gelöschten Elementen verknüpft sind, da er Aufrufe auf Videoebene auflistet. Wenn auf dem Kanal im Berichtszeitraum Videos 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. Das 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 in einem bestimmten Zeitraum nur eingeschränkte Zugriffe hat,

    oder

  2. Sie haben einen Filter oder eine Dimension wie Traffic-Quelle oder Land ausgewählt, 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 sind die Gesamtaufrufe für ein bestimmtes Video aufgeführt, im zweiten Bericht die Gesamtaufrufe für dieses Video nach Land. 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.

Im ersten Bericht in diesem Beispiel wird 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.

Die tatsächlichen Grenzwerte eingeschränkter Daten werden nicht veröffentlicht und können nach Ermessen von YouTube geändert werden.

Eingeschränkte Datentypen

Die folgenden Daten sind in YouTube Analytics-Berichten möglicherweise eingeschränkt:

  • Demografische Daten wie Alter und Geschlecht.
  • Standortbezogene Daten, einschließlich Messwerten oder Dimensionen, die sich auf die Länder oder Regionen beziehen, in denen sich die Zuschauer aufhalten, z. B. ihre Länder oder Regionen. In Berichten werden jedoch keine geografischen Mindesteinnahmen auf Umsatzmesswerte angewendet.
  • Messwerte zu bestimmten Zugriffsquellen, z. B. Suchbegriffe oder externe URLs, die zu Aufrufen deiner Videos geführt haben. Suchbegriffe und URLs, die zu sehr wenigen Aufrufen führen, werden beispielsweise nicht in Berichten angezeigt. Begriffe und URLs, die viele Zuschauer zu deinen Inhalten führen, werden aber 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, zählt als eine Einheit Ihres API-Nutzungskontingents. Kontingentlimits werden in der Google API Console im Bereich Kontingente angezeigt.