API ВКонтакте используют не только для сбора статистики, но и для отложенного постинга, отправки сообщений. Мы с командой активно применяем его для автоматизации отчетности по SMM и таргету. Поэтому поговорим про сценарии использования, когда нужно получить статистику из ВКонтакте для обработки в других системах. Кратко расскажем, как в целом работает API, поделимся методами, которыми пользуемся сами. В конце пройдемся по сложностям, от которых зависит результат.
Когда и зачем нужно выгружать данные из ВК
Данные из ВКонтакте выгружают, чтобы обрабатывать, производить операции и расчеты с ними, анализировать дальше в других системах и сервисах. Мы экспортируем статистику сообществ и рекламных кабинетов в свои базы данных и дальше:
рассчитываем дополнительные показатели – вовлеченность, активное ядро аудитории, лучшие день и время постинга и т. д.;
упаковываем в динамические дашборды;
импортируем в другие инструменты обработки данных и BI-системы – Excel, Google Data Studio, Power BI, Google Таблицы.
1: Шаблон отчета по ВКонтакте для Google Data Studio в сервисе DataFan, в который можно автоматически импортировать данные через официальный API
Если разберетесь в методах и объектах и научитесь работать с API ВКонтакте, вы как разработчик сможете написать свои скрипты и выгружать данные напрямую в сторонние сервисы обработки данных вроде Google Data Studio. Или же тянуть статистику в собственный аналитический инструмент.
Зная принципы и правила работы с API, вы сможете получать актуальные данные через формы на страницах каждого метода на платформе ВКонтакте для разработчиков.
Для этого:
Зайдите в раздел API платформы ВК для разработчиков.
2: Здесь можно почитать подробные инструкции по работе с API
В списке методов найдите нужный – в зависимости от того, какие данные вы хотите получить. Например, stories.get собирает активные Истории конкретного пользователя или сообщества.
3: Находим нужный метод API ВКонтакте
Проскрольте до блока «Пример запроса» внизу страницы, введите параметры в форму и нажмите «Выполнить».
4: Полученный код можно скопировать кликом по иконке в правом верхнем углу
Теперь разберемся, как работает API ВКонтакте, а потом подробнее рассмотрим несколько методов, которые чаще всего используются для экспорта статистики.
Общий принцип работы API ВКонтакте
В целом API VK работает так же, как и любой другой API:
→ мы (клиент) авторизуемся в интерфейсе API;
→ отправляем запрос к системе в виде предусмотренных разработчиками методов;
→ API «объясняет» системе, чего мы от нее хотим;
→ система через API в заданном формате возвращает результат, с которым можно дальше работать.
5: Схематично это можно изобразить так
Метод в понятном для системы формате передает информацию о том, что мы хотим от нее получить и в каком виде. Например, для получения статистики мы используем метод stats.get и в параметрах указываем, что хотим получить цифры:
для конкретного сообщества или приложения;
за определенные периоды времени;
по конкретным показателям – количеству посетителей, охвату, активности и т. д.
Как мы говорили выше, единоразово все это можно выгрузить через форму на странице метода платформы для разработчиков. Однако нас такой способ не устраивает. Нам важен постоянный доступ к актуальной статистике, представленной в виде наглядных сводок, схем и графиков, которыми можно поделиться с клиентом.
Чтобы регулярно выгружать данные и импортировать в нужные инструменты, мы написали свой клиент для API ВКонтакте, в котором учли лимиты системы по количеству запросов и необходимые паузы между ними. Через него отправляются запросы к базе данных и возвращаются читаемые данные.
Когда новое сообщество или рекламный кабинет подключается к клиенту, первые данные собираются за 1,5 года, в дальнейшем при обновлении данных – за последние несколько дней. Поэтому в рамках одного запроса мы не запрашиваем полную информацию за все время – ограничиваем период статистики конкретными датами. Этот способ оптимален, так как показатели выгружаются регулярно. Он помогает снизить нагрузку и соблюдать лимиты API.
После экспорта статистики из ВКонтакте мы работаем с ней дальше: обрабатываем, переводим в нужные форматы, вычисляем дополнительные показатели, приводим в удобный для анализа вид.
Какие методы используем
Расскажем про ключевые методы, которые мы используем для экспорта статистики из ВКонтакте.
Собираем посты со стены сообщества
Метод wall.get возвращает список постов, которые были опубликованы в группе, и сами записи.
Для получения данных нужно указать параметры:
ID сообщества – owner_id;
короткий адрес группы – domain;
количество публикаций, которые нужно выгрузить – count.
Также здесь можно указать тип постов, которые мы хотим выгрузить:
предложенные;
отложенные;
от имени сообщества;
от имени других пользователей или все.
В результате мы получаем количество выгруженных постов и массив объектов, записей на стене сообщества, с подробными данными по каждому: количеством комментариев, лайков, репостов, просмотров и т. д.
Через этот метод API отдает посты с сортировкой по дате от новых к старым, и возможности выгрузить записи за определенный период нет. Поэтому мы выгружаем «постранично» по 50 постов, пока не выйдем за пределы временного интервала или пока не кончатся все записи.
Собираем активные Истории
Метод stories.get собирает Истории пользователя или сообщества, активные на момент отправки запроса.
Для выгрузки указываются параметры:
ID сообщества – owner_id;
данные, которые мы хотим получить – fields.
На выходе получаем количество активных Историй и массив объектов с самими публикациями. В зависимости от того, что прописали в параметре fields, по каждой Истории собираются ID, тип (фото или видео), число просмотров и ответов на нее.
Собираем статистику по Историям
Метод stories.getStats возвращает статистику по Истории, ID которой мы передаем в API в рамках запроса.
Для этого нужно сформировать параметры:
ID владельца Истории (пользователя или сообщества) – owner_id;
ID самой публикации – story_id.
В результате получаем данные по просмотрам, ответам на Историю, расшариваниям, новым подписчикам, переходам по ссылке, ответам в сообщениях, скрытиям.
Собираем информацию о подписчиках
Метод users.get возвращает расширенную информацию о пользователях, идентификаторы или короткие имена которых мы указали в запросе.
Параметры:
ID или короткие имена пользователей, информацию о которых надо собрать – user_ids или screen_name;
список полей профилей, из которых нужны данные – fields;
падеж для склонения имени и фамилии пользователя – name_case.
На выходе получаем массив объектов пользователей с информацией о них. Набор полей зависит от того, что мы прописали в параметрах запроса. С помощью users.get можно собрать имена, фамилии и даты рождения, данные из разделов страницы «О себе», «Деятельность», «Карьера», количество друзей, фотоальбомов, видеозаписей и т. д.
Мы с помощью этого запроса решаем 2 задачи:
вытягиваем фамилию и имя, чтобы отобразить их при подключении пабликов и рекламных кабинетов;
получаем часовой пояс пользователя, чтобы давать в отчетах корректные рекомендации по лучшему времени постинга.
Вытягиваем данные по видеозаписям
Метод video.get возвращает информацию о видеозаписях, которые принадлежат заданному в параметрах запроса пользователю.
Предусмотренные параметры:
ID владельца видео – owner_id;
ID видеозаписей – videos;
ID альбома, видео из которого надо вытянуть – album_id;
количество выгружаемых роликов – count;
поля с информацией и показателями, которые нужно вытянуть – fields.
Метод возвращает количество видеозаписей и массив роликов с количеством комментариев, просмотров, лайков, зрителей прямой трансляции, репостов и другими показателями по каждому.
Выгружаем комментарии к видеозаписям
Метод video.getComments позволяет выгрузить список комментариев к конкретному ролику, идентификатор которого мы указали в запросе.
Параметры:
ID пользователя или сообщества – owner_id;
ID видео – video_id;
необходимость выгружать данные по лайкам к комментариям – need_likes;
ID комментария, начиная с которого нужно выгружать данные – start_comment_id;
количество выгружаемых комментариев – count;
порядок сортировки – sort.
В результате получаем количество и массив с комментариями и дополнительными данными по ним.
Собираем данные по фотографиям
Метод photos.get экспортирует список фотографий альбома, который мы указали в запросе.
Параметры:
ID владельца альбома – owner_id;
ID альбома – album_id;
ID фотографий, данные по которым нужно выгрузить – photo_ids;
порядок сортировки фотографий – rev;
необходимость выгружать дополнительную информацию: лайки, комментарии, репосты – extended;
количество фотографий, которые нужно собрать – count.
В результате получаем количество и массив с фотографиями и данными по каждой: количеством лайков, комментариев, репостов.
Экспортируем комментарии к фотографиям
Метод photos.getComments собирает комментарии к фотографии, указанной в запросе.
Параметры:
ID владельца фотографии – owner_id;
ID фотографии, данные о которой надо вытянуть – photo_id;
необходимость выгружать лайки к комментариям – need_likes;
ID комментария, начиная с которого нужно экспортировать данные – start_comment_id;
количество выгружаемых комментариев – count;
порядок сортировки – sort;
дополнительная информация о пользователях, оставлявших комментарии, которую нужно выгрузить: ФИО, «О себе», гео и т. д. – fields.
На выходе получаем количество и массив комментариев с дополнительной информацией по ним. В зависимости от параметров запроса это могут быть количество лайков, массивы пользователей и сообществ с данными по ним, которые мы запрашивали через параметр fields.
Выгружаем статистику сообщества
Метод stats.get позволяет экспортировать статистику сообщества или приложения.
Параметры:
ID сообщества – group_id;
начальная и конечная даты выводимой статистики – date_from и date_to;
начало и окончание периода статистики – timestamp_from и timestamp_to;
конкретные блоки статистики, которые нужно вытянуть – stats_groups.
В результате получаем показатели сообщества за указанный период: количество подписок и отписок, позитивных и негативных действий и реакций, число просмотров и посетителей, охват.
Объединяем несколько методов в один запрос
Метод execute универсален – он позволяет запускать последовательность других методов, чтобы сохранить и отфильтровать промежуточные результаты. Также мы активно используем его, чтобы собрать данные по нескольким постам, Историям или видео в рамках одного запроса. Это помогает укладываться в ограничения API – если бы мы отправляли отдельные запросы по каждой Истории, собирать такое количество данных в единицу времени было бы невозможно, приходилось бы делать перерывы.
Параметры зависят от конкретных методов, которые мы используем в рамках запроса. Для формирования можно использовать арифметические и логические операции, конструкцию if, поиск в массиве или строке и т. д.
На выходе получаем данные, которые запрашивали через методы, использованные в алгоритме.
6: Пример execute-запроса из официальной справки по API
Пример: как получить статистику по Историям
Рассмотрим выгрузку данных через официальный API ВКонтакте на примере конкретной задачи. Предположим, нам надо вытянуть статистику по Историям сообщества и настроить регулярную выгрузку показателей.
Чтобы обновить собранную статистику по Историям, нам приходится собирать ID всех публикаций за последние 2 дня в нашей базе данных и отдельным запросом execute(stores.getStats) вытягивать по ним финальную статистику.
Такое происходит, потому что по запросу stories.get ВКонтакте отдает только активные на данный момент Истории. Мы обновляем набор данных не каждую секунду. Может быть ситуация, когда публикация завершилась, а мы не выгрузили по ней финальную статистику. Потому что мы не можем собирать данные в последнюю секунду существования Истории. Чтобы решить эту проблему, собираем ID. Так мы можем получить статистику, даже если История уже завершилась – с помощью метода execute(stores.getStats).
А вот и фрагмент кода, который нужен, чтобы:
получить из API ВКонтакте Истории сообщества;
проверить, что они входят в нужный временной промежуток;
сформировать массив с данными для execute-запроса по статистике для этих публикаций.
def get_stories(self, group_id, group_cash, user_tz_offset):
executed_batch_for_story_stats = list()
stories_stats = dict()
stories_data = {
'owner_id': group_id * -1,
'extended': 0
}
group_stories_response = self.vk_client_stories.post('stories.get', **stories_data)
group_stories = group_stories_response.get('items', [])
if len(group_stories) > 0:
if type(group_stories[0]) == list:
group_stories = group_stories[0]
for story in group_stories:
story_date_datetime = timestamp_to_datetime(story['date'])
if story_date_datetime < self.start_datetime:
continue
story_key = self.make_story_key(self.format_key('story', story))
executed_batch_for_story_stats.append(self._prepare_execute_code_for_story_data(
group_id=group_id,
story_id=story['id'],
story_key=story_key,
))
story.pop('views')
stories_stats[story_key] = story
self.stories = self._collect_story_stats(
batch=executed_batch_for_story_stats
)
Например, проверить, входят ли отобранные Истории в нужный интервал, позволяет этот фрагмент:
story_date_datetime = timestamp_to_datetime(story['date'])
if story_date_datetime < self.start_datetime:
continue
Далее нам нужно правильно сформировать параметры для запроса execute(stores.getStats) — owner_id и story_id. Так как мы собираем статистику по нескольким Историям, для каждой из них дописываем код с соответствующими story_id, которые мы собрали на предыдущем этапе через запрос stories.get.
def _prepare_execute_code_for_story_data(self, group_id: int, story_id: int, story_key: str) -> str:
code_story_stats = f'API.stories.getStats({{"owner_id": {group_id * -1}, ' \
f'"story_id": {story_id}}})'
return (
f'{{"groupId": "{story_key}",'
f'"statsGetStoryData": {code_story_stats} }}'
)
Наконец, вытягиваем статистику Историй. Для этого передаем в API те параметры для execute-запроса, которые сформировали выше. Через них мы получим статистику по публикациям, которые собрали на первом этапе.
def _collect_story_stats(self, batch: List[str]) -> dict:
collected_story_stats = dict()
for execute_items in chunks(batch, 15):
response = self.vk_client_stories.execute(**{
'code': self.execute.format(elements=','.join(map(str, execute_items)))
})
for batch in response:
batch_group_id = batch['groupId']
stats_get_data = batch['statsGetStoryData']
collected_story_stats[batch_group_id] = stats_get_data
return collected_story_stats
Подводные камни
Основные нюансы, которые нужно учитывать, чтобы вытянуть через официальный API ВКонтакте данные в нужных объеме и формате:
Есть ограничения на количество запросов. API ВКонтакте обрабатывает ограниченное число запросов за промежуток времени. И для разных типов методов предусмотрены свои «квоты». Об этом нужно помнить, если вы планируете выгружать данные автоматически и в больших объемах.
Отдельные методы позволяют получить информацию только об ограниченном наборе сущностей. Например, метод stories.get возвращает только активные на момент запроса Истории. Если 24 часа с момента публикации Историй уже прошли, собрать их не получится.
Важно разобраться со взаимодействием разных методов между собой. Без этого не получится выгрузить отдельные показатели. Например, чтобы собрать статистику по всем Историям – и активным, и завершенным, выпущенным за определенный период времени, мы используем метод stories.getStats. Но для этого нужно указать в параметрах ID конкретных Историй. Эту информацию мы можем получить только с помощью метода stories.get. Поэтому для выгрузки и поддержания актуальной статистики по этому типу контента мы собираем ID Историй через stories.get, а затем – финальную статистику по ним после завершения через stories.getStats.
Случаются баги и ошибки. Нельзя сказать, что этим страдает исключительно API ВКонтакте – от ошибок не застрахована ни одна система. Однако об этом нужно помнить и в случае чего сразу обращаться в техподдержку. Специалисты ВК довольно оперативно решают такие ситуации – собирают дополнительную информацию, передают разработчикам и исправляют ошибки.
Это не все подводные камни, с которыми мы сталкиваемся. Чтобы разобраться со всеми, придется тщательно изучить документацию по API и немного походить по граблям.
php7
А что такое Посещаемость Просмотры Охват в статистике по группе?