В браузере X по-прежнему выглядит как лента. Спецификация публичных данных уже: имя пользователя — это не URL поста, цитата — это не репост, ответ — это не цитата, а удаленный или защищенный пост должен корректно завершаться ошибкой, а не превращаться в пустую запись.
В этом руководстве строится продакшен-процесс на основе API SocQ для X. Рассматриваются официальный и публичный доступ, маршрутизация по эндпоинтам, подготовка входных данных, асинхронные задачи, смысл полей, частота обновления и ответственное использование.
Коротко: отправляйте имена пользователей, URL постов
x.comилиtwitter.comили поисковый запрос наPOST /v1/x/{resource}, сохраняйте ID задачи и опрашивайте/v1/tasks/{id}. Не сводите цитаты, репосты и ответы в одну таблицу без поля, различающего ресурсы.
Официальный API X или API публичных данных?
Официальный API X платный и требует разрешений. Это правильный продукт, когда нужно публиковать, отправлять личные сообщения, управлять рекламой, подписываться или ставить лайки от имени пользователя либо получать потоки и другие данные, доступные при авторизации аккаунта. Условия доступа и цены меняются; для продуктов записи и партнерских продуктов источником истины считайте текущую документацию для разработчиков.
SocQ — уровень чтения публичных данных для поддерживаемых профилей, известных постов, окон постов пользователя, поиска, связей в обсуждениях и трендов. Он не аутентифицируется как пользователь X и не заменяет официальные инструменты публикации и рекламы. О ценах и сравнении поставщиков читайте в статьях альтернативы API Twitter, API для парсинга Twitter и альтернативы TwitterAPI.io. Выберите модель доступа до выбора эндпоинта.
Выбор правильного эндпоинта X
| Ресурс | Эндпоинт | Принимаемый публичный вход | Типичное применение |
|---|---|---|---|
| Профили | /v1/x/profiles | Имена пользователей, с @ или без | Публичная идентичность и видимые счетчики |
| Посты | /v1/x/posts | URL постов x.com или twitter.com | Один известный пост |
| Посты пользователя | /v1/x/user-posts | Имена пользователей | Недавние публичные посты аккаунта |
| Поиск | /v1/x/search | Запрос | Поиск публичных постов в режиме Latest или Top |
| Ответы | /v1/x/post-replies | URL постов | Ответы на известный пост |
| Цитаты | /v1/x/post-quotes | URL постов | Цитаты известного поста |
Также доступны:
post-retweetersдля URL публичных постов.followers-listиfollowing-listдля имен пользователей сresults_limitот 200 до 2 000 с шагом 200.trendsдля числовых WOEID.
Цитаты, репосты и ответы — разные ресурсы. У цитаты есть собственный текст поста. Список сделавших репост — это набор профилей. Ответ — это пост, принадлежащий обсуждению. Не выполняйте для них upsert так, будто это один и тот же объект.
Нормализация имен пользователей, URL и запросов
Сохраняйте отправленное значение, затем очищайте его копию:
- Принимайте имена пользователей с
@или без, затем сохраняйте одно каноническое имя. - Принимайте оба домена —
x.comиtwitter.com. Для эндпоинтов, работающих с постами, требуйте числовой путь/status/{id}. - Удаляйте параметры запроса для отслеживания. Не требуйте конкретного мобильного домена или домена с локалью, если ID поста не поврежден.
- Удаляйте дубликаты имен пользователей без учета регистра, а постов — по ID поста.
- Отклоняйте пустые запросы и имена пользователей до отправки.
- Храните поисковые выражения в строке сведений о происхождении, чтобы аналитики могли объяснить, почему пост попал в датасет.
user-posts и search принимают results_limit от 20 до 2 000 с шагом 20. Для поиска sort_by принимает значения latest или top. post-replies также принимает sort_by со значением relevance, latest или likes.
Отправка задачи сбора
Сбор профилей:
curl -X POST "https://api.socq.ai/v1/x/profiles" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"usernames":["openai","@github"]}'
Сбор известных постов с любого из доменов:
curl -X POST "https://api.socq.ai/v1/x/posts" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://x.com/X/status/2073395918011789670"]}'
Сбор окна постов пользователя:
curl -X POST "https://api.socq.ai/v1/x/user-posts" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"usernames":["openai","github"],"results_limit":40}'
Поиск публичных постов:
curl -X POST "https://api.socq.ai/v1/x/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"AI lang:en","results_limit":100,"sort_by":"latest"}'
Собирайте ответы и цитаты отдельными заданиями:
curl -X POST "https://api.socq.ai/v1/x/post-replies" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://x.com/X/status/2073395918011789670"],"results_limit":20,"sort_by":"latest"}'
curl -X POST "https://api.socq.ai/v1/x/post-quotes" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://x.com/X/status/2073395918011789670"],"results_limit":20}'
Сохраняйте возвращенный ID задачи вместе с названием ресурса и каноническими входными данными.
Опрос задачи без создания дубликатов
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
Статусы queued и running — это нормальное состояние. Используйте экспоненциальную задержку. Когда задача завершится успешно, читайте data.results.items и переходите по next_cursor, пока has_more равно true.
Надежный воркер должен сохранять:
- ID пакета и ID задачи SocQ.
- Ресурс и канонические имена пользователей, URL или запрос.
- Время отправки и завершения.
- Конечный статус и категорию ошибки.
- Последний обработанный курсор результатов.
Перезапуск воркера — не причина повторно отправлять тот же поиск.
Возвращаемые поля
У записей есть общие поля id, platform, resource, type, url, created_at, collected_at и extra.
Профиль включает username, name, description, avatar_url, cover_url, is_verified, is_private и видимые метрики. Защищенные аккаунты не являются целью сбора публичных данных.
Пост включает text, language, author, видимые метрики, media, hashtags и mentions, если они публичны. Используйте id как предпочтительный ключ сущности, а URL поста — как сведения о происхождении.
Ответы и цитаты используют структуру поста. Список сделавших репост использует структуру профиля. Тренды — это строки результатов, привязанные к местоположению, а не посты.
Удаленные и закрытые посты должны завершаться ошибкой на уровне входных данных или задачи. Не вставляйте пустой пост, не придумывайте нулевую вовлеченность и не используйте collected_at вместо created_at.
Результаты поиска — это ранжированная выдача. latest и top — это разные способы упорядочивания ограниченного окна, а не полный исторический архив.
Python-воркер для профилей, постов и поиска
import time
import requests
BASE = "https://api.socq.ai/v1"
HEADERS = {
"Authorization": f"Bearer {SOCQ_API_KEY}",
"Content-Type": "application/json",
}
def collect(resource, payload):
created = requests.post(
f"{BASE}/x/{resource}",
headers=HEADERS,
json=payload,
timeout=30,
)
created.raise_for_status()
task_id = created.json()["data"]["task_id"]
delay = 2
while True:
response = requests.get(
f"{BASE}/tasks/{task_id}",
headers=HEADERS,
timeout=30,
)
response.raise_for_status()
task = response.json()["data"]
if task["status"] == "succeeded":
return task["results"]["items"]
if task["status"] in {"failed", "cancelled"}:
raise RuntimeError(task)
time.sleep(delay)
delay = min(delay * 1.5, 15)
profiles = collect("profiles", {"usernames": ["openai"]})
hits = collect("search", {
"query": "AI lang:en",
"results_limit": 40,
"sort_by": "latest",
})
Прежде чем выпускать это в продакшен, добавьте курсорную пагинацию, ограниченное число повторных попыток для тайм-аутов и 5xx-ответов, допускающих повтор, а также идемпотентный upsert.
Разделяйте посты и снимки метрик
Идентичность поста и его метрики меняются с разной скоростью.
x_entity
resource
platform_id
canonical_url_or_username
text_or_description
author_id
created_at
first_seen_at
last_seen_at
x_snapshot
resource
platform_id
collected_at
likes_count
replies_count
reposts_count
quotes_count
source_task_id
Выполняйте upsert по resource + id. Храните цитаты, ответы и исходные посты в одной таблице постов, только если resource остается обязательным столбцом. Список сделавших репост храните в таблице профилей или связей.
Не вычисляйте рост числа цитат по снимку списка сделавших репост. Эти метрики не взаимозаменяемы.
Проверка перед сохранением
platformдолжно быть равноx.resourceдолжно соответствовать эндпоинту.- URL постов должны содержать числовой ID в
/status/, если ресурс работает с постами. - Имена авторов должны совпадать с отправленным аккаунтом, если ресурс —
user-postsи поле присутствует. - Счетчики должны быть неотрицательными числами или null.
- Временные метки должны корректно разбираться.
- Неудавшийся закрытый или удаленный вход не должен превращаться в успешный пустой пост.
Храните невалидные строки в карантине вместе с исходными данными задачи.
Расписание обновления по типу сущности
| Сущность | Разумная начальная частота | Причина |
|---|---|---|
| Профиль | Раз в неделю или в месяц | Описание профиля и поля идентичности меняются медленно |
| Известный пост | От раза в час до раза в день, пока активен | Публичные метрики быстро меняются |
| Окно постов пользователя | От раза в час до раза в день для мониторинга | Ленты ограничены и ранжированы |
| Поиск | По расписанию, соответствующему запросу | latest и top — это не архивы |
| Ответы / цитаты | Раз в час, пока пост активен | Связи в обсуждении появляются всплесками |
| Подписчики / подписки | Раз в неделю | Списки большие, шаг — 200 |
| Тренды | Раз в час или несколько раз в день | Наборы по WOEID меняются |
Сокращайте сбор, если для бизнес-вопроса не нужен более свежий снимок.
Типичные сбои
URL поста ничего не возвращает
Убедитесь, что URL публичный, по-прежнему доступен и содержит /status/{id}. Удаленные и защищенные посты должны корректно завершаться ошибкой. Сохраняйте ошибку на уровне входных данных.
Поиск выглядит неполным
results_limit ограничивает запрос. Ранжирование, индексация и выбор между latest и top меняют страницу. Храните запрос и сортировку вместе с записями.
Цитаты сохранились как репосты
Это разные эндпоинты и разные объекты. Включайте resource в первичный ключ.
Задания по подписчикам отклоняют лимит
Эндпоинты подписчиков и подписок принимают значения от 200 до 2 000 с шагом 200. User-posts и search используют шаг 20.
Метрики расходятся с браузером
Публичные счетчики — это снимки. Они могут запаздывать, округляться или скрываться. Сравните collected_at, прежде чем винить парсер.
Один и тот же пользователь встречается дважды
Приводите имена пользователей к каноническому виду и отдавайте предпочтение стабильному публичному ID. Ведите таблицу псевдонимов на случай переименования аккаунта.
Ответственное использование данных X
Собирайте только публичные поля, необходимые для законной цели. Не обходите защищенные аккаунты, блокировки, требования входа и другие механизмы контроля доступа. Избегайте профилирования отдельных людей по чувствительным признакам и автоматизированных решений, которые могут существенно повлиять на человека, без мер защиты.
Данные X могут быть персональными данными. Определите правовое основание, где это требуется, задайте правила хранения и удаления, защищайте API-ключи и выгрузки и изучите текущие условия X с квалифицированным юристом. API публичных данных не дает лицензии на повторную публикацию постов или медиа.
Часто задаваемые вопросы
Законен ли парсинг X или Twitter?
Универсального ответа нет. Это зависит от юрисдикции, данных, способа, цели, договора и мер защиты. Это руководство не является юридической консультацией.
Заменяет ли это официальный API X?
Нет. Официальный доступ по-прежнему необходим для публикации, личных сообщений, рекламы, потоков и других действий, требующих разрешений. SocQ покрывает поддерживаемое чтение публичных данных.
Можно ли собирать закрытые или удаленные посты?
Нет. Такие входные данные должны корректно завершаться ошибкой. Не обходите защиту.
Цитаты — это то же самое, что репосты?
Нет. Цитаты — это посты. Список сделавших репост — это профили. Ответы — третий ресурс.
Возвращает ли поиск полную историю?
Нет. Он возвращает ограниченное упорядоченное окно для одного запроса.
Какой ключ использовать для удаления дубликатов?
Предпочтительно resource + id. Если публичный ID отсутствует, используйте нормализованный URL поста или имя пользователя.
X API
Проверить сценарий на публичном URL X
Отправляйте публичные входные данные и получайте нормализованные записи с отслеживаемым источником.
API для X