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ą podzielone na wymiary i dane:

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

    W raporcie każdy wiersz danych zawiera unikalną kombinację wartości wymiarów. Wymiary wybrane do raportu określają sposób, w jaki YouTube oblicza wartości danych w tym raporcie.

  • Dane to poszczególne pomiary związane z aktywnością użytkowników, skutecznością reklam lub szacunkowymi przychodami. Dane o aktywności użytkowników obejmują m.in. liczbę wyświetleń filmu i oceny (pozytywne i negatywne).

Interfejs Analytics API udostępnia parametry filtrowania i sortowania, więc aplikacja wywołująca nie musi natywnie obsługiwać tych funkcji. Interfejs API umożliwia też pobieranie danych dotyczących grup Statystyk YouTube, gdzie grupa to niestandardowa kolekcja zawierająca maksymalnie 500 filmów, playlist, kanałów lub zasobów.

Wybieranie parametrów raportu

Gdy żądasz 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 wszystkie dane w zapytaniu są dostępne w momencie wysłania zapytania.

  • Parametr metrics określa pomiary, które zostaną uwzględnione w raporcie. W raportach dotyczących kanałów dane mierzą aktywność użytkowników i obejmują wartości takie jak wyświetlenia i polubienia. Niektóre dane mierzą też skuteczność reklam lub szacunkowe przychody.

  • Parametr dimensions wyjaśnia, jak będą grupowane dane.

  • Parametr filters wyjaśnia, jak będą filtrowane dane do raportu. Zamiast zwracać wszystkie dane dotyczące kanału, raport może zostać przefiltrowany 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 dla filtrów video, playlist i channel. Jeśli to zrobisz, możesz też uwzględnić ten filtr na liście wymiarów, aby zwrócone dane były również grupowane według filmu, playlisty lub kanału.

Przykładowe opcje raportowania

Załóżmy na przykład, że właściciel kanału chce pobrać raport o typie urządzenia, aby sprawdzić, ile wyświetleń filmów z kanału miało miejsce na urządzeniach mobilnych, konsolach do gier, telewizorach itd.

  • 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 okresu 2 miesięcy.

  • Raport o typach urządzeń obsługuje dane views i estimatedMinutesWatched, więc właściciel kanału ustawia parametr metrics na views,estimatedMinutesWatched.

  • Właściciel kanału ma do wyboru kilka opcji parametru dimensions. Dwa z nich są wymienione na liście poniżej, a trzeci jest omówiony 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 dla całego okresu, który obejmuje raport. Dzięki tej wartości dane do raportu będą odpowiadać na pytania takie jak:

    • Ile razy filmy z kanału zostały wyświetlone na urządzeniach mobilnych w okresie od 1 czerwca do 31 lipca 2015 r.?

    • Ile razy filmy z kanału zostały wyświetlone na konsolach do gier w okresie od 1 czerwca do 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 dla każdego dnia w okresie raportowania. Dzięki tej wartości dane do raportu będą odpowiadać na pytania takie jak:

    • Ile razy filmy z kanału zostały wyświetlone na urządzeniach mobilnych 1 czerwca 2015 r.?

    • Ile razy filmy z kanału zostały wyświetlone na telewizorach 14 lipca 2015 r.?

  • Parametr filters pozwala właścicielowi kanału ograniczyć raport, tak aby zawierał tylko dane pasujące do określonych wartości filtra. Raport obsługuje zbyt wiele opcji filtrowania, aby można było je wszystkie wyjaśnić, więc te przykłady stanowią tylko ułamek raportów, które można wygenerować.

    • Właściciel kanału może przefiltrować żądanie, aby zwrócić wartości tylko dla systemu operacyjnego Android. (Ile wyświetleń miało miejsce na urządzeniach mobilnych z Androidem w okresie raportowania?)

    • Właściciel kanału może przefiltrować żądanie, aby zwrócić wartości tylko dla określonego kraju. (Ile razy filmy były wyświetlane w Kanadzie każdego dnia okresu raportowania?)

    • Właściciel kanału może przefiltrować żądanie, aby zwracało wartości tylko dla konkretnych filmów. Filtr video obsługuje jednak listę wartości rozdzielonych przecinkami, więc raport może zawierać dane dotyczące wielu filmów.

    Jeśli filtr video określa wiele wartości, video 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ą zawierać 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ż interfejs YouTube Analytics API obsługuje zapytania ukierunkowane, 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 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 aktualna liczba wyświetleń, polubień lub komentarzy, użyj metody videos.list interfejsu YouTube Data API zamiast interfejsu YouTube Analytics API.

Pobieranie raportów

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

Listę raportów obsługiwanych przez interfejs API znajdziesz w dokumentacji dotyczącej raportów kanału i raportów właściciela 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 interfejsu YouTube Analytics API powinny zawsze stosować te praktyki:

  • Kolejność kolumn raportu możesz określić na podstawie wiersza nagłówka odpowiedzi. Nie zakładaj na przykład, że wyświetlenia będą pierwszymi danymi zwróconymi 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 interfejsu YouTube Data API, aby pobrać dodatkowe metadane zasobów zidentyfikowanych w odpowiedziach interfejsu YouTube Analytics API. Zgodnie z Zasadami dla deweloperów korzystających z 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.

Wskaźniki agregacji i usunięte elementy

Odpowiedzi YouTube Analytics API nie zawierają zestawień 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. Jednak raporty, które agregują dane dla zestawu zasobów, nadal zawierają 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ą dzienną liczbę wyświetleń wszystkich filmów na kanale w określonym przedziale czasu. Drugi raport zawiera łączną liczbę dziennych wyświetleń w podziale na poszczególne filmy w tym samym okresie.

W takim przypadku liczby w pierwszym raporcie będą obejmować wyświetlenia filmów, które zostały później usunięte, ponieważ pierwszy raport zawiera dane zagregowane dziennie. Jednak drugi raport nie będzie zawierał wyświetleń powiązanych z usuniętymi elementami, ponieważ zawiera on listę wyświetleń poszczególnych filmów. W związku z tym, jeśli w okresie, którego dotyczy raport, z kanału usunięto filmy, łączna dzienna liczba wyświetleń w pierwszym raporcie może być wyższa niż suma dziennych wyświetleń poszczególnych filmów w drugim raporcie.

Anonimizacja danych

Niektóre dane w Statystykach YouTube są ograniczone, gdy nie przekraczają odpowiednich progów. Może się tak zdarzyć w przypadku różnych raportów. W praktyce oznacza to, że raport może nie zawierać części danych lub być całkiem pusty, jeśli:

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

    lub

  2. 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 zbiorczych.

Załóżmy na przykład, że właściciel kanału pobiera 2 raporty. Pierwszy raport zawiera łączną liczbę wyświetleń danego filmu, a drugi – łą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 pokazuje, ż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 może wystąpić 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 (lub że jakiekolwiek wyświetlenia zostały wygenerowane we Francji).

Typy danych z ograniczonym dostępem

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

  • Dane demograficzne, takie jak wiek i płeć.
  • Dane geograficzne, w tym dane i wymiary związane z krajami lub regionami, w których znajdowali się widzowie, takie jak 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, takie jak wyszukiwane słowa lub zewnętrzne adresy URL, które doprowadziły do wyświetleń Twoich filmów. Na przykład wyszukiwane słowa i adresy URL, które prowadzą do bardzo małej liczby wyświetleń, nie pojawią się w raportach, ale nadal będziesz widzieć słowa i adresy URL, które przyciągają do Twoich treści wielu widzów.

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 Google Cloud.