Ta strona zawiera listę raportów, które właściciele kanałów mogą pobrać za pomocą interfejsu YouTube Analytics API. Raporty dotyczące kanału zawierają dane o aktywności użytkowników na określonym kanale i obejmują takie wskaźniki jak liczba wyświetleń, ocen i subskrypcji.
Raporty dotyczące filmów zawierają statystyki dotyczące całej aktywności użytkowników związanej z filmami na kanale.
Raporty dotyczące playlist zawierają statystyki dotyczące wyświetleń filmów w kontekście danej playlisty.
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 skuteczności reklam znajdziesz wyjaśnienie 2 typów danych o skuteczności reklam, które obsługuje interfejs API.
Pobieranie raportu
Aby pobrać raport o kanałach, musisz ustawić wartość parametru ids w żądaniu interfejsu API na jedną z tych wartości:
channel==MINE – interfejs API zwraca dane dotyczące kanału YouTube uwierzytelnionego użytkownika.
channel==CHANNEL_ID – ustaw wartość CHANNEL_ID na unikalny identyfikator kanału, z którego pobierasz dane. Użytkownik, który autoryzuje prośbę, musi być właścicielem kanału.
Identyfikator kanału to obecnie ciąg znaków rozpoczynający się od liter UC, ale jego format może ulec zmianie. Identyfikator kanału znajdziesz na stronie zaawansowanych ustawień konta na kanale YouTube lub możesz go pobrać programowo za pomocą metody YouTube Data API'schannels.list.
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 o szacunkowych przychodach i skuteczności reklam nie są obecnie obsługiwane w raportach dotyczących kanałów. W efekcie zakres https://www.googleapis.com/auth/yt-analytics-monetary.readonly nie zapewnia obecnie dostępu do danych finansowych w tych raportach.
Filtry
W tabelach z opisami obsługiwanych raportów znajdziesz informacje o filtrach, których możesz używać w poszczególnych raportach. W tabelach filtry w nawiasach są opcjonalne. Na przykład w przypadku opcji filtrowania video(,country) filtr wideo jest wymagany, a filtr kraj jest opcjonalny.
Interfejs API umożliwia też podawanie wielu wartości dla filtrów video i playlist. 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.
Tabele 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.
Raporty na temat filmów
Statystyki podstawowe
Podstawowe statystyki aktywności użytkowników
Ten raport zawiera statystyki związane z działaniami użytkowników na kanale. Możesz filtrować raport, aby zwracał dane tylko z konkretnego filmu lub kraju.
podstawowe statystyki dotyczące aktywności użytkowników w stanach USA;
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.
Aktywność użytkowników według kraju w określonych okresach
Ten raport zawiera statystyki związane z działaniami użytkowników na kanale 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 związane z aktywnością użytkowników w danym 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.
Ten raport zawiera statystyki dotyczące aktywności użytkowników w poszczególnych krajach. Możesz filtrować raport, aby zwracał tylko dane dotyczące konkretnego filmu.
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ą co najmniej 250. W odróżnieniu od większości innych raportów w tym raporcie musisz też podać wartość parametru żądania sort.
Ten raport zawiera statystyki aktywności użytkowników według miasta.
Ten raport zawiera statystyki aktywności użytkowników według wyznaczonego obszaru rynku (DMA). W tym raporcie:
musisz ustawić wartość parametru filters na country==US lub
przefiltrować dane według konkretnej prowincji (stanu w USA).
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 utworzyć ten raport, musisz ustawić parametr maxResults na wartość całkowitą równą co najmniej 25. 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 filmów na kanale.
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 utworzyć ten raport, musisz ustawić parametr maxResults na wartość całkowitą równą co najmniej 25. 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ądalności na podstawie źródeł zewnętrznych, które wygenerowały najwięcej wyświetleń treści na kanale. 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 czasu oglądania treści na kanale.
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 sposobu, w jaki widzowie dotarli do Twoich filmów. 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ń 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.
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.
Zaangażowanie i udostępnianie treści
Ten raport zawiera statystyki pokazujące, jak często filmy z kanału były udostępniane na różnych platformach społecznościowych.
Ten raport mierzy zdolność filmu do utrzymania uwagi odbiorców, a także pokazuje, jak często oglądane były poszczególne części filmu. Wymiar elapsedVideoTimeRatio mierzy czas trwania filmu dla odpowiednich wartości danych. Dane można podzielić na 2 kategorie:
Utrzymanie uwagi odbiorców
Te dane wskazują, w jakim stopniu film utrzymuje uwagę odbiorców.
audienceWatchRatio to współczynnik porównujący liczbę obejrzeń danego fragmentu filmu do łącznej liczby obejrzeń filmu.
relativeRetentionPerformance pokazuje, jak dobrze film utrzymuje uwagę odbiorców podczas odtwarzania w porównaniu z innymi filmami w YouTube o podobnej długości.
Szczegółowe statystyki oglądania
Te dane dostarczają informacji o tym, jak często oglądane były poszczególne części filmu.
startedWatching wskazuje, jak często widzowie zaczęli oglądać film w danym jego fragmencie.
stoppedWatching wskazuje, jak często widzowie przerywali oglądanie filmu w danym jego fragmencie.
Liczba równoczesnych widzów (w przypadku transmisji na żywo)
Ten raport pokazuje liczbę równoczesnych widzów na danej pozycji w przypadku pojedynczego filmu w ramach transmisji na żywo.
Filtr określa film. Wymiar pozycji zwykle odpowiada 1 minucie.
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 z opcjonalnymi filtrami regionalnymi (maksymalnie 200 wyników)
Ten raport zawiera listę najpopularniejszych filmów na kanale. Raport można filtrować, aby wyświetlić najpopularniejsze filmy według kraja, kontynentu lub subContinent.
Najpopularniejsze filmy według stanu (maksymalnie 200 wyników)
Ten raport zawiera listę najpopularniejszych filmów na kanale w danym 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 na kanale dla widzów, którzy subskrybowali kanał lub anulowali subskrypcję. 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 na kanale i obsługuje szczegóły odtwarzania oraz filtry geograficzne. Ten raport jest podobny do poprzedniego, ale obsługuje mniej danych i dodaje filtr youtubeProduct.
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 związane z interakcjami użytkowników z filmami na playlistach kanału. Możesz filtrować raport, aby zwracał tylko dane dotyczące określonej playlisty.
Ten raport zawiera statystyki związane z interakcjami użytkowników z filmami na playlistach kanału. Możesz filtrować raport, aby zwracał tylko dane dotyczące określonej playlisty.
Ten raport zawiera statystyki aktywności związanej z playlistami w stanach USA i Dystrykcie Kolumbii.
W przypadku tego raportu musisz przefiltrować wyniki, aby zwrócić dane tylko z Stanów Zjednoczonych.
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 czasu oglądania filmów na playlistach kanału.
Ten raport agreguje statystyki oglądania na podstawie tego, jak widzowie dotarli do treści z playlisty.
Na przykład identyfikuje liczbę wyświetleń, które pochodzą z wyszukiwarki Google.
Uwaga: aby korzystać z tego raportu, musisz ustawić parametr maxResults na wartość całkowitą równą co najmniej 25. W odróżnieniu od większości innych raportów w tym raporcie musisz też podać wartość parametru żądania sort.
Ten raport agreguje statystyki oglądania na podstawie źródeł zewnętrznych, które wygenerowały najwięcej wyświetleń filmów na playlistach kanału. Odsyłacze są kategoryzowane według typu źródła wizyt, 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, w raporcie pojawią się typy reklam, które wygenerowały najwięcej wyświetleń lub czasu oglądania w przypadku playlist na kanale.
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 tego, jak widzowie znaleźli filmy na Twoich playlistach. 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ń 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 można sprawdzić, ile wyświetleń miało miejsce na tabletach z Androidem lub komputerach z systemem Windows.
Uwaga: wartości viewerPercentage w tym raporcie nie są normalizowane pod kątem różnych wartości wymiaru szczegółów odtwarzania subscribedStatus.
Na przykład raport, który 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%).
Za pomocą filtrów możesz się upewnić, że raport zawiera tylko dane viewerPercentage dla jednej wartości wymiaru subscribedStatus.
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 na kanale 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.
