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, выберите лимит на локацию и рассматривайте возвращенные записи как снимок на момент сбора.
- Укажите один или несколько известных WOEID в виде числовых строк; этот эндпоинт не распознает названия мест.
- Выберите целое значение results_limit от 20 до 2 000 или оставьте значение по умолчанию 100 на каждый WOEID.
- Отправьте запрос методом POST на /v1/x/trends, затем опрашивайте /v1/tasks/{task_id}, пока задача не завершится успешно.
- Читайте 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, потому что источник не предоставляет время создания тренда.
- Курсоры результатов задачи листают уже сохраненные записи и не запрашивают у провайдера новую страницу трендов.
Связанные API
Помимо 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 Followers List API
- X Following List API
- X Post Quotes API
- X Post Replies API
- X Post Retweeters API
- Twitter Mentions API
- X Community API
- X Community Posts API
- X Thread Context API
- X Account Location API
- X Verified Followers API
- X List Tweets API
- Twitter List Members API
- Twitter List Followers API
- X Community Members API
- X Community Moderators API
- X Articles API
- X Spaces API
- Twitter Media Scraper API
- X User Replies API
- Twitter Follow Checker API
- Twitter Video Transcript API