Google używa technologii AI do tłumaczenia treści na Twój preferowany język. Tłumaczenia wygenerowane przez AI mogą zawierać błędy.

YouTube Analytics API - Data Model

YouTube Analytics API umożliwia generowanie raportów niestandardowych zawierających dane ze Statystyk YouTube. Interfejs API obsługuje raporty dotyczące kanałów i właścicieli treści. Pola raportu są klasyfikowane jako wymiary lub dane:

Wymiary to typowe kryteria używane do agregowania danych, takie jak data wystąpienia działania lub kraj, w którym znajdowali się użytkownicy.

W raporcie każdy wiersz danych ma unikalną kombinację wartości wymiarów. W związku z tym wymiary wybrane w raporcie określają, jak YouTube oblicza wartości danych w tym raporcie.
Dane to indywidualne pomiary związane z aktywnością użytkowników, skutecznością reklam lub szacowanymi przychodami. Dane dotyczące aktywności użytkowników obejmują takie informacje jak liczba wyświetleń filmu i oceny (polubienia i brak polubień).

Interfejs Analytics API udostępnia parametry filtrowania i sortowania, dzięki czemu aplikacja wywołująca nie musi natywnie obsługiwać tych funkcji. Interfejs API umożliwia też pobieranie danych z grup w Statystykach YouTube. Grupa to niestandardowa kolekcja zawierająca maksymalnie 500 filmów, playlist, kanałów lub zasobów.

Wybieranie parametrów raportu

Gdy wysyłasz żądanie raportu za pomocą metody reports.query interfejsu API, żądanie do interfejsu API zawiera 5 parametrów, które określają sposób obliczania wartości raportu:

Parametry startDate i endDate określają okres, za który raport będzie zawierać dane. Odpowiedź interfejsu API zawiera dane do ostatniego określonego dnia, dla którego w momencie wysyłania zapytania dostępne są wszystkie dane w zapytaniu.
Parametr metrics określa pomiary, które zostaną uwzględnione w raporcie. W raportach dotyczących kanału dane mierzą aktywność użytkowników i obejmują takie wartości jak wyświetlenia i polubienia. Niektóre dane mierzą też skuteczność reklam lub szacowane przychody.
Parametr dimensions wyjaśnia, jak dane będą grupowane.
Parametr filters wyjaśnia, jak dane w raporcie będą filtrowane. Dzięki temu zamiast zwracać wszystkie dane dotyczące kanału, raport może być filtrowany tak, aby zawierał tylko dane dotyczące określonego kraju, filmu lub grupy filmów.

Uwaga: interfejs API umożliwia określenie wielu wartości filtrów filmów, playlist i kanałów. Jeśli to zrobisz, możesz też uwzględnić ten filtr na liście wymiarów, aby zwracane dane były też grupowane według filmu, playlisty lub kanału.

Przykładowe opcje raportowania

Załóżmy, że właściciel kanału chce pobrać raport dotyczący typu urządzenia, aby sprawdzić, ile wyświetleń filmów na kanale miało miejsce na urządzeniach mobilnych, konsolach do gier, telewizorach itp.

Właściciel kanału ustawia parametr startDate na 2015-06-01, a parametr endDate na 2015-07-31. Na podstawie tych wartości raport będzie zawierać dane z 2 miesięcy.
Raport dotyczący typu urządzenia obsługuje dane views i estimatedMinutesWatched, więc właściciel kanału ustawia parametr metrics na views,estimatedMinutesWatched.
W przypadku parametru dimensions właściciel kanału ma kilka opcji. 2 z nich są widoczne na poniższej liście, a trzecia jest omówiona w wyjaśnieniu wartości parametru filters w dalszej części tej sekcji.
- Ustawienie wartości parametru na deviceType oznacza, że liczba wyświetleń i czas oglądania będą grupowane według typu urządzenia w całym okresie objętym raportem. Dzięki tej wartości dane w raporcie odpowiedzą na pytania takie jak:
  - Ile razy filmy na kanale zostały wyświetlone na urządzeniach mobilnych między 1 czerwca 2015 r. a 31 lipca 2015 r.?
  - Ile razy filmy na kanale zostały wyświetlone na konsolach do gier między 1 czerwca 2015 r. a 31 lipca 2015 r.?
  Raport będzie zawierać łączną liczbę wyświetleń i czas oglądania dla każdego typu urządzenia.
- Ustawienie wartości parametru na day,deviceType oznacza, że liczba wyświetleń i czas oglądania będą obliczane według typu urządzenia w każdym dniu okresu objętego raportem. Dzięki tej wartości dane w raporcie odpowiedzą na pytania takie jak:
  - Ile razy filmy na kanale zostały wyświetlone na urządzeniach mobilnych 1 czerwca 2015 r.?
  - Ile razy filmy na kanale zostały wyświetlone na telewizorach 14 lipca 2015 r.?
Na koniec parametr filters umożliwia właścicielowi kanału ograniczenie raportu tak, aby zawierał tylko dane pasujące do określonych wartości filtra. Raport obsługuje zbyt wiele opcji filtrowania, aby je wszystkie wyjaśnić, więc te przykłady stanowią tylko niewielką część raportów, które można wygenerować.
- Właściciel kanału może odfiltrować żądanie tak, aby zwracało wartości tylko dla systemu operacyjnego Android. (Ile wyświetleń miało miejsce na urządzeniach mobilnych z Androidem w okresie objętym raportem?)
- Właściciel kanału może odfiltrować żądanie tak, aby zwracało wartości tylko dla określonego kraju. (Ile razy filmy zostały wyświetlone w Kanadzie w każdym dniu okresu objętego raportem?)
- Właściciel kanału może odfiltrować żądanie tak, aby zwracało wartości tylko dla określonych filmów. Filtr filmów obsługuje jednak listę wartości rozdzielonych przecinkami, więc raport może zawierać dane dotyczące wielu filmów.
  
  Jeśli filtr filmów określa wiele wartości, film można też określić jako wymiar. Oznacza to, że parametr dimensions obsługuje też wartości deviceType,video i day,deviceType,video.
  - Jeśli właściciel kanału uwzględni film na liście wymiarów, dane będą określać poszczególne wartości dla każdego filmu. (Ile razy film XYZ został wyświetlony na konsoli do gier 1 czerwca 2015 r.?
  - Jeśli właściciel kanału nie uwzględni filmu na liście wymiarów, dane będą określać łączne wartości obejmujące wszystkie określone filmy. (Ile razy filmy ABC, DEF i XYZ zostały wyświetlone na konsoli do gier 1 czerwca 2015 r.?

Częstotliwość aktualizacji danych i opóźnienie

Chociaż YouTube Analytics API obsługuje zapytania ukierunkowane, podstawowe dane analityczne nie są dostępne w czasie rzeczywistym. Przetwarzanie danych zwykle powoduje opóźnienie wynoszące od 48 do 72 godzin. Dlatego odpowiedzi interfejsu API nie zawierają danych z ostatnich dni, a parametr endDate raportu obejmuje tylko dane do ostatniego dnia, dla którego wszystkie żądane dane zostały w pełni przetworzone.

Ze względu na opóźnienie danych możesz zauważyć rozbieżności między danymi zwracanymi przez interfejs API a danymi w czasie rzeczywistym widocznymi w YouTube Studio. Jeśli Twoja aplikacja wymaga statystyk w czasie rzeczywistym dotyczących poszczególnych filmów, takich jak bieżąca liczba wyświetleń, polubień lub komentarzy, zamiast YouTube Analytics API użyj metody videos.list interfejsu YouTube Data API.

Pobieranie raportów

Aby pobrać raport, wyślij autoryzowane żądanie GET do metody reports.query interfejsu API, określając parametry definiujące raport, który chcesz pobrać.

Listę raportów obsługiwanych przez interfejs API znajdziesz w dokumentacji raportów dotyczących kanałów i raportów dotyczących właścicieli treści. Każda definicja raportu określa wartości, które raport dopuszcza w przypadku parametrów metrics, dimensions i filters.

Sprawdzone metody

Aplikacje korzystające z YouTube Analytics API powinny zawsze stosować się do tych zasad:

Używaj wiersza nagłówka odpowiedzi, aby określić kolejność kolumn raportu. Nie zakładaj na przykład, że wyświetlenia będą pierwszymi danymi zwracanymi w odpowiedzi tylko dlatego, że są pierwszymi danymi wymienionymi w opisie raportu. Zamiast tego użyj wiersza nagłówka odpowiedzi, aby określić, która kolumna zawiera te dane.
Użyj YouTube Data API, aby pobrać dodatkowe metadane zasobów zidentyfikowanych w odpowiedziach YouTube Analytics API. Zgodnie z zasadami dla deweloperów usług YouTube API (sekcje III.E.4.b–III.E.4.d) klienci API muszą usunąć lub odświeżyć przechowywane metadane zasobów z tego interfejsu API po 30 dniach.

Dane zbiorcze i usunięte elementy

Odpowiedzi YouTube Analytics API nie zawierają podziału danych dotyczących usuniętych elementów. Jeśli na przykład właściciel kanału usunie film, nie będzie on już widoczny w odpowiedzi interfejsu API, która zwraca dane dotyczące poszczególnych filmów. Raporty, które agregują dane dotyczące zestawu zasobów, nadal zawierają jednak dane powiązane z usuniętymi elementami.

Załóżmy na przykład, że właściciel kanału pobiera 2 raporty. Pierwszy raport zawiera łączną liczbę wyświetleń dziennie wszystkich filmów na kanale w określonym okresie. Drugi raport zawiera łączną liczbę wyświetleń dziennie dla poszczególnych filmów w tym samym okresie.

W tym przypadku liczby w pierwszym raporcie będą obejmować wyświetlenia filmów, które zostały później usunięte, ponieważ pierwszy raport zawiera dzienne dane zbiorcze. Drugi raport nie będzie jednak zawierać wyświetleń powiązanych z usuniętymi elementami, ponieważ drugi raport zawiera wyświetlenia dla poszczególnych filmów. W związku z tym, jeśli kanał usunął filmy w okresie objętym raportem, łączna liczba wyświetleń dziennie podana w pierwszym raporcie może być wyższa niż suma dziennych liczb wyświetleń poszczególnych filmów w drugim raporcie.

Anonimizacja danych

Niektóre dane ze Statystyk YouTube są ograniczone, gdy dane nie osiągną określonego progu. Może się to zdarzyć w różnych raportach. W praktyce oznacza to, że raport może nie zawierać wszystkich (lub żadnych) Twoich danych, jeśli:

film lub kanał ma ograniczony ruch w określonym okresie,

lub
wybrano filtr lub wymiar, np. źródło wizyt lub kraj, w przypadku których wartości nie osiągnęły określonego progu.

W przypadku ograniczonych danych podsumowania w różnych raportach mogą się różnić w zależności od sposobu zbierania danych.

Załóżmy na przykład, że właściciel kanału pobiera 2 raporty. Pierwszy raport zawiera łączną liczbę wyświetleń określonego filmu, a drugi raport zawiera łączną liczbę wyświetleń tego filmu w poszczególnych krajach. W wybranym okresie film został wyświetlony 1000 razy, gdzie 500 wyświetleń miało miejsce w Stanach Zjednoczonych, 498 w Kanadzie, a 2 – we Francji.

W tym przykładzie pierwszy raport wskazywałby, że film został wyświetlony 1000 razy. Drugi raport wskazywałby tylko, że film został wyświetlony 500 razy w Stanach Zjednoczonych i 498 razy w Kanadzie. W związku z tym wystąpiłaby różnica między łączną liczbą wyświetleń w obu raportach. Pamiętaj, że drugi raport nie zawierałby żadnych informacji o tym, że miały miejsce jeszcze 2 wyświetlenia (ani że jakiekolwiek wyświetlenia zostały wygenerowane we Francji).

Rzeczywiste wartości progów ograniczenia danych nie są publikowane i mogą ulec zmianie według uznania YouTube.

Typy ograniczonych danych

W raportach Statystyk YouTube mogą być ograniczone te dane:

Dane demograficzne, takie jak wiek i płeć.
Dane geograficzne, w tym dane lub wymiary związane z krajami lub regionami, w których znajdowali się widzowie, np. ich kraje lub regiony. Pamiętaj jednak, że raporty nie stosują progów geograficznych do danych o przychodach.
Dane związane z konkretnymi źródłami wizyt, takimi jak wyszukiwane hasła lub zewnętrzne adresy URL, które doprowadziły do wyświetleń Twoich filmów. Na przykład wyszukiwane hasła i adresy URL, które generują bardzo małą liczbę wyświetleń, nie będą widoczne w raportach, ale nadal będziesz widzieć hasła i adresy URL, które przyciągają wielu widzów do Twoich treści.

Więcej informacji o ograniczonych danych w raportach Statystyk YouTube znajdziesz w Centrum pomocy YouTube.

Wykorzystanie limitu

Każde żądanie do interfejsu API jest liczone jako 1 jednostka limitu wykorzystania interfejsu API. Limity są widoczne w panelu Limity w Konsoli interfejsów API Google.