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 służące do agregowania danych, np. 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. Wymiary wybrane w raporcie określają sposób obliczania wartości danych w tym raporcie przez YouTube.

• 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ń filmów i oceny (polubienia i kliknięcia przycisku „To mi się nie podoba”).

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 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 zawiera 5 parametrów, które określają sposób obliczania wartości raportu:

• Parametry startDate i endDate określają okres, którego mają dotyczyć dane w raporcie. Odpowiedź interfejsu API zawiera dane do ostatniego określonego dnia, dla którego w momencie zapytania dostępne są wszystkie wskaźniki w zapytaniu.

• Parametr metrics określa pomiary, które zostaną uwzględnione w raporcie. W raportach o kanałach 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 określa sposób grupowania danych.

• Parametr filters wyjaśnia, jak będą filtrowane dane raportu. Na przykład 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, playlista i kanał. Jeśli to zrobisz, możesz też dodać ten filtr do listy wymiarów, aby zwracane dane były również pogrupowane według filmu, playlisty lub kanału.

Opcje raportowania próbek

Załóżmy na przykład, że właściciel kanału chce pobrać raport dotyczący typu urządzenia, aby określić, 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ęcznego okresu.

• 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. Dwa z nich znajdziesz na poniższej liście, a trzeci omawiamy w dalszej części tej sekcji w wyjaśnieniu wartości parametru filters.

  • 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, którego dotyczy raport. Dzięki tej wartości dane w raporcie pozwolą Ci uzyskać odpowiedzi na pytania takie jak:

    • Ile razy filmy na kanale zostały wyświetlone na urządzeniach mobilnych w okresie od 1 czerwca do 31 lipca 2015 r.?
    • Ile razy filmy na kanale zostały wyświetlone na konsolach do gier między 1 czerwca 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 raportowania. Dzięki tej wartości dane w raporcie pozwolą Ci uzyskać odpowiedzi na pytania takie jak:

    • Ile razy filmy na kanale zostały obejrzane na urządzeniach mobilnych 1 czerwca 2015 r.?
    • Ile razy filmy na kanale zostały wyświetlone na telewizorach 14 lipca 2015 r.?

• 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żesz wygenerować.

  • Właściciel kanału może odfiltrować żądanie, aby zwracało 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 filtrować żądanie, aby zwracać wartości tylko dla określonego kraju. (Ile razy filmy były oglądane w Kanadzie w poszczególne dni okresu raportowania?)

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

    Jeśli filtr video określa wiele wartości, wymiar 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ą zawierać łą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.?)

Pobieranie raportów

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

Listę raportów obsługiwanych przez interfejs API znajdziesz w dokumentacji raportów o kanałach i raportów 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 postępować zgodnie z tymi zasadami:

• Aby określić kolejność kolumn raportu, użyj 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 YouTube Data API, aby pobrać dodatkowe metadane zasobów zidentyfikowanych w odpowiedziach interfejsu 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 interfejsu 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ż wymieniony w odpowiedzi interfejsu API, która zwraca dane dotyczące poszczególnych filmów. Raporty, które zawierają zbiorcze dane dotyczące zestawu zasobów, nadal obejmują 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 łączne dzienne wyświetlenia wszystkich filmów na kanale w określonym przedziale czasu. Drugi raport zawiera łączne dzienne wyświetlenia 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ż wyświetlenia są w nim podawane dla poszczególnych filmów. W efekcie, jeśli w okresie objętym raportem z kanału usunięto filmy, łączna dzienna liczba wyświetleń 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 w Statystykach YouTube są ograniczone, ponieważ nie przekraczają one odpowiednich progów. Może się tak zdarzyć w przypadku różnych raportów. W praktyce oznacza to, że raport może nie zawierać wszystkich danych (lub żadnych danych), 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.

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 wskazuje, że film został wyświetlony 1000 razy. Drugi raport wskazywałby tylko, że w Stanach Zjednoczonych film został wyświetlony 500 razy, a w Kanadzie – 498 razy. W związku z tym może wystąpić różnica między łączną liczbą wyświetleń w tych 2 raportach. Pamiętaj, że drugi raport nie zawierałby żadnej 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.

Ograniczone typy danych

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, np. ich kraje lub regiony. Pamiętaj jednak, że w raportach nie stosuje się progów geograficznych do danych o przychodach.
• Dane dotyczące konkretnych źródeł wizyt, np. haseł wyszukiwania lub zewnętrznych adresów 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ą się pojawiać w raportach. Nadal jednak będziesz widzieć hasła 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 wysłane żądanie API jest liczone jako 1 jednostka limitu wykorzystania interfejsu API. Limity są widoczne w panelu Limity w konsoli interfejsów API Google.