мониторинг брендаупоминания брендаанализ тональностирепутацияруководство по API

API мониторинга бренда: упоминания в вебе с оценками тональности, эмоций и авторитетности

Два новых эндпоинта SocQ собирают веб-страницы, упоминающие бренд, с оценками тональности, эмоций и авторитетности и разделяют все упоминания на позитивные, негативные и нейтральные.

SocQОбновлено 19 ноября 2026 г.6 мин чтения

Мониторинг бренда обычно начинается с двух вопросов: где в интернете говорят о нас и как к нам относятся? Для первого нужны данные на уровне страниц, которые можно прочитать и распределить по команде. Для второго нужен агрегат, который можно вывести на график, не скачивая миллионы страниц.

2026-11-17 SocQ запустил платформу Brand Monitoring с одним эндпоинтом на каждый из этих вопросов. В этом руководстве описано, что они возвращают, как выглядят запросы, сколько они стоят и когда использовать каждый из них.

Коротко: отправьте бренд, продукт или тему в query на POST /v1/brand-monitoring/mentions, чтобы получить список веб-страниц, где они упоминаются, с оценками тональности, эмоций и авторитетности для каждой. Отправьте тот же query на POST /v1/brand-monitoring/sentiment, чтобы получить одну строку, в которой все упоминания разбиты по тональности и эмоциям. Результаты забирайте через опрос GET /v1/tasks/{task_id}.

Новые эндпоинты Brand Monitoring

1 кредит SocQ = $0.005.

ЭндпоинтЧто возвращаетЦена
Brand Mentions APIОдна строка на каждую веб-страницу с упоминанием запроса: URL, заголовок, фрагмент вокруг упоминания, автор, язык, страна, тип сайта, оценки тональности и эмоций, авторитетность страницы и домена10 кредитов ($0.05) за запрос + 0.02 кредита ($0.0001) за страницу
Brand Sentiment Analysis APIОдна строка, в которой все страницы с упоминанием запроса сгруппированы по основной тональности и по сильнейшей эмоции, с числом страниц и ведущими сайтами, странами, языками и типами сайтов в каждой группе10 кредитов ($0.05) за вызов

Для Brand Mentions базовые 10 кредитов списываются и тогда, когда ни одной страницы не найдено.

Аутентификация и асинхронные задачи

Все запросы к SocQ аутентифицируются API-ключом, и один и тот же заголовок используется для отправки задачи, проверки статуса и получения результатов:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Каждый сбор данных выполняется как фоновая задача:

submit -> task_id -> queued -> running -> succeeded
                                   \-> failed

Ответ на отправку содержит data.task_id и data.status. Опрашивайте задачу по этому ID:

curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=50" \
  -H "Authorization: Bearer $SOCQ_API_KEY"

Когда status равен succeeded, ответ содержит первую страницу нормализованных записей в data.results.items. По умолчанию limit равен 50, максимум 500; если has_more равно true, передайте results.next_cursor как cursor, чтобы прочитать следующую страницу. Пока задача находится в состоянии queued, running или failed, эндпоинт возвращает метаданные задачи без results.

Необязательный callback_url в теле запроса заставляет SocQ отправить один POST со сводкой задачи после ее завершения; сами записи читайте через GET /v1/tasks/{task_id}. Тайм-аут на стороне клиента не отменяет задачу, поэтому продолжайте с тем же ID задачи, а не платите за дубликат. 402 означает недостаточно кредитов; 429 означает, что ключ достиг лимита запросов или кредитов.

Brand Mentions API: каждая страница, где вас упоминают

Brand Mentions API возвращает страницы со всего интернета, где упоминается ваш запрос: обзоры в блогах, новостные материалы, ветки форумов и карточки товаров. Укажите бренд, продукт или тему в query, до 100 символов. Заключите фразу в двойные кавычки, чтобы искать точное совпадение. content_type ограничивает результаты сайтами типа news, blogs, message-boards, ecommerce или organization. По умолчанию results_limit равен 100, допустимы значения от 1 до 1,000.

curl -X POST "https://api.socq.ai/v1/brand-monitoring/mentions" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "notion",
    "results_limit": 100
  }'

Каждая строка описывает одну страницу:

  • Где: url, title, domain, language, country (две буквы; WW означает весь мир) и page_types, например news, blogs или ecommerce.
  • Что: text — фрагмент вокруг упоминания, и author_name, если автор указан.
  • Какая тональность: sentiment с оценками positive, negative и neutral от 0 до 1, которые в сумме дают 1, и emotions с шестью оценками от 0 до 1: happiness, love, fun, share, sadness и anger.
  • Насколько это важно: content_quality_score (от 0 до 100), spam_score (от 0 до 100, чем выше, тем больше признаков спама), domain_rank и page_rank (от 0 до 1,000).
  • Когда: fetched_at — время, когда страница была прочитана в последний раз.

Оценки авторитетности и спама позволяют отсортировать большой набор результатов так, чтобы команда сначала читала авторитетные страницы с низким уровнем спама, а разбивка по тональности помечает страницы, на которые нужно ответить. 100 страниц стоят 12 кредитов ($0.06), а максимальные 1,000 страниц — 30 кредитов ($0.15). Полный список полей: документация Brand Mentions.

Чтобы следить только за прессой, добавьте фильтр:

{
  "query": "\"notion ai\"",
  "content_type": "news",
  "results_limit": 200
}

Brand Sentiment Analysis API: разбивка за итоговой цифрой

Brand Sentiment Analysis API отвечает на вопрос «как интернет относится к нам», не возвращая отдельные страницы. Страницы с упоминанием вашего запроса группируются по основной тональности и отдельно по сильнейшей эмоции. Для каждой группы указывается, сколько в ней страниц, и какие сайты, страны, языки и типы сайтов вносят наибольший вклад.

curl -X POST "https://api.socq.ai/v1/brand-monitoring/sentiment" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "notion"
  }'

Единственная строка результата содержит два массива:

  • sentiments: по одной группе для positive, negative и neutral.
  • emotions: по одной группе для happiness, love, fun, share, sadness и anger.

У каждой группы есть label, mentions_count, а также top_domains, countries, languages и page_types — каждый из них представляет собой список пар name и count, начиная с самых крупных. Такая структура позволяет понять, исходит ли критика от новостных изданий или с одного форума и какие страны ее формируют. Каждый запрос стоит 10 кредитов ($0.05). Анализ очень широких запросов с миллионами упоминаний занимает больше времени, до нескольких минут, поэтому опрашивайте задачу терпеливо. См. документацию Brand Sentiment Analysis.

Какой эндпоинт выбрать

  • Еженедельная панель репутации: запускайте Brand Sentiment Analysis для своего бренда и каждого конкурента, сохраняйте счетчики и стройте график во времени. Четыре бренда стоят 40 кредитов ($0.20) за запуск.
  • Очередь разбора для PR-команды: запускайте Brand Mentions с content_type, равным news или message-boards, затем сортируйте по тональности negative и по domain_rank.
  • Расследование всплеска: когда счетчики тональности меняются, посмотрите top_domains в негативной группе, чтобы понять, какие сайты его вызывают, затем получите эти страницы через Brand Mentions.

Оба эндпоинта работают с веб-страницами пяти перечисленных выше типов сайтов. Для публикаций и комментариев в соцсетях используйте эндпоинты платформ, описанные в руководстве по единому API социальных сетей. О том, что ИИ-ассистенты говорят о вашем бренде, читайте в руководстве по API AI-поиска.

FAQ

Что такое API мониторинга бренда?

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

Как искать точную фразу?

Заключите ее в двойные кавычки внутри query, например "\"notion ai\"" в JSON. Длина запроса — до 100 символов.

Какие типы сайтов охватываются?

Страницы классифицируются как news, blogs, message-boards, ecommerce или organization. В Brand Mentions можно ограничить результаты одним из этих типов с помощью content_type.

Списываются ли кредиты, если ничего не найдено?

Brand Mentions списывает базовые 10 кредитов, даже если ни одной страницы не найдено, плюс 0.02 кредита за каждую возвращенную страницу. Brand Sentiment Analysis стоит 10 кредитов за запрос.

Почему моя задача анализа тональности все еще выполняется?

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

BRAND MONITORING API

Проверить сценарий на публичном URL Brand Monitoring

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

API для Brand Monitoring