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 bezeichnet:

  • Dimensionen sind allgemeine Kriterien, die zum Aggregieren von Daten verwendet 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 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 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 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 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 zum Zeitpunkt der Abfrage alle Messwerte in der Abfrage verfügbar sind.

  • Der Parameter metrics gibt die Messungen an, die in den Bericht aufgenommen werden. In Kanalberichten werden mit Messwerten Nutzeraktivitäten gemessen. Dazu gehören Werte wie Aufrufe und Likes. 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. So kann ein Bericht beispielsweise so gefiltert werden, dass er nicht alle Daten für einen Kanal enthält, sondern nur Messwerte für ein bestimmtes Land, Video oder eine bestimmte Gruppe von Videos.

    Hinweis: Mit der API können Sie mehrere Werte für die Filter für Videos, Playlists und Kanäle angeben. In diesem Fall 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.

Beispielhafte Berichtsoptionen

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

  • Der Kanalinhaber 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.

  • Der Bericht zum Gerätetyp unterstützt die Messwerte Aufrufe und estimatedMinutesWatched. 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 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 Berichtszeitraum nach Gerätetyp gruppiert. Mit diesem Wert können Sie mit den 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 eine Gesamtzahl der Aufrufe und der 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 können Sie mit den 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 auf Fernsehern angesehen?

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

    • Der Kanalinhaber kann 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 kann die Anfrage so filtern, dass nur Werte für ein bestimmtes Land zurückgegeben werden. (Wie oft wurden 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 Video-Filter unterstützt jedoch eine durch Kommas getrennte Liste von Werten, sodass der Bericht Daten für viele Videos enthalten kann.

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

      • Wenn der Kanalinhaber „Video“ in die Liste der Dimensionen aufnimmt, enthalten die Messwerte einzelne Werte für jedes Video. (Wie oft wurde Video XYZ am 1. Juni 2015 auf einer Spielekonsole angesehen?)
      • Wenn der Kanalinhaber „Video“ nicht in die Liste der Dimensionen aufnimmt, enthalten die Messwerte Gesamtzahlen für alle angegebenen Videos. (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 Analytics-Daten 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. Der Parameter endDate Ihres Berichts enthält nur Daten bis zum letzten Tag, für den alle angeforderten Messwerte vollständig verarbeitet wurden.

Aufgrund der Datenlatenz können Abweichungen zwischen den von der API zurückgegebenen Daten und den in YouTube Studio sichtbaren Echtzeitmesswerten auftreten. Wenn Ihre Anwendung Echtzeitstatistiken für einzelne Videos benötigt, z. B. die aktuelle Anzahl der Aufrufe, Likes oder Kommentare, verwenden Sie stattdessen die YouTube Data API's videos.list Methode anstelle der YouTube Analytics API.

Berichte abrufen

Senden Sie zum Abrufen eines Berichts eine autorisierte GET-Anfrage an die Methode reports.query 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 sind 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 Best Practices beachten:

  • 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 sind, der in einer Antwort zurückgegeben wird, nur weil er in einer Berichtsbeschreibung als erster Messwert aufgeführt ist. Verwenden Sie stattdessen die Kopfzeile der Antwort, um zu ermitteln, in welcher Spalte diese Daten enthalten sind.
  • Verwenden Sie die YouTube Data API, um zusätzliche Metadaten für Ressourcen abzurufen, die in Antworten der YouTube Analytics API identifiziert wurden. Gemäß den Richtlinien für Entwickler*innen der YouTube API-Dienste (Abschnitte III.E.4.b bis III.E.4.d) müssen API-Clients gespeicherte Ressourcenmetadaten aus dieser API nach 30 Tagen entweder löschen oder aktualisieren.

Zusammengefasste Messwerte und gelöschte Elemente

Antworten der YouTube Analytics API enthalten keine Aufschlüsselung der Messwerte 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. Berichte, in denen Messwerte für eine Reihe von Ressourcen zusammengefasst werden, enthalten jedoch weiterhin Messwerte für gelöschte Elemente.

Angenommen, ein Kanalinhaber ruft zwei Berichte ab. Der erste Bericht enthält die Gesamtzahl der täglichen Aufrufe für alle Videos des Kanals in einem bestimmten Zeitraum. Der zweite Bericht enthält die Gesamtzahl der täglichen Aufrufe für einzelne Videos im selben Zeitraum.

In diesem Fall enthalten die Zahlen im ersten Bericht Aufrufe von Videos, die später gelöscht wurden, da der erste Bericht tägliche Aggregationen enthält. Der zweite Bericht enthält jedoch keine Aufrufe für gelöschte Elemente, da er Aufrufe für einzelne Videos auflistet. Wenn der Kanalinhaber also im Berichtszeitraum Videos gelöscht hat, 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 in 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 im angegebenen Zeitraum nur wenige Zugriffe hat

    oder

  2. Sie einen Filter oder eine Dimension wie Zugriffsquelle oder Land ausgewählt haben, 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. Der erste Bericht enthält die Gesamtzahl der Aufrufe für ein bestimmtes Video und der zweite Bericht enthält die Gesamtzahl der Aufrufe für dieses Video nach Land aufgeschlüsselt. 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 angegeben, 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. Der zweite Bericht enthält keine Angaben dazu, 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 können in YouTube Analytics-Berichten eingeschränkt sein:

  • Demografische Daten wie Alter und Geschlecht.
  • Geografische Daten, einschließlich Messwerte oder Dimensionen im Zusammenhang mit den Ländern oder Regionen, in denen sich die Zuschauer befanden, z. B. ihre Länder oder Regionen. In Berichten werden jedoch keine geografischen Grenzwerte auf Umsatzmesswerte angewendet.
  • Messwerte für bestimmte Zugriffsquellen, z. B. Suchbegriffe oder externe URLs, die zu Aufrufen Ihrer 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 Ihren Inhalten führen, werden jedoch weiterhin angezeigt.

Weitere Informationen zu eingeschränkten Daten in YouTube Analytics-Berichten finden Sie in der YouTube-Hilfe.

Kontingentnutzung

Jede API-Anfrage, die Sie senden, zählt als eine Einheit Ihres API-Nutzungskontingents. Kontingentlimits sind in der Google API Console im Bereich „Kontingente“ sichtbar.