YouTube Analytics API - Data Model

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

  • 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 aus Dimensionswerten. Anhand der Dimensionen, die Sie für einen Bericht auswählen, wird also bestimmt, wie YouTube die Werte für die Messwerte in diesem Bericht berechnet.

  • Messwerte sind individuelle Messungen im Zusammenhang mit Nutzeraktivitäten, Anzeigenleistung oder geschätztem Umsatz. Zu den Messwerten zur Nutzeraktivität gehören beispielsweise die Anzahl der Videoaufrufe und Bewertungen (positive und negative Bewertungen).

Die Analytics API bietet Filter- und Sortierparameter, sodass die aufrufende Anwendung diese Funktionen nicht nativ unterstützen muss. Über die 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 Methode reports.query der API anfordern, enthält die API-Anfrage fünf Parameter, die bestimmen, wie die Werte berechnet werden:

  • Die Parameter startDate und endDate geben den Zeitraum an, für den der Bericht Daten enthält. Die API-Antwort enthält Daten bis zum letzten angegebenen Tag, für den zum Zeitpunkt der Abfrage alle Messwerte in der Abfrage verfügbar sind.

  • Der Parameter metrics gibt die Messwerte an, die im Bericht enthalten sein sollen. In Channel-Berichten werden Messwerte zur Nutzeraktivität erfasst. Sie enthalten Werte wie Aufrufe und positive Bewertungen. Bei einigen Messwerten wird auch die Anzeigenleistung oder der geschätzte Umsatz gemessen.

  • Der Parameter dimensions erklärt, wie die Messwerte gruppiert werden.

  • Mit dem Parameter filters wird erläutert, 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 Video oder eine Gruppe von Videos enthält.

    Hinweis: In der API kannst du mehrere Werte für die Filter Video, Playlist und Kanal angeben. In diesem Fall können Sie diesen Filter auch in die Liste der Dimensionen aufnehmen, sodass die zurückgegebenen Messwerte auch nach Video, Playlist oder Channel gruppiert werden.

Beispiele für Berichtsoptionen

Beispiel: Ein Kanalinhaber möchte einen Bericht zu einem Videogerätetyp abrufen, um zu ermitteln, wie viele Aufrufe der Videos auf einem Mobilgerät, einer Spielekonsole oder einem Fernseher erzielt wurden.

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

  • Der Gerätetypbericht unterstützt die Messwerte Aufrufe und estimatedMinutesWatched, sodass der Kanalinhaber den Parameter metrics auf views,estimatedMinutesWatched setzt.

  • Für den Parameter dimensions hat der Kanalinhaber eine Reihe von Optionen. Zwei davon sind in der folgenden Liste aufgeführt. Ein drittes wird in der Erläuterung des Parameterwerts filters weiter unten erläutert.

    • Wenn du den Parameterwert auf deviceType setzt, werden die Anzahl der Aufrufe und die Wiedergabezeit für den gesamten Zeitraum, der im Bericht berücksichtigt wird, nach Gerätetyp gruppiert. Mit diesem Wert können Sie anhand der Berichtsdaten beispielsweise folgende Fragen 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 angesehen?

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

    • Wenn du den Parameterwert auf day,deviceType setzt, wird die Anzahl der Aufrufe und die Wiedergabezeit während des Berichtszeitraums für jeden Tag nach Gerätetyp berechnet. Mit diesem Wert können Sie anhand der Berichtsdaten beispielsweise folgende Fragen beantworten:

      • 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 im Fernsehen angesehen?

  • Mit dem Parameter filters kann der Kanalinhaber den Bericht auf Daten beschränken, die mit bestimmten Filterwerten übereinstimmen. Der Bericht unterstützt zu viele Filteroptionen, um alle zu erklären. Diese Beispiele stellen also nur einen Bruchteil der Berichte dar, die Sie erstellen können.

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

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

    • Der Kanalinhaber kann die Anfrage so filtern, dass nur Werte für bestimmte Videos zurückgegeben werden. Der Videofilter unterstützt jedoch eine durch Kommas getrennte Liste von Werten. Der Bericht kann also Daten für viele Videos enthalten.

      Wenn der Filter Video mehrere Werte enthält, 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, geben die Messwerte für jedes Video einzelne Werte an. (Wie oft wurde das Video XYZ am 1. Juni 2015 auf einer Spielekonsole angesehen?)
      • Wenn der Channelinhaber 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?)

Berichte werden abgerufen

Senden Sie zum Abrufen eines Berichts eine autorisierte GET-Anfrage an die reports.query-Methode der API und geben Sie die Parameter an, die den gewünschten Bericht definieren.

In der Dokumentation zu Kanalberichten und Berichten zu Rechteinhabern finden Sie eine Liste der Berichte, die von der API unterstützt werden. Jede Berichtsdefinition gibt die Werte an, die im Bericht für die Parameter metrics, dimensions und filters zulässig sind.

Best Practices

Für Anwendungen, in denen die YouTube Analytics API verwendet wird, gelten immer die folgenden Schritte:

  • 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 dies der erste Messwert ist, der in einer Berichtsbeschreibung aufgeführt wird. Verwenden Sie stattdessen die Kopfzeile der Antwort, um festzustellen, welche Spalte diese Daten enthält.
  • Mit der YouTube Data API kannst du zusätzliche Metadaten für Ressourcen abrufen, die in den 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 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 jedes einzelne Video zurückgibt. Berichte, die Messwerte für eine Gruppe von Ressourcen zusammenfassen, enthalten jedoch weiterhin Messwerte, die mit gelöschten Elementen verknüpft sind.

Beispiel: Ein Kanalinhaber ruft zwei Berichte ab. Der erste Bericht listet die gesamten Aufrufe pro Tag für alle Videos des Kanals über einen bestimmten Zeitraum auf. Der zweite Bericht listet die täglichen Aufrufe für einzelne Videos im selben Zeitraum auf.

In diesem Fall enthält der erste Bericht Aufrufe von Videos, die später gelöscht wurden, weil der erste Bericht tägliche Zusammenfassungen enthält. Der zweite Bericht enthält jedoch keine Aufrufe für gelöschte Elemente, da im zweiten Bericht die Aufrufe für jedes einzelne Video aufgeführt werden. Wenn der Kanal in diesem Zeitraum Videos gelöscht hat, kann die Gesamtzahl der täglichen Aufrufe im ersten Bericht daher höher sein als die Summe der täglichen Videoaufrufe im zweiten Bericht.

Datenanonymisierung

Einige YouTube Analytics-Daten sind eingeschränkt, wenn Messwerte einen bestimmten Grenzwert nicht erreichen. Das kann in verschiedenen Berichten passieren. In der Praxis bedeutet dies, dass ein Bericht in den folgenden Fällen möglicherweise nicht (oder überhaupt) Ihre Daten enthält:

  1. ein Video oder ein Kanal nur über einen festgelegten Zeitraum verfügt,

    oder

  2. Sie haben einen Filter oder eine Dimension ausgewählt, z. B. Zugriffsquelle oder Land, für die bestimmte Werte nicht erreicht werden.

In Fällen, in denen die Daten begrenzt sind, kann ein Unterschied zwischen den Summen in den verschiedenen Berichten auftreten, je nachdem, wie in den Berichten Daten aggregiert werden.

Beispiel: Ein Kanalinhaber ruft zwei Berichte ab. Der erste Bericht listet die Gesamtzahl der Aufrufe für ein bestimmtes Video auf, der zweite Bericht gibt die Gesamtzahl der Aufrufe für dieses Video nach Land aufgeschlüsselt an. Angenommen, das Video wurde im angegebenen Zeitraum 1.000 Mal angesehen. 500 Aufrufe erfolgten in den USA, 498 in Kanada und zwei in Frankreich.

In diesem Beispiel gibt der erste Bericht an, dass das Video 1.000 Mal angesehen wurde. Der zweite Bericht würde nur anzeigen, dass das Video in den USA 500 und in Kanada 498 Mal angesehen wurde. Daher würde sich die Gesamtzahl der Aufrufe in den beiden Berichten unterscheiden. Beachten Sie, dass der zweite Bericht keinen Hinweis darauf enthält, dass zwei weitere Aufrufe stattgefunden haben oder dass ein Aufruf in Frankreich stattgefunden hat.

Die tatsächlichen Schwellenwerte, bei denen Daten begrenzt sind, 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
  • Geografische Daten, einschließlich Messwerten oder Dimensionen in Bezug auf die Länder oder Regionen, in denen sich die Zuschauer befinden, z. B. ihre Länder oder Regionen In Berichten werden jedoch keine geografischen Grenzwerte auf Umsatzmesswerte angewendet.
  • Messwerte zu bestimmten Zugriffsquellen wie 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 trotzdem aufgeführt.

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

Kontingentnutzung

Jede von Ihnen gesendete API-Anfrage zählt als eine Einheit Ihres API-Nutzungskontingents. Kontingentlimits werden in der Google API Console im Bereich Kontingente angezeigt.