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 для получения токенов авторизации.

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

Сферы
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 будет использовать для указания следующих метрик расчетного дохода: предполагаемый доход , предполагаемый доход рекламы , предполагаемый доход RedPartnerRevenue , валовой доход , цена за тысячу показов , воспроизведение на основе цены за тысячу показов . Значения, возвращаемые 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 Console .
  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>

питон

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

Перед первым запуском этого примера локально вам необходимо настроить учетные данные авторизации для вашего проекта:
  1. Создайте или выберите проект в Google API Console .
  2. Включите API YouTube Analytics для своего проекта.
  3. В верхней части страницы учетных данных выберите вкладку экрана согласия OAuth . Выберите адрес электронной почты, введите название продукта, если оно еще не задано, и нажмите кнопку «Сохранить».
  4. На странице Учетные данные нажмите кнопку Создать учетные данные и выберите Идентификатор клиента Oauth .
  5. Выберите тип приложения Другое , введите название «Быстрый запуск API YouTube Analytics» и нажмите кнопку «Создать».
  6. Нажмите OK , чтобы закрыть появившееся диалоговое окно.
  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'
  )

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

Используйте APIs Explorer , чтобы вызвать этот API и просмотреть запрос и ответ API.