Streaming API

Streaming API — это инструмент для получения публичных данных из ВКонтакте по заданным ключевым словам.

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

Для чего это нужно?

Streaming API нужен всем, кто занимается изучением данных из соцмедиа. Это могут быть научные статистические исследования, анализ восприятия бренда, проверка эффективности маркетинговой стратегии и многое другое. Главное, что лежит в основе — выборка публичного контента с определенными словами (например, название торговой марки).

Новый инструмент позволяет получать нужные вам данные, и только их, не совершая множества отдельных запросов.

Как это работает?

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

В базовой версии Streaming API мы предоставляем 1% от объёма всего публичного контента. Как правило, этого достаточно для проведения научных или некоммерческих исследований.

Чтобы получить доступ к расширенной версии Streaming API, включающей 100% данных, пожалуйста, обратитесь в Поддержку. Обязательно расскажите для каких целей нужен доступ к расширенной версии и укажите ID используемого приложения.

Техническая документация

Streaming API передаёт данные с использованием протокола WebSocket.

Работа со Streaming API выглядит так — вы проходите авторизацию, добавляете нужные Вам правила и затем получаете данные, которые подходят под эти правила, в едином потоке.

С помощью Streaming API вы можете получить не более 1% всех публичных данных, удовлетворяющих заданным правилам. Чтобы получить доступ к расширенной версии Streaming API, включающей 100% данных, пожалуйста, напишите в Поддержку.

Примеры реализации и готовые библиотеки:

• •
  Пример использования на Go.
• •
  Streaming API в Java SDK.
• •
  Streaming API на Node JS.

Авторизация

Чтобы получить учётные данные, необходимые для начала работы, используйте метод API streaming.getServerUrl. В качестве результата метод возвращает URL для дальнейших запросов в поле endpoint (string) и ключ доступа в поле key (string).

Пример авторизации на Go (Github).

Формат правил

Правило — это набор ключевых слов, наличие которых в тексте объекта означает, что объект попадёт в поток.

• •
  Если слова указаны без двойных кавычек, поиск ведётся с упрощением (все словоформы, без учёта регистра).
• •
  Для поиска по точному вхождению (с учётом регистра, словоформы и т.п.) каждое слово должно быть указано в двойных кавычках.
• •
  Минус (-) перед ключевым словом исключит из выборки тексты, содержащие это слово. Правило не может состоять только из ключевых слов с минусом.
• •
  Внутри правила в кавычках вы можете использовать для поиска произвольные символы (#, $, % и так далее), кроме пробела и перевода каретки. В правилах без кавычек подобные символы игнорируются.

Например, правилу кот будут соответствовать объекты с текстом «кот», «кОт», «Котик».

Правилу «кот» из вышеперечисленных будет соответствовать только объект с текстом «кот».

Правилу «-кот» будут соответствовать объекты, которые не содержат точную словоформу «кот».

Правилу «-собака» будут соответствовать объекты, которые не содержат слово «собака» в любой форме.

Чтобы искать записи с хештегом, используйте правило вида «#хештег».

У каждого правила есть значение (value) — собственно содержание правила, и метка (tag). Вместе с каждым объектом вы будете получать список его меток, чтобы понимать, какому правилу этот объект соответствует.

Ограничения:

• •
  максимальное количество правил — 300;
• •
  максимальное количество ключевых слов в правиле — 100;
• •
  максимальный размер правила в байтах — 4096;
• •
  максимальный размер метки правила (tag) в байтах — 256;

Список методов

Для работы с Streaming API вам потребуются эти методы:

• •
  GET /rules — получает текущие правила из потока;
• •
  POST /rules — добавляет новое правило в поток;
• •
  DELETE /rules — удаляет правило из потока;
• •
  GET /stream — создаёт подключение к потоку данных.

Все методы возвращают в результате объект в формате JSON, либо HTTP-статус 503 в случае непредвиденной ошибки на сервере. Каждый JSON-объект содержит поле code (integer), определяющий содержимое:

• •
  code = 100 — объект содержит событие;
• •
  code = 200 — свидетельствует об успешном выполнении запроса;
• •
  code = 300 — объект содержит сервисное сообщение;
• •
  code = 400 — объект содержит сообщение об ошибке.

Получение правил

Пример получения правил из потока на Go (Github).

Используйте этот метод, чтобы получить правила, которые уже добавлены в поток.

Возвращает объект с полями:

• •
  code (integer) — код ответа. Возможные значения: 200, 400.
• •
  rules (array) — (для code = 200) данные о правилах в потоке. Каждый объект в массиве rules содержит следующие поля:

  • •
    value (string) — строковое представление правила;
  • •
    tag (string) — метка правила.
• •
  error (object) — (для code = 400) описание ошибки. Объект, который содержит поля:

  • •
    message (string) — сообщение об ошибке;
  • •
    error_code (integer) — код ошибки.

Пример ответа:

Добавление правил

Пример добавления правила в поток на Go (Github).

Используйте этот метод, чтобы добавить новое правило в поток.

В теле запроса необходимо передать JSON-объект (rule), описывающий новое правило. Объект rule содержит поля:

• •
  value (string) — строковое представление правила;
• •
  tag (string) — метка правила.

Например:

Возвращается объект с полями:

• •
  code (integer) — код ответа. Возможные значения: 200, 400.
• •
  error (object) — (для code = 400) описание ошибки. Объект, который содержит поля:

  • •
    message (string) — сообщение об ошибке;
  • •
    error_code (integer) — код ошибки.

Пример ответа

Пример ошибки

Удаление правил

Пример удаления правила из потока на Go (Github).

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

В теле запроса необходимо передать поле tag (string), содержащее метку правила, которое необходимо удалить.

Например:

Возвращается объект с полями:

• •
  code (integer) — код ответа. Возможные значения: 200, 400.
• •
  error (object) — (для code = 400) описание ошибки. Объект, который содержит поля:

  • •
    message (string) — сообщение об ошибке;
  • •
    error_code (integer) — код ошибки.

Пример ответа:

Пример ошибки:

Чтение потока

Пример чтения данных для одного потока на Go (Github).

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

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

По этому WebSocket-соединению будут приходить данные в формате JSON. Кроме самих событий, периодически могут приходить WebSocket PING сообщения, на которые нужно отвечать. Соединение будет разорвано, если сервер не получит ответное WebSocket PONG сообщение.

Объект, описывающий событие, содержит следующие поля:

• •
  code (integer) — код ответа. Возможные значения: 100, 300.
• •
  service_message (object) — (для code = 300) сервисное сообщение. Объект, который содержит следующие поля:

  • •
    message (string) — текст сообщения. Возможные значения:

    • •
      Service restart — сервис будет перезапущен. После этого сообщения сервер разорвёт соединение.
    • •
      Pong wait timeout — превышено время ожидания WebSocket PONG. После этого сообщения сервер разорвёт соединение.
  • •
    service_code (integer) — код сообщения. Возможные значения:

    • •
      3000 — Service restart;
    • •
      3001 — Pong wait timeout.
• •
  event (object) — (для code = 100) событие. Объект, который содержит следующие поля:

  • •
    event_type (string) — тип события. Возможные значения:

    • •
      post
    • •
      comment
    • •
      share
    • •
      topic_post
  • •
    event_id (object) — идентификатор события. Объект, который содержит следующие поля:

    • •
      post_owner_id (integer) — идентификатор владельца записи (для event_type = post, comment, share);
    • •
      post_id (integer) — идентификатор записи (для event_type = post, comment, share);
    • •
      comment_id (integer) — идентификатор комментария (для event_type = comment);
    • •
      shared_post_id (integer) — идентификатор оригинальной записи (для event_type = share);
    • •
      topic_owner_id (integer) — идентификатор группы (для event_type = topic_post);
    • •
      topic_id (integer) — идентификатор обсуждения (для event_type = topic_post);
    • •
      topic_post_id (integer) — идентификатор сообщения в обсуждении (для event_type = topic_post);
  • •
    event_url (string) — ссылка на объект;
  • •
    text (string) — текст записи;
  • •
    action (string) — действие с объектом. Возможные значения:

    • •
      new — новый объект.
  • •
    action_time (integer) — время совершения действия с объектом.
  • •
    creation_time (integer) — время создания объекта;
  • •
    attachments (array) — медиавложения записи (фотографии, ссылки и т.п.). Описание массива attachments находится на отдельной странице;
  • •
    geo (object) — геометка. Описание объекта находится на отдельной странице;
  • •
    shared_post_text (string) — текст оригинальной записи (для event_type = share);
  • •
    shared_post_creation_time (integer) — время создания оригинальной записи (для event_type = share);
  • •
    signer_id (integer) — идентификатор пользователя, чья подпись указана под записью;
  • •
    tags (array) — метки правил для события;
  • •
    author (object) — информация об авторе. Объект, который содержит следующие поля:

    • •
      id (integer) — идентификатор автора;
    • •
      author_url (string) — URL страницы автора;
    • •
      shared_post_author_id (integer) — идентификатор автора оригинальной записи (для event_type = share);
    • •
      shared_post_author_url (string) — URL страницы автора оригинальной записи (для event_type = share);
    • •
      platform (integer) — платформа, с которой создан контент. Возможные значения:

      • •
        1 — мобильная версия сайта;
      • •
        2 — iPhone;
      • •
        3 — iPad;
      • •
        4 — Android;
      • •
        5 — Windows Phone;
      • •
        6 — Windows 8;
      • •
        7 — полная версия сайта;
      • •
        8 — сторонние приложения.

Пример ответа:

Service message

Поле service_message описывает сервисное сообщение и возвращается для ответов с полем code = 300. Сейчас вы можете получить одно из двух сервисных сообщений:

После получения одного из этих сообщений соединение будет разорвано.

Сообщения об ошибках

Поле error описывает сообщение об ошибке возвращается для ответов с полем code = 400. Вы можете получить одно из этих сообщений об ошибке: