Reports: Query

Важно! Для запросов API к этому методу теперь требуется доступ к области https://www.googleapis.com/auth/youtube.readonly .

Этот метод позволяет получать множество различных отчетов Analytics. В каждом запросе используются параметры запроса для указания идентификатора канала или владельца контента, даты начала, даты окончания и хотя бы одного показателя. Вы также можете предоставить дополнительные параметры запроса, такие как измерения, фильтры и инструкции по сортировке.

  • Метрики — это отдельные измерения активности пользователей, например просмотры видео или оценки (лайки и антипатии).
  • Измерения — это общие критерии, используемые для агрегирования данных, например дата, когда произошло действие пользователя, или страна, в которой находились пользователи. В отчете каждая строка данных имеет уникальную комбинацию значений измерения.
  • Фильтры — это значения измерений, определяющие данные, которые будут получены. Например, вы можете получить данные по определенной стране, конкретному видео или группе видео.

Примечание. Отчеты владельцев контента доступны только контент-партнерам YouTube, участвующим в партнерской программе YouTube .

Распространенные случаи использования

Запрос

HTTP-запрос

GET https://youtubeanalytics.googleapis.com/v2/reports

Все запросы API YouTube Analytics должны быть авторизованы. Руководство по авторизации объясняет, как использовать протокол OAuth 2.0 для получения токенов авторизации.

Запросы YouTube Analytics API используют следующие области авторизации:

Области применения
https://www.googleapis.com/auth/yt-analytics.readonly Просматривайте отчеты YouTube Analytics для вашего контента YouTube. Эта область обеспечивает доступ к показателям активности пользователей, таким как количество просмотров и рейтингов.
https://www.googleapis.com/auth/yt-analytics-monetary.readonly Просматривайте финансовые отчеты YouTube Analytics для вашего контента YouTube. Эта область обеспечивает доступ к показателям активности пользователей, а также к показателям предполагаемого дохода и эффективности рекламы.
https://www.googleapis.com/auth/youtube Управляйте своим аккаунтом YouTube. В API YouTube Analytics владельцы каналов используют эту область для управления группами и элементами групп YouTube Analytics.
https://www.googleapis.com/auth/youtubepartner Просматривайте ресурсы YouTube и связанный с ними контент на YouTube и управляйте ими. В API YouTube Analytics владельцы контента используют эту область для управления группами и элементами групп YouTube Analytics.

Параметры

В следующих таблицах перечислены обязательные и необязательные параметры запроса для запросов API для получения отчетов о запросах. Стандартные параметры запроса, перечисленные в таблице, также являются необязательными и поддерживаются многими API Google.

Параметры
Обязательные параметры
endDate string
Дата окончания получения данных YouTube Analytics . Значение должно быть в формате YYYY-MM-DD .

Ответ API содержит данные до последнего дня, для которого все метрики в запросе доступны на момент запроса. Так, например, если в запросе указана дата окончания 5 июля 2017 г., а значения для всех запрошенных показателей доступны только до 3 июля 2017 г., это будет последняя дата, для которой данные будут включены в ответ. (Это верно, даже если данные по некоторым из запрошенных показателей доступны на 4 июля 2017 г.)
Примечание. В версии 1 API этот параметр назывался end-date .
ids string
Идентифицирует канал YouTube или владельца контента, для которого вы получаете данные YouTube Analytics .

  • Чтобы запросить данные для канала YouTube, установите значение параметра ids либо channel==MINE , либо channel== CHANNEL_ID , где CHANNEL_ID идентифицирует канал YouTube текущего аутентифицированного пользователя.
  • Чтобы запросить данные о владельце контента YouTube, установите для параметра ids значение contentOwner== OWNER_NAME , где OWNER_NAME — это content owner ID для пользователя.

metrics string
Разделенный запятыми список показателей YouTube Analytics , таких как views или likes,dislikes . Список отчетов, которые вы можете получить, и показатели, доступные в каждом отчете, см. в документации по отчетам о каналах или отчетам владельцев контента. (Документ «Метрики» содержит определения всех метрик.)
startDate string
Дата начала получения данных YouTube Analytics . Значение должно быть в формате YYYY-MM-DD .
Примечание. В версии 1 API этот параметр назывался start-date .
Дополнительные параметры
currency string
Валюта, которую API будет использовать для указания следующих показателей предполагаемого дохода: AssessmentRevenue , AssessmentAdRevenue , AssessmentRedPartnerRevenue , GrosRevenue , CPM , PlaybackBasedCpm . Значения, которые API возвращает для этих показателей, представляют собой оценки, рассчитанные с использованием обменных курсов, которые меняются ежедневно. Если ни одна из этих метрик не запрошена, параметр игнорируется.

Значением параметра является трехбуквенный код валюты ISO 4217 из списка валют ниже. API возвращает ошибку, если указана неподдерживаемая валюта. Значение по умолчанию — USD .

dimensions string
Список параметров YouTube Analytics, разделенных запятыми, например video или ageGroup,gender . Список отчетов, которые вы можете получить, и параметры, используемые для этих отчетов, см. в документации по отчетам о каналах или отчетам владельцев контента. (Документ «Измерения» содержит определения для всех измерений.)
filters string
Список фильтров, которые следует применять при получении данных YouTube Analytics . В документации по отчетам о каналах и отчетам владельцев контента указаны параметры, которые можно использовать для фильтрации каждого отчета, а в документе «Измерения» определяются эти измерения.

Если в запросе используется несколько фильтров, соедините их точкой с запятой ( ; ), и возвращаемая таблица результатов будет удовлетворять обоим фильтрам. Например, значение параметра filters video==dMH0bHeiRNg;country==IT ограничивает набор результатов, включив в него данные для данного видео в Италии.

Указание нескольких значений для фильтра

API поддерживает возможность указывать несколько значений для фильтров video , playlist и channel . Для этого укажите отдельный список идентификаторов видео, плейлиста или канала, для которых следует фильтровать ответ API. Например, значение параметра filters video==pd1FJh59zxQ,Zhawgd0REhA;country==IT ограничивает набор результатов, включив в него данные для заданных видео в Италии. Значение параметра может указывать до 500 идентификаторов.

При указании нескольких значений для одного и того же фильтра вы также можете добавить этот фильтр в список измерений, указанный для запроса. Это верно, даже если фильтр не указан в качестве поддерживаемого параметра для конкретного отчета. Если вы добавите фильтр в список измерений, API также будет использовать значения фильтра для группировки результатов.

Например, предположим, что вы получили отчет об источниках трафика канала, в котором собрана статистика просмотров на основе того, каким образом зрители дошли до видеоконтента канала. Также предположим, что запрос параметра filters вашего запроса определяет список из 10 видео, для которых должны быть возвращены данные.
  • Если вы добавите video в значение параметра dimensions , ответ API предоставит отдельную статистику источников трафика для каждого из 10 видео.
  • Если вы не добавите video в значение параметра dimensions , ответ API объединит статистику источников трафика для всех 10 видео.
includeHistoricalChannelData boolean
Примечание. Этот параметр применяется только к отчетам владельцев контента .

Указывает, должен ли ответ API включать время просмотра каналов и данные просмотра за период до того, как каналы были связаны с владельцем контента. Значение параметра по умолчанию — false Это означает, что ответ API включает только время просмотра и данные просмотра за те даты, когда каналы были связаны с владельцем контента.

Важно помнить, что разные каналы могли быть связаны с владельцем контента в разные даты. Если запрос API получает данные для нескольких каналов и значение параметра равно false , то ответ API содержит данные на основе даты связывания для каждого соответствующего канала. Если значение параметра равно true , ответ API содержит данные, соответствующие датам, указанным в запросе API.
Примечание. В версии 1 API этот параметр назывался include-historical-channel-data .
maxResults integer
Максимальное количество строк, включаемых в ответ.
Примечание. В версии 1 API этот параметр назывался max-results .
sort string
Список параметров или показателей, разделенных запятыми, которые определяют порядок сортировки данных YouTube Analytics. По умолчанию порядок сортировки — по возрастанию. Префикс - определяет порядок сортировки по убыванию.
startIndex integer
Индекс первой извлекаемой сущности, отсчитываемый от 1. (Значение по умолчанию — 1 ) Используйте этот параметр в качестве механизма нумерации страниц вместе с параметром max-results .
Примечание. В версии 1 API этот параметр назывался start-index .
Стандартные параметры
access_token Токен OAuth 2.0 для текущего пользователя.
alt Этот параметр не поддерживается в версии 2 API, которая поддерживает только ответы JSON. Формат данных для ответа API.
  • Допустимые значения: json , csv
  • Значение по умолчанию: json
callback Функция обратного звонка.
  • Имя функции обратного вызова JavaScript, которая обрабатывает ответ.
  • Используется в запросах JavaScript JSON-P .
prettyPrint

Возвращает ответ с отступами и разрывами строк.

  • Возвращает ответ в удобочитаемом формате, если true .
  • Значение по умолчанию: true .
  • Если это значение false , это может уменьшить размер полезных данных ответа, что может привести к повышению производительности в некоторых средах.
quotaUser Этот параметр поддерживался в версии 1 API, которая сейчас устарела. Этот параметр не поддерживается в версии 2 API.
userIp Этот параметр поддерживался в версии 1 API, которая сейчас устарела. Этот параметр не поддерживается в версии 2 API.

Тело запроса

Не отправляйте тело запроса при вызове этого метода.

Ответ

Как отмечено в определении параметра alt , API может возвращать ответы в формате JSON или CSV. Информация о теле ответа для каждого типа приведена ниже:

JSON
{
  "kind": "youtubeAnalytics#resultTable",
  "columnHeaders": [
    {
      "name": string,
      "dataType": string,
      "columnType": string
    },
    ... more headers ...
  ],
  "rows": [
    [
      {value}, {value}, ...
    ]
  ]
}
Характеристики
kind string
Это значение указывает тип данных, включенных в ответ API. Для метода query значением свойства kind будет youtubeAnalytics#resultTable . Однако если API добавляет поддержку других методов, ответы API для этих методов могут содержать другие значения свойств kind .
columnHeaders[] list
Это значение указывает информацию о данных, возвращаемых в полях rows . Каждый элемент в списке columnHeaders идентифицирует поле, возвращаемое в значении rows , которое содержит список данных, разделенных запятыми.

Список columnHeaders начинается с измерений, указанных в запросе API, за которыми следуют метрики, указанные в запросе API. Порядок параметров и показателей соответствует порядку в запросе API.

Например, если запрос API содержит параметры dimensions=ageGroup,gender&metrics=viewerPercentage , ответ API возвращает столбцы в следующем порядке: ageGroup , gender , viewerPercentage .
columnHeaders[]. name string
Название параметра или метрики.
columnHeaders[]. columnType string
Тип столбца ( DIMENSION или METRIC ).
columnHeaders[]. dataType string
Тип данных в столбце ( STRING , INTEGER , FLOAT и т. д.).
rows[] list
Список содержит все строки таблицы результатов. Каждый элемент в списке представляет собой массив, содержащий данные, разделенные запятыми, соответствующие одной строке данных. Порядок полей данных, разделенных запятыми, будет соответствовать порядку столбцов, перечисленных в поле columnHeaders .

Если для данного запроса данные недоступны, элемент rows будет исключен из ответа.

Ответ на запрос с измерением day не будет содержать строк за последние дни.

CSV-файл
day, views, likes, ...
"2012-01-01", 12.0, 3, ...
"2012-01-02", 16.0, 2, ...
"2012-01-03", 18.0, 8, ...
...

Примеры

Примечание. Следующие примеры кода могут представлять не все поддерживаемые языки программирования. Список поддерживаемых языков см. в документации клиентских библиотек .

JavaScript

В этом примере вызывается API YouTube Analytics для получения ежедневных просмотров и других показателей для канала авторизующего пользователя за 2017 календарный год. В примере используется клиентская библиотека JavaScript API Google .

Прежде чем запускать этот пример локально в первый раз, вам необходимо настроить учетные данные авторизации для вашего проекта:
  1. Создайте или выберите проект в консоли Google API .
  2. Включите API YouTube Analytics для своего проекта.
  3. В верхней части страницы «Учетные данные» выберите вкладку «Экран согласия OAuth» . Выберите адрес электронной почты, введите название продукта, если оно еще не задано, и нажмите кнопку «Сохранить».
  4. На странице «Учетные данные» нажмите кнопку «Создать учетные данные» и выберите «Идентификатор клиента Oauth» .
  5. Выберите тип приложения Веб-приложение.
  6. В поле Авторизованное происхождение JavaScript введите URL-адрес, с которого вы будете обслуживать пример кода. Например, вы можете использовать что-то вроде http://localhost:8000 или http://yourserver.example.com . Поле «Разрешенные URI перенаправления» можно оставить пустым.
  7. Нажмите кнопку «Создать» , чтобы завершить создание учетных данных.
  8. Прежде чем закрыть диалоговое окно, скопируйте идентификатор клиента, который вам нужно будет поместить в пример кода.

Затем сохраните образец в локальный файл. В примере найдите следующую строку и замените YOUR_CLIENT_ID идентификатором клиента, который вы получили при настройке учетных данных для авторизации.

gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'});

Теперь вы готовы протестировать образец:

  1. Откройте локальный файл в веб-браузере и откройте консоль отладки в браузере. Вы должны увидеть страницу с двумя кнопками.
  2. Нажмите кнопку авторизации и загрузки , чтобы запустить процесс авторизации пользователя. Если вы разрешаете приложению получать данные вашего канала, вы должны увидеть следующие строки, напечатанные на консоли браузера: 
    Sign-in successful
GAPI client loaded for API
  3. Если вместо приведенных выше строк вы видите сообщение об ошибке, подтвердите, что вы загружаете сценарий из URI авторизованного перенаправления, который вы настроили для своего проекта, и что вы вставили свой идентификатор клиента в код, как описано выше.
  4. Нажмите кнопку «Выполнить» , чтобы вызвать API. Вы должны увидеть объект response , выводимый на консоль в браузере. В этом объекте свойство result сопоставляется с объектом, содержащим данные API.
<script src="https://apis.google.com/js/api.js"></script>
<script>
  function authenticate() {
    return gapi.auth2.getAuthInstance()
        .signIn({scope: "https://www.googleapis.com/auth/yt-analytics.readonly"})
        .then(function() { console.log("Sign-in successful"); },
              function(err) { console.error("Error signing in", err); });
  }
  function loadClient() {
    return gapi.client.load("https://youtubeanalytics.googleapis.com/$discovery/rest?version=v2")
        .then(function() { console.log("GAPI client loaded for API"); },
              function(err) { console.error("Error loading GAPI client for API", err); });
  }
  // Make sure the client is loaded and sign-in is complete before calling this method.
  function execute() {
    return gapi.client.youtubeAnalytics.reports.query({
      "ids": "channel==MINE",
      "startDate": "2017-01-01",
      "endDate": "2017-12-31",
      "metrics": "views,estimatedMinutesWatched,averageViewDuration,averageViewPercentage,subscribersGained",
      "dimensions": "day",
      "sort": "day"
    })
        .then(function(response) {
                // Handle the results here (response.result has the parsed body).
                console.log("Response", response);
              },
              function(err) { console.error("Execute error", err); });
  }
  gapi.load("client:auth2", function() {
    gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'});
  });
</script>
<button onclick="authenticate().then(loadClient)">authorize and load</button>
<button onclick="execute()">execute</button>

yt_analytics_v2.html

Питон

В этом примере вызывается API YouTube Analytics для получения ежедневных просмотров и других показателей для канала авторизующего пользователя за 2017 календарный год. В примере используется клиентская библиотека Google API Python .

Прежде чем запускать этот пример локально в первый раз, вам необходимо настроить учетные данные авторизации для вашего проекта:
  1. Создайте или выберите проект в консоли Google API .
  2. Включите API YouTube Analytics для своего проекта.
  3. В верхней части страницы «Учетные данные» выберите вкладку «Экран согласия OAuth» . Выберите адрес электронной почты, введите название продукта, если оно еще не задано, и нажмите кнопку «Сохранить».
  4. На странице «Учетные данные» нажмите кнопку «Создать учетные данные» и выберите «Идентификатор клиента Oauth» .
  5. Выберите тип приложения «Другое» , введите имя «Краткий старт YouTube Analytics API» и нажмите кнопку «Создать».
  6. Нажмите кнопку ОК , чтобы закрыть появившееся диалоговое окно.
  7. Нажмите кнопку (Загрузить JSON) справа от идентификатора клиента.
  8. Переместите загруженный файл в свой рабочий каталог.

Вам также необходимо установить клиентскую библиотеку API Google для Python и некоторые дополнительные библиотеки:

pip install --upgrade google-api-python-client
pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2

Теперь вы готовы протестировать образец:

  1. Скопируйте приведенный ниже пример кода в свой рабочий каталог.
  2. В примере обновите значение переменной CLIENT_SECRETS_FILE , чтобы оно соответствовало расположению файла, который вы скачали после настройки учетных данных для авторизации.
  3. Запустите пример кода в окне терминала: 
    python yt_analytics_v2.py
  4. Пройдите процедуру авторизации. Поток аутентификации может автоматически загружаться в вашем браузере, или вам может потребоваться скопировать URL-адрес аутентификации в окно браузера. В конце процесса авторизации, если необходимо, вставьте код авторизации, отображаемый в браузере, в окно терминала и нажмите [возврат].
  5. Запрос API выполняется, и ответ JSON выводится в окно терминала.
# -*- coding: utf-8 -*-

import os
import google.oauth2.credentials
import google_auth_oauthlib.flow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
from google_auth_oauthlib.flow import InstalledAppFlow

SCOPES = ['https://www.googleapis.com/auth/yt-analytics.readonly']

API_SERVICE_NAME = 'youtubeAnalytics'
API_VERSION = 'v2'
CLIENT_SECRETS_FILE = 'YOUR_CLIENT_SECRET_FILE.json'
def get_service():
  flow = InstalledAppFlow.from_client_secrets_file(CLIENT_SECRETS_FILE, SCOPES)
  credentials = flow.run_console()
  return build(API_SERVICE_NAME, API_VERSION, credentials = credentials)

def execute_api_request(client_library_function, **kwargs):
  response = client_library_function(
    **kwargs
  ).execute()

  print(response)

if __name__ == '__main__':
  # Disable OAuthlib's HTTPs verification when running locally.
  # *DO NOT* leave this option enabled when running in production.
  os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1'

  youtubeAnalytics = get_service()
  execute_api_request(
      youtubeAnalytics.reports().query,
      ids='channel==MINE',
      startDate='2017-01-01',
      endDate='2017-12-31',
      metrics='estimatedMinutesWatched,views,likes,subscribersGained'
      dimensions='day',
      sort='day'
  )

yt_analytics_v2.py

Попробуй это!

Используйте APIs Explorer для вызова этого API и просмотра запроса и ответа API.