Uwaga:Content owner reports are only accessible to YouTube content partners who participate in the YouTube Partner Program.
Ta strona zawiera listę raportów, które właściciele treści mogą pobrać za pomocą interfejsu API Statystyk YouTube. Raporty właścicieli treści zawierają dane dotyczące kanałów powiązanych z określonym właścicielem treści w YouTube. Dane to poszczególne pomiary aktywności użytkowników, skuteczności reklam lub szacunkowych przychodów.
Raporty dotyczące filmów zawierają dane o aktywności użytkowników, skuteczności reklam i szacowanych przychodach z filmów na kanałach właściciela treści.
Raporty dotyczące playlist zawierają statystyki dotyczące wyświetleń filmów w kontekście danej playlisty. Raporty dotyczące playlist używają wielu tych samych zakresów i filtrów co raporty dotyczące filmów.
Raporty skuteczności reklam zawierają dane dotyczące przychodów i skuteczności reklam. Używają wymiaru adType do grupowania danych według typów reklam wyświetlanych podczas odtwarzania filmów. W sekcji raporty o skuteczności reklam znajdziesz wyjaśnienie 2 typów danych o skuteczności reklam obsługiwanych przez interfejs API.
Pobieranie raportu
Aby pobrać raport właściciela treści, wywołaj metodę reports.query interfejsu API i ustaw wartość parametru ids w żądaniu interfejsu API na contentOwner==OWNER_NAME, gdzie OWNER_NAME określa identyfikator właściciela treści. Jeśli nie masz pewności co do wartości, zapytaj swojego menedżera ds. partnera.
Autoryzacja
Wszystkie żądania do interfejsu API Statystyk YouTube muszą być autoryzowane. W przewodniku Autoryzacja znajdziesz informacje o pobieraniu tokenów autoryzacji za pomocą protokołu OAuth 2.0.
Żądania do interfejsu API Statystyk YouTube korzystają z tych zakresów autoryzacji:
Wyświetlanie raportów Statystyk YouTube dotyczących treści w YouTube. Ten zakres uprawnień zapewnia dostęp do danych o aktywności użytkowników, takich jak liczba wyświetleń i ocen.
Wyświetlanie raportów finansowych Statystyk YouTube dotyczących treści w YouTube Ten zakres uprawnień zapewnia dostęp do danych o aktywności użytkowników oraz szacowanych przychodów i danych o skuteczności reklam.
https://www.googleapis.com/auth/youtube
Zarządzanie kontem YouTube. W interfejsie API Statystyk YouTube właściciele kanałów używają tego zakresu do zarządzania grupami i elementami grup w Statystykach YouTube.
https://www.googleapis.com/auth/youtubepartner
Wyświetlanie zasobów w YouTube oraz powiązanych z nimi treści i zarządzanie nimi w serwisie YouTube W interfejsie YouTube Analytics API właściciele treści używają tego zakresu do zarządzania grupami i elementami grup w Statystykach YouTube.
Uwaga: dane oznaczone gwiazdką (*) wymagają tokena autoryzacji, który przyznaje dostęp do zakresu https://www.googleapis.com/auth/yt-analytics-monetary.readonly.*
Filtry
Wszystkie żądania interfejsu API służące do pobierania raportów właścicieli treści muszą filtrować dane za pomocą wymiaru video, channel, isCurated lub obsługiwanej kombinacji wymiarów claimedStatus i uploaderType. (obsługiwane kombinacje znajdziesz w definicji wymiaru uploaderType).
Tabele z informacjami o obsługiwanych raportach wskazują filtry, których można używać w każdym raporcie. W opisach filtry w nawiasach są opcjonalne. Jeśli na przykład w raporcie jako opcja filtrowania jest podana wartość video(,country), możesz przefiltrować raport, aby uwzględniał tylko dane o konkretnym filmie lub tylko dane o konkretnym filmie w konkretnym kraju.
Interfejs API umożliwia też określenie wielu wartości dla filtrów video, playlist i channel. Jeśli określisz kilka wartości dla jednego z tych filtrów, możesz też dodać ten filtr do listy wymiarów, które podajesz w prośbie. Dzieje się tak nawet wtedy, gdy filtr nie jest wymieniony jako obsługiwany wymiar w danym raporcie.
Aby dowiedzieć się, jak filtrować wyniki interfejsu API pod kątem określonej wartości lub zestawu wartości, zapoznaj się z definicją parametru filters.
Interpretowanie tabel raportów
W tej sekcji wyjaśniamy formatowanie i terminologię używane w tabelach definiujących raporty obsługiwane przez interfejs API. W tabeli poniżej znajdziesz wymiary, dane i filtry obsługiwane w raporcie wideo Szczegóły odtwarzania, który korzysta z wymiaru Czas i danych averageViewPercentage.
Tabela zawiera 2 wiersze dla wymiarów, 1 wiersz dla danych i 3 wiersze dla filtrów. W przypadku wymiarów i filtrów wartości z każdego wiersza można łączyć w zapytaniu do interfejsu API, o ile tylko dana kombinacja jest zgodna z zasadami użycia w tabeli. Przykładowe prawidłowe wartości parametru dimensions w tym raporcie:
dimensions=day
dimensions=day,subscribedStatus
dimensions=month,subscribedStatus,youtubeProduct
dimensions=month,youtubeProduct
Wartość parametru day,month jest jednak nieprawidłowa, ponieważ zawiera 2 wymiary oparte na czasie, a żądanie musi zawierać wartość 0 lub 1.
Terminologia tabeli raportów
W tabelach używamy tej terminologii, aby wskazać, czy wymiary są wymagane, czy opcjonalne:
Te terminy oznaczają, że wymagana jest wartość:
Wymagane: musisz podać wartość.
Użyj dokładnie 1: musisz uwzględnić jedną wartość z grupy.
Użyj co najmniej 1 wartości: możesz uwzględnić dowolną lub wszystkie wartości z grupy, ale musisz uwzględnić co najmniej 1 wartość.
Te warunki oznaczają, że wartość jest opcjonalna:
Opcjonalnie: możesz podać wartość.
Użyj wartości 0 lub 1: możesz uwzględnić jedną wartość z grupy.
Użyj wartości 0 lub większej: możesz uwzględnić dowolną wartość z grupy lub wszystkie jej wartości.
Ważne: wszystkie żądania interfejsu API służące do pobierania raportów o filmach właścicieli treści muszą filtrować dane za pomocą wymiaru video, channel, group lub obsługiwanej kombinacji wymiarów claimedStatus i uploaderType. (niektóre raporty nie obsługują wszystkich tych opcji). Obsługiwane kombinacje, które są też wymienione w definicji wymiaru uploaderType:
uploaderType==self
claimedStatus==claimed
claimedStatus==claimed;uploaderType==self
claimedStatus==claimed;uploaderType==thirdParty
Raporty na temat filmów
Statystyki podstawowe
podstawowe statystyki (w tym liczba subskrybentów);
Ten raport zawiera statystyki związane z działaniami użytkowników we wszystkich kanałach właściciela treści. Możesz filtrować raport, aby zwracał dane tylko z konkretnego filmu lub kraju. Można go też użyć do pobrania statystyk tylko dla treści objętych roszczeniem, w tym treści objętych roszczeniem przesłanych przez właściciela treści, osoby trzecie lub obie te strony.
Ten raport zawiera statystyki dotyczące konkretnego stanu w USA lub Dystryktu Kolumbii. Pamiętaj, że ten raport obsługuje tylko podzbiór danych dostępnych w opisanym powyżej raporcie dotyczącym konkretnego kraju.
Ten raport zawiera statystyki związane z działaniami użytkowników we wszystkich kanałach właściciela treści w określonych przedziałach czasu. Możesz filtrować raport, aby zwracał dane tylko z konkretnego filmu lub kraju.
Aktywność użytkowników w stanach USA w określonych przedziałach czasu
Ten raport zawiera statystyki dotyczące konkretnego stanu w USA lub Dystryktu Kolumbii. Pamiętaj, że ten raport obsługuje tylko podzbiór danych dostępnych w opisanym powyżej raporcie dotyczącym konkretnego kraju.
Ten raport zawiera statystyki dotyczące aktywności użytkowników w poszczególnych krajach w przypadku wszystkich kanałów właściciela treści. Możesz filtrować raport, aby zwracał dane tylko z określonego filmu lub kanału.
Ten raport zawiera statystyki aktywności użytkowników w stanach USA i Dystrykcie Kolumbii. W tym raporcie musisz ustawić wartość parametru filters na country==US.
Aktywność użytkowników według miasta (maksymalnie 250 wyników)
Uwaga: aby korzystać z tego raportu, musisz ustawić parametr maxResults na wartość całkowitą równą 250 lub mniejszą. W odróżnieniu od większości innych raportów ten raport wymaga też podania wartości parametru żądania sort.
Ten raport zawiera statystyki aktywności użytkowników według miasta.
Raporty dotyczące szczegółów odtwarzania zawierają statystyki związane z tymi atrybutami odtwarzania:
Czy obejrzano transmisję na żywo, czy film na żądanie?
Czy widz subskrybował kanał, którego właścicielem jest osoba, która przesłała film?
W której usłudze YouTube miało miejsce wyświetlenie?
Formalnie wymiary szczegółów odtwarzania obsługiwane przez te raporty są opcjonalne. Jeśli w prośbie nie uwzględnisz wymiarów szczegółów odtwarzania, zwrócony raport będzie podobny do jednego z raportów statystyk podstawowych, na podstawie czasu lub geografii użytkowników.
Ten raport zawiera dane o aktywności użytkowników, którzy mają subskrypcję i którzy jej nie mają. Statystyki można grupować według okresu (dzień lub miesiąc), a raport można filtrować według kraju, kontynentu lub subContinent.
Aktywność użytkowników według stanu subskrypcji w poszczególnych prowincjach
Ten raport zawiera dane o aktywności użytkowników, którzy mają subskrypcję i nie mają subskrypcji, w stanach USA lub Dystrykcie Kolumbii. Ten raport obsługuje mniej danych niż poprzedni.
Szczegóły odtwarzania z opcjonalnym wymiarem czasu
Wymiar czasu (dzień lub miesiąc) jest w przypadku tych raportów opcjonalny, ponieważ w każdym razie musisz użyć parametrów żądania startDate i endDate, aby określić zakres dat, którego ma dotyczyć raport. Wymiar, jeśli jest obecny, wskazuje, że chcesz, aby dane w raporcie były agregowane według dnia, miesiąca itp.
Szczegóły odtwarzania z opcjonalnym wymiarem czasu i statystykami liveOrOnDemand
Ten raport zawiera szczegółowe statystyki odtwarzania w określonych przedziałach czasu. Obsługuje wymiar (i filtr) liveOrOnDemand.
Szczegóły miejsca odtwarzania (maksymalnie 25 wyników)
Uwaga: aby korzystać z tego raportu, musisz ustawić parametr maxResults na wartość całkowitą równą 25 lub mniejszą. W odróżnieniu od większości innych raportów ten raport wymaga też podania wartości parametru żądania sort.
Ten raport wskazuje osadzone odtwarzacze wideo, które wygenerowały najwięcej wyświetleń lub najdłuższy czas oglądania treści właściciela. Podczas pobierania tego raportu musisz ustawić filtr insightPlaybackLocationType na EMBEDDED.
Ten raport agreguje statystyki oglądania na podstawie sposobu, w jaki widzowie dotarli do Twoich treści. Przykładowo, identyfikuje on liczbę obejrzeń, które pochodzą z wyszukiwania w Google lub z linku do powiązanego filmu.
Uwaga: ten raport zwraca błąd,jeśli iloczyn liczba zapytanych filmów × liczba dni w zakresie dat przekracza 50 tys. Na przykład zapytanie, które pobiera dane dla 500 identyfikatorów filmów, może zawierać żądanie danych z maksymalnie 100 dni. Aby zmniejszyć liczbę wierszy zwracanych przez żądanie, podziel zapytanie na kilka zapytań, które określają mniej filmów lub zawierają krótsze zakresy dat.
Uwaga: aby korzystać z tego raportu, musisz ustawić parametr maxResults na wartość całkowitą równą 25 lub mniejszą. W odróżnieniu od większości innych raportów ten raport wymaga też podania wartości parametru żądania sort.
Ten raport agreguje statystyki oglądania na podstawie źródeł, które wygenerowały najwięcej wyświetleń treści właściciela. Odesłania są przypisywane do kategorii według typu źródła wizyty, a definicja wymiaru insightTrafficSourceDetail wskazuje źródła wizyt, dla których jest dostępny raport. Jeśli np. ustawisz filtr insightTrafficSourceType na ADVERTISING, raport będzie zawierać listę typów reklam, które wygenerowały najwięcej wyświetleń lub czas oglądania treści właściciela.
Uwaga: ten raport jest obsługiwany tylko w przypadku określonych źródeł ruchu. VIDEO_REMIXES, NOTIFICATION, END_SCREEN, CAMPAIGN_CARD, VIDEO_REMIXES i NO_LINK_EMBEDDED to niektóre z nieobsługiwanych źródeł wizyt.
Typ urządzenia i system operacyjny
Typ urządzenia
Ten raport agreguje statystyki oglądania na podstawie typu urządzenia, którego używali widzowie podczas oglądania Twoich treści. Na przykład określa liczbę wyświetleń na tabletach lub konsolach do gier.
Ten raport agreguje statystyki oglądania na podstawie systemów operacyjnych widzów. Na przykład identyfikuje liczbę wyświetleń na urządzeniach z Androidem lub na konsolach PlayStation.
Ten raport agreguje statystyki oglądania według systemów operacyjnych i typów urządzeń widzów. Na przykład identyfikuje liczbę wyświetleń na tabletach z Androidem lub na komputerach z systemem Windows.
Uwaga: wartości viewerPercentage w tym raporcie nie są normalizowane dla różnych wartości wymiaru szczegółów odtwarzania subscribedStatus.
Na przykład jeśli raport używa wymiaru subscribedStatus, zwraca dane viewerPercentage, które sumują się do 100% w przypadku odtworzeń z subskrypcją i dane viewerPercentage, które sumują się do 100% w przypadku odtworzeń bez subskrypcji. (łączna wartość wszystkich pól viewerPercentage w raporcie wynosi 200 procent).
Ten raport mierzy zdolność filmu do utrzymywania uwagi odbiorców. Wymiar elapsedVideoTimeRatio mierzy czas trwania filmu dla odpowiednich wartości danych. Dane audienceWatchRatio i relativeRetentionPerformance to 2 wskaźniki, które pokazują, jak dobrze film utrzymuje uwagę odbiorców. Pierwszy z nich to wartość bezwzględna, a drugi pokazuje, jak film wypada w porównaniu z innymi filmami w YouTube o podobnej długości.
Uwaga: raporty Utrzymanie uwagi odbiorców nie umożliwiają określenia listy wartości oddzielonych przecinkami dla filtra video. Wartość musi zawierać identyfikator pojedynczego filmu.
Uwaga: aby móc korzystać z tych raportów, musisz ustawić parametr maxResults na wartość całkowitą nie większą niż 200. Dane z okresu przed 1 stycznia 2013 r. obejmują tylko 10 najpopularniejszych filmów. W odróżnieniu od większości innych raportów w przypadku tych raportów musisz też podać wartość parametru żądania sort.
Najpopularniejsze filmy w ogóle, według kraju, kontynentu lub subkontynentu (maksymalnie 200 wyników)
Ten raport zawiera listę najpopularniejszych filmów właściciela treści na podstawie określonych kryteriów filtrowania i sortowania.
Najpopularniejsze filmy według stanu w USA (maksymalnie 200 wyników)
Ten raport zawiera listę najpopularniejszych filmów właściciela treści w konkretnym stanie USA lub Dystrykcie Kolumbii. Pamiętaj, że ten raport obsługuje tylko podzbiór danych dostępnych w opisanym powyżej raporcie dotyczącym konkretnego kraju.
Najpopularniejsze filmy dla widzów, którzy subskrybują kanał lub go anulowali (maksymalnie 200 wyników)
Ten raport zawiera listę najpopularniejszych filmów wśród subskrybentów i widzów bez subskrypcji. Raport można filtrować, aby wyświetlić najpopularniejsze filmy według kraja, kontynentu lub subContinent. Poprzedni raport umożliwia pobieranie danych o najpopularniejszych filmach w konkretnym stanie w Stanach Zjednoczonych dla widzów, którzy subskrybowali kanał lub z niego zrezygnowali, ale zawiera mniej danych niż ten raport.
Najpopularniejsze filmy według usługi w YouTube (maksymalnie 200 wyników)
Ten raport zawiera listę najpopularniejszych filmów i obsługuje szczegóły odtwarzania oraz filtry geograficzne. Ten raport jest podobny do poprzedniego, ale obsługuje mniej danych i dodaje filtr youtubeProduct.
Najpopularniejsze filmy z filtrami szczegółów odtwarzania (maksymalnie 200 wyników)
Ten raport zawiera listę najpopularniejszych filmów właściciela treści, z filtrem według co najmniej jednego wymiaru szczegółów odtwarzania: liveOrOnDemand, subscribedStatus i youtubeProduct. Raport obsługuje też filtrowanie według regionu.
Raporty dotyczące playlist zawierają dane o aktywności użytkowników związanej z filmami na playlistach właściciela kanału. Dostępne są 2 wersje tych raportów. W przypadku każdego z nich w tych sekcjach znajdziesz opisy obu wersji:
Karta Zalecane w każdej sekcji zawiera opis preferowanego formatu żądania interfejsu API do pobierania odpowiedniego raportu. Polecane raporty obsługują rozszerzony zestaw danych, który obejmuje zarówno zbiorcze dane wideo, jak i dane dotyczące playlisty. Ten format zapytania nie używa wymiaru isCurated.
Karta Korzystanie z isCurated w każdej sekcji opisuje starszy format żądania interfejsu API, w którym wymagana jest wymiar isCurated. Te raporty obsługują tylko dane na poziomie playlisty. Pamiętaj, że wymiar isCurated został wycofany we wszystkich raportach. W poniższym ostrzeżeniu znajdziesz informacje o harmonogramie wycofywania.
W poniższym ostrzeżeniu znajdziesz szczegółowe informacje o różnicach między tymi 2 wersjami raportu.
Zbiorcze dane wideo
Te dane obejmują aktywność użytkowników i dane dotyczące wyświetleń, które są agregowane dla wszystkich filmów na playliście należących do kanału, który jest właścicielem playlisty. Dane dotyczące filmów należących do innych kanałów nie są uwzględniane w agregacji. W rezultacie, jeśli kanał utworzy playlistę zawierającą tylko filmy należące do innych kanałów, raporty dotyczące tych playlist nie będą zawierać wartości tych danych.
Te dane odzwierciedlają aktywność i zaangażowanie użytkowników w kontekście strony playlisty. Te dane obejmują wyświetlenia wszystkich filmów z playlisty, niezależnie od tego, do którego kanału należą, ale uwzględniają tylko wyświetlenia, które miały miejsce w kontekście playlisty.
Ten raport zawiera statystyki dotyczące interakcji użytkowników z filmami na playlistach na kanałach właściciela treści. Raport nie zawiera wymaganych wymiarów.
Ten raport zawiera statystyki dotyczące interakcji użytkowników z filmami na playlistach na kanałach właściciela treści w określonych przedziałach czasu. Możesz filtrować raport, aby zwracał tylko dane dotyczące określonej playlisty lub kanału.
Ten raport zawiera statystyki aktywności związanej z playlistami w stanach USA i Dystrykcie Kolumbii. W tym raporcie w wartości parametru filters uwzględniasz wartość country==US.
Szczegóły miejsca odtwarzania (maksymalnie 25 wyników)
Uwaga: aby korzystać z tego raportu, musisz ustawić parametr maxResults na wartość całkowitą równą 25 lub mniejszą. W odróżnieniu od większości innych raportów ten raport wymaga też podania wartości parametru żądania sort.
Ten raport wskazuje wbudowane odtwarzacze wideo, które wygenerowały najwięcej wyświetleń lub czas oglądania na playlistach właściciela treści.
Ten raport agreguje statystyki oglądania na podstawie sposobu, w jaki widzowie dotarli do treści z playlisty. Na przykład identyfikuje liczbę wyświetleń, które pochodzą z wyszukiwarki Google lub strony kanału.
Uwaga: aby korzystać z tego raportu, musisz ustawić parametr maxResults na wartość całkowitą równą 25 lub mniejszą. W odróżnieniu od większości innych raportów ten raport wymaga też podania wartości parametru żądania sort.
Ten raport agreguje statystyki oglądania na podstawie źródeł, które wygenerowały najwięcej wyświetleń playlist właściciela treści. Odesłania są przypisywane do kategorii według typu źródła wizyty, a definicja wymiaru insightTrafficSourceDetail wskazuje źródła wizyt, dla których jest dostępny raport. Jeśli na przykład ustawisz filtr insightTrafficSourceType na ADVERTISING, raport będzie zawierać listę typów reklam, które wygenerowały najwięcej wyświetleń lub czasu oglądania na playlistach właściciela treści.
Uwaga: ten raport jest obsługiwany tylko w przypadku określonych źródeł ruchu. VIDEO_REMIXES, NOTIFICATION, END_SCREEN, CAMPAIGN_CARD, VIDEO_REMIXES i NO_LINK_EMBEDDED to niektóre z nieobsługiwanych źródeł wizyt.
Typ urządzenia i system operacyjny
Typ urządzenia do playlist
Ten raport agreguje statystyki oglądania na podstawie typu urządzenia, którego widzowie używali do oglądania treści z playlisty. Na przykład identyfikuje liczbę wyświetleń, które miały miejsce na urządzeniach mobilnych lub konsolach do gier.
Ten raport agreguje statystyki oglądania na podstawie systemów operacyjnych widzów. Na przykład identyfikuje liczbę wyświetleń playlist na urządzeniach z Androidem lub na konsolach PlayStation.
System operacyjny i typ urządzenia w przypadku playlist
Ten raport agreguje statystyki oglądania według systemów operacyjnych i typów urządzeń widzów. Na przykład identyfikuje liczbę wyświetleń playlist na tabletach z Androidem lub na komputerach z systemem Windows.
Uwaga: wartości viewerPercentage w tym raporcie nie są normalizowane pod kątem różnych wartości ani kombinacji wartości wymiarów szczegółów odtwarzania (subscribedStatus i youtubeProduct).
Na przykład raport, który używa wymiaru subscribedStatus, zwraca dane viewerPercentage, które sumują się do 100% w przypadku wyświetleń subskrypcji i dane viewerPercentage, które sumują się do 100% w przypadku wyświetleń bez subskrypcji. (łączna wartość wszystkich pól viewerPercentage w raporcie wynosi 200%).
Za pomocą filtrów możesz zadbać o to, aby raport zawierał tylko dane viewerPercentage dla jednej wartości (lub kombinacji wartości) wymiarów szczegółów odtwarzania.
Najpopularniejsze playlisty
Uwaga: aby móc korzystać z tych raportów, musisz ustawić parametr maxResults na wartość całkowitą nie większą niż 200. Dane z okresu przed 1 stycznia 2013 r. są dostępne tylko w przypadku 10 najpopularniejszych playlist. W odróżnieniu od większości innych raportów w przypadku tych raportów musisz też podać wartość parametru żądania sort.
Ten raport zawiera listę najpopularniejszych playlist właściciela treści na podstawie określonych kryteriów filtrowania i sortowania.
Uwaga: raporty skuteczności reklam wymagają tokena autoryzacji, który przyznaje dostęp do zakresu https://www.googleapis.com/auth/yt-analytics-monetary.readonly.
Raporty skuteczności reklam zawierają dane o wyświetleniach reklam, które wyświetlały się podczas odtwarzania filmów. Te dane uwzględniają każde wyświetlenie reklamy, a każde odtworzenie filmu może spowodować kilka wyświetleń.
Dane o skuteczności reklamy na podstawie wyświetleń to:
Ponadto niektóre raporty dotyczące filmów obsługują te dane o skuteczności reklamy na podstawie odtwarzania: Dane te nie są jednak uwzględniane w raportach o skuteczności reklam.
