x/
trends

Собирайте текущие публичные тренды X для одного или нескольких числовых WOEID с позицией у источника, запросом, описанием, контекстом локации и временем сбора.

X Trends API

Снимки по WOEID
Позиция у источника
Контекст локации
0,5 кредита за результат
Готово
README

Автор: SocQ · Обновлено

X Trends

Тренды X — это привязанный к локации снимок публичных тем, доступных для числового WOEID, в котором название, позиция, запрос, описание и время сбора хранятся вместе. Такая структура помогает находить региональные темы и вести повторные наблюдения, ясно показывая, что каждая запись отражает момент сбора, а не историческую серию трендов.

Возможности X Trends API

  • Сбор с привязкой к локацииЗапрашивайте текущие публичные тренды для одного или нескольких известных числовых WOEID и сохраняйте исходный идентификатор в extra.woeid.
  • Сохранение позиции у источникаСохраняет позицию от источника в metrics.rank, если она доступна, и не заменяет ее оценкой, рассчитанной SocQ.
  • Полезный контекст трендаПолучайте название тренда вместе с запросом от источника и описанием провайдера, если эти поля доступны.
  • Отдельный лимит для каждой локацииПрименяет results_limit отдельно к каждому переданному WOEID и собирает текущий доступный набор трендов каждой локации один раз.

Параметры X Trends API

ПараметрыОбязательныйОписание
woeidsОбязательныйОбязательный массив из одного или нескольких известных идентификаторов локаций X, каждый в виде непустой числовой строки.
results_limitНеобязательныйНеобязательный целочисленный лимит, который применяется отдельно к каждому WOEID. По умолчанию 100, допустимы значения от 20 до 2 000.

Как использовать X Trends API

Начните с уже известных вам числовых WOEID, выберите лимит на локацию и рассматривайте возвращенные записи как снимок на момент сбора.

  1. Укажите один или несколько известных WOEID в виде числовых строк; этот эндпоинт не распознает названия мест.
  2. Выберите целое значение results_limit от 20 до 2 000 или оставьте значение по умолчанию 100 на каждый WOEID.
  3. Отправьте запрос методом POST на /v1/x/trends, затем опрашивайте /v1/tasks/{task_id}, пока задача не завершится успешно.
  4. Читайте data.results.items и переходите по next_cursor результата задачи, пока has_more равно true.
curl -X POST "https://api.socq.ai/v1/x/trends" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"woeids":["1"],"results_limit":100}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is true

Сценарии использования X Trends API

  • Отслеживание тем на известном рынке: Собирайте текущие названия, позиции и описания, связанные с идентификатором локации, который уже ведет ваша система мониторинга.
  • Регулярные снимки для наблюдения: Запускайте один и тот же WOEID по собственному расписанию и сохраняйте collected_at с каждым результатом для последующего анализа изменений.
  • Очередь тем на проверку: Используйте возвращенные название, запрос, позицию и описание, чтобы расставлять приоритеты публичных тем для проверки аналитиком или для последующего процесса поиска.

Практические советы по X Trends API

  • Подготовьте числовые WOEID до отправки задачи; названия мест и локации в свободной форме не принимаются.
  • Значение по умолчанию 1 взято из опубликованного примера запроса бэкенда; замените его идентификатором, который соответствует нужному вам охвату.
  • Считайте results_limit верхней границей для каждого WOEID: текущий набор трендов может содержать меньше строк, чем запрошено.
  • Запускайте пересекающиеся локации в отдельных задачах, если важно сохранить каждую связь тренда с локацией: одинаковые названия трендов могут дедуплицироваться в пределах одной задачи.
  • Используйте collected_at как время наблюдения; created_at равно null, потому что источник не предоставляет время создания тренда.
  • Курсоры результатов задачи листают уже сохраненные записи и не запрашивают у провайдера новую страницу трендов.

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

  • Twitter Tweet Scraper API — Получайте по URL статусов x.com или twitter.com текст публичных постов, авторов, вовлеченность, медиа, хештеги, упоминания и связи в обсуждении.
  • Twitter Profile Scraper API — Получайте по имени пользователя публичные данные аккаунта, описание, аватар, обложку, статус аккаунта и видимую статистику аудитории.
  • Twitter User Tweets Scraper API — Собирайте свежие публичные посты, авторов, медиа, хештеги, упоминания и вовлеченность по имени пользователя без ответов.
  • Twitter Search API — Находите публичные посты по поисковому выражению с сортировкой по новизне или популярности и настраиваемым лимитом результатов.
  • Twitter User Search API — Находите публичные аккаунты X по ключевому слову.
  • X Communities Search API — Находите сообщества по ключевому слову: число участников и ссылки для эндпоинтов участников и постов.

Другие платформы

Объединяйте данные X с публичными данными других поддерживаемых соцсетей.

X Trends API — FAQ

X Trends API — это программный интерфейс для сбора текущих снимков публичных трендов X по числовому WOEID.

Передайте один или несколько известных идентификаторов локаций в виде числовых строк. Эндпоинт не преобразует название города или страны в WOEID.

По умолчанию значение равно 100, допустимы целые числа от 20 до 2 000, и лимит применяется отдельно к каждому WOEID. Источник может предоставить меньше текущих трендов, чем запрошено.

Запись содержит название тренда в полях id и text, позицию от источника, если она есть, collected_at, а также дополнительные поля extra с WOEID, запросом и описанием, если они доступны.

Нет. Он возвращает текущий снимок для каждого запрошенного WOEID; чтобы получить историю, запускайте сбор по расписанию и сохраняйте повторные результаты в своей системе.

Сохраненные записи дедуплицируются по нормализованному названию тренда в пределах задачи. Если одно и то же название встречается в нескольких переданных локациях, первая сохраненная запись может сохранить только одно значение extra.woeid.

Каждый успешно сохраненный нормализованный тренд стоит 0,5 кредита SocQ. Предварительная оценка рассчитывается по results_limit для каждого переданного WOEID, а неиспользованные предварительно списанные кредиты возвращаются после завершения расчетов по задаче.