YouTube Analytics API - Data Model

Interfejs API YouTube Analytics umożliwia generowanie raportów niestandardowych zawierających dane YouTube Analytics. Interfejs API obsługuje raporty dotyczące kanałów i właścicieli treści. Pola raportu dzielą się na wymiary lub dane:

  • Wymiary to typowe kryteria używane do agregowania danych, takie jak data wystąpienia działania lub kraj zamieszkania użytkowników.

    W każdym wierszu danych w raporcie występuje unikalna kombinacja wartości wymiaru. W związku z tym wymiary wybrane w raporcie określają sposób obliczania wartości przez YouTube w danych w tym raporcie.

  • Dane to indywidualne pomiary dotyczące aktywności użytkowników, skuteczności reklam i szacunkowych przychodów. Dane dotyczące aktywności użytkowników obejmują liczbę wyświetleń filmów i oceny (oceny pozytywne i negatywne).

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 także pobieranie danych dotyczących grup w YouTube Analytics, w których znajduje się niestandardowa kolekcja zawierająca maksymalnie 500 filmów, playlist, kanałów lub zasobów.

Wybieranie parametrów raportu

Gdy zgłaszasz raport za pomocą metody API reports.query, żądanie to zawiera 5 parametrów, które określają sposób obliczania wartości raportu:

  • Parametry startDate i endDate określają okres, przez jaki raport będzie zawierał dane. Odpowiedź interfejsu API zawiera dane aż do ostatniego dnia, dla którego wszystkie dane zapytania są dostępne w momencie wysyłania zapytania.

  • Parametr metrics określa pomiary, które zostaną uwzględnione w raporcie. W raportach dotyczących kanałów dane przedstawiają aktywność użytkowników i zawierają takie wartości jak wyświetlenia i polubienia. Niektóre dane służą również do pomiaru skuteczności reklam lub szacunkowych przychodów.

  • Parametr dimensions wyjaśnia sposób grupowania danych.

  • Parametr filters wyjaśnia sposób filtrowania danych w raporcie. Na przykład zamiast zwracać wszystkie dane dotyczące kanału, można przefiltrować raport, aby zawierał on dane dotyczące tylko danego kraju, filmu lub grupy filmów.

    Uwaga: interfejs API umożliwia określenie wielu wartości filtrów filmów, playlist i kanałów. W takim przypadku możesz też dodać ten filtr do listy wymiarów, aby zwracane dane były też pogrupowane według filmu, playlisty lub kanału.

Przykładowe opcje raportowania

Załóżmy, że właściciel kanału chce pobrać raport o typie urządzenia wideo, by ustalić, ile wyświetleń filmów pochodzi z urządzeń mobilnych, konsol do gier, telewizorów 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 2 miesięcy.

  • Raport dotyczący typu urządzenia obsługuje dane obejrzenia 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 są widoczne na poniższej liście, a trzeci został omówiony w objaśnieniu wartości parametru filters znajdującym się w dalszej części tej sekcji.

    • Ustawienie wartości 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. Przy tej wartości dane raportu będą odpowiadać na pytania takie jak:

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

      Raport będzie zawierał całkowitą liczbę wyświetleń i czas oglądania dla każdego typu urządzenia.

    • Ustawienie wartości parametru day,deviceType oznacza, że w danym okresie liczby wyświetleń i czas oglądania będą obliczane według typu urządzenia. Przy tej wartości dane raportu będą odpowiadać na pytania takie jak:

      • Ile razy filmy z tego kanału były wyświetlane na urządzeniach mobilnych 1 czerwca 2015 r.?
      • Ile razy filmy z tego kanału były oglądane w telewizji 14 lipca 2015 r.?

  • Parametr filters pozwala właścicielowi kanału ograniczyć raport tylko do danych pasujących do określonych wartości filtrów. Raport obsługuje zbyt wiele opcji filtrowania, aby można było je wszystkie wyjaśnić, więc te przykłady to tylko część raportów, które możesz wygenerować.

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

    • Właściciel kanału może odfiltrować żądanie, aby zobaczyć wartości tylko dla danego kraju. (Ile razy filmy były oglądane w Kanadzie każdego dnia w okresie raportowania?)

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

      Jeśli filtr wideo zawiera wiele wartości, jako wymiar możesz też podać film. Oznacza to, że parametr dimensions obsługuje też wartości deviceType,video i day,deviceType,video.

      • Jeśli właściciel kanału umieści na liście wymiarów film, te dane będą określać indywidualne wartości dla każdego filmu. (Ile razy film XYZ był wyświetlany w konsoli do gier 1 czerwca 2015 r.?)
      • Jeśli właściciel kanału nie umieścił filmu na liście wymiarów, w danych znajdują się łączne wartości dla wszystkich określonych filmów. (Ile razy filmy ABC, DEF i XYZ były wyświetlane w konsoli do gier 1 czerwca 2015 r.?)

Pobieram raporty

Aby pobrać raport, wyślij autoryzowane żądanie GET do metody reports.query interfejsu API, określają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 oraz właścicieli treści. Każda definicja raportu wskazuje wartości, na które zezwala raport dla parametrów metrics, dimensions i filters.

Sprawdzone metody

Aplikacje, które korzystają z interfejsu YouTube Analytics API, zawsze powinni stosować te metody:

  • Aby określić kolejność kolumn raportu, użyj wiersza nagłówka odpowiedzi. Na przykład nie zakładaj, że wyświetlenia będą pierwszymi danymi zwracanymi w odpowiedzi tylko dlatego, że są to pierwsze dane wymienione w opisie raportu. Aby określić, która kolumna zawiera te dane, skorzystaj z wiersza nagłówka odpowiedzi.
  • Jeśli chcesz pobrać dodatkowe metadane zasobów wykrytych w odpowiedziach YouTube Analytics API, użyj interfejsu YouTube Data API. Zgodnie z zasadami dla deweloperów dotyczącymi usług interfejsu API YouTube (sekcje III.E.4.b do III.E.4.d) klienty interfejsu API muszą usuwać lub odświeżać zapisane metadane zasobów z tego interfejsu API po 30 dniach.

Zbiorcze dane i usunięte elementy

Odpowiedzi YouTube Analytics API nie zawierają zestawienia danych usuniętych elementów. Jeśli na przykład właściciel kanału usunie film, film nie będzie już wyświetlany w odpowiedzi interfejsu API, która zwraca dane dla każdego filmu osobno. Jednak raporty zbiorcze zawierające dane dotyczące danego zasobu 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 danym kanale w danym okresie. Drugi raport przedstawia łączną dzienną liczbę wyświetleń poszczególnych filmów w tym samym okresie.

W tym przypadku liczby w pierwszym raporcie obejmują wyświetlenia filmów, które zostały później usunięte, ponieważ pierwszy raport zawiera dane zbiorcze. Drugi raport nie obejmuje jednak wyświetleń powiązanych z usuniętymi elementami, ponieważ zawiera on szczegółowe informacje na temat wyświetleń filmów. W efekcie, jeśli w okresie objętym raportem kanał usunie filmy, łączna liczba dziennych wyświetleń w pierwszym raporcie może być wyższa niż suma dziennych wyświetleń konkretnego filmu.

Anonimizacja danych

Niektóre dane w Statystykach YouTube są ograniczone, gdy 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) danych, jeśli:

  1. filmy lub kanały mają ograniczony ruch we wskazanym okresie,

    lub to

  2. Wybrany filtr lub wymiar, takie jak źródło wizyt lub kraj, dla których wartości nie osiągnęły określonego progu,

Jeśli dane są ograniczone, łączne wartości podawane w różnych raportach mogą się różnić w zależności od sposobu ich zbiorczych danych.

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

W tym przykładzie pierwszy raport wskazuje, że film został obejrzany 1000 razy. Drugi raport wskazuje tylko na to, że film został obejrzany 500 razy w Stanach Zjednoczonych i 498 razy w Kanadzie. W tych przypadkach różni się łączna liczba wyświetleń w obu raportach. Drugi raport nie będzie zawierał informacji o 2 innych wyświetleniach (lub o wyświetleniach we Francji).

Faktyczne wartości progowe, w przypadku których dane są ograniczone, nie są publikowane i mogą ulec zmianie według uznania YouTube.

Ograniczone typy danych

Te dane mogą być ograniczone w raportach w Statystykach YouTube:

  • Dane demograficzne, takie jak wiek i płeć.
  • Dane geograficzne, w tym dane lub wymiary związane z krajami lub regionami, w których znajdowały się widzowie, np. ich kraje lub regiony. Pamiętaj jednak, że w tych raportach nie stosuje się progów geograficznych.
  • Dane dotyczące konkretnych źródeł wizyt, takie 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 prowadzące do niewielkiej liczby wyświetleń nie będą widoczne w raportach, jednak będą one uwzględniać wyszukiwane hasła i adresy URL, które przyciągają wielu widzów do Twoich treści.

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

Wykorzystanie limitu

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