Добавление второй социальной платформы в продукт редко просто удваивает работу по интеграции. Каждая сеть приносит свою модель аутентификации, словарь ресурсов, формат ответа, схему пагинации, классификацию ошибок и график изменений. Двадцать семь отдельных интеграций могут превратиться в двадцать семь отдельных систем.
SocQ Social Media API объединяет публичные данные за одним API-ключом, одним асинхронным процессом задач и нормализованной моделью записей. Текущий каталог содержит более 170 специализированных эндпоинтов на 27 платформах: социальные сети, библиотеки рекламы, e-commerce, карты, магазины приложений и SEO.

Коротко: вызовите
POST /v1/{platform}/{resource}с входными данными, которые требует этот ресурс, сохраните возвращенный ID задачи и опрашивайте общий эндпоинт задач. Записи используют общие нормализованные соглашения для платформы, ресурса, идентификаторов, автора, метрик, медиа и временных меток, а специфичные для источника значения хранят в явных полях и вextra.
Что такое единый API соцсетей?
Единый API — это уровень абстракции над интеграциями с несколькими платформами. Вместо того чтобы учить приложение новой системе аутентификации и несовместимой оболочке ответа для каждого источника, вы интегрируете общую спецификацию, а платформу и ресурс выбираете в маршруте.
«Единый» не должен означать «делать вид, что все платформы одинаковы». Вакансия LinkedIn — это не видео TikTok, объявление Marketplace — не профиль Instagram, а у места в Google Maps нет полезного аналога в Reddit. Ответственная единая модель стандартизирует действительно общие понятия и сохраняет специфичную для источника семантику там, где она различается.
API публичных данных или API подключенных аккаунтов
По запросу «unified social media API» в выдаче встречаются два разных продукта.
API подключенных аккаунтов использует OAuth, чтобы авторизованные пользователи могли публиковать, планировать публикации, управлять комментариями или сообщениями и читать закрытую статистику аккаунта. Это правильная категория для ПО управления соцсетями.
API публичных данных собирает поддерживаемые публично видимые ресурсы для исследований, мониторинга, аналитики или обогащения. SocQ относится ко второй категории. Его эндпоинты не публикуют посты, не отправляют личные сообщения, не управляют рекламой и не заменяют официальные API для авторизованных действий с аккаунтом.
Многим продуктам нужно и то и другое: официальные API или API подключенных аккаунтов для записи и данных по разрешению, а также уровень публичных данных для поддерживаемых внешних источников.
27 платформ и более 170 эндпоинтов
О покрытии проще рассуждать по категориям, чем по короткому списку логотипов.
| Категория | Примеры в каталоге | Что обычно собирают |
|---|---|---|
| Соцсети | Instagram (17+), TikTok (18), X (15), Facebook (14), YouTube (12), LinkedIn (11), Reddit (6), Pinterest (4), Threads (3), а также Douyin, Rednote, Snapchat, Bluesky, Twitch, Truth Social, Kwai | Люди, публикации, комментарии, поиск |
| Библиотеки рекламы | Facebook, TikTok, Google и LinkedIn Ad Library | Публичные креативы и страницы рекламодателей, а не кабинет управления рекламой |
| E-commerce | TikTok Shop, Facebook Marketplace, Amazon | Товары, объявления и отзывы, а не кабинет продавца |
| Карты | Google Maps | Места, поиск и отзывы |
| Магазины приложений | Google Play, Apple App Store | Публичные сведения о приложениях, рейтинги и отзывы |
| SEO | Ресурсы SEO по ключевым словам и поисковой выдаче | Записи о результатах поиска и ключевых словах |
Глубина по-прежнему важнее названия платформы. Instagram — это не «один API Instagram». TikTok Shop — это не каталог видео TikTok. Принимаемые входные данные и возвращаемые поля каждого ресурса смотрите в каталоге API.
REST — лишь одна дверь. MCP, CLI и Agent Skill — другие двери в тот же каталог. Эта статья посвящена HTTP-спецификации.
Единая аутентификация и единая схема задач
Все эндпоинты текущего каталога используют аутентификацию Bearer:
Authorization: Bearer $SOCQ_API_KEY
Content-Type: application/json
Создание ресурса следует предсказуемому маршруту:
POST /v1/{platform}/{resource}
Примеры:
POST /v1/tiktok/profiles
POST /v1/instagram/reels
POST /v1/x/search
POST /v1/linkedin/jobs
POST /v1/tiktok-shop/search
POST /v1/facebook-ad-library/search
POST /v1/google-maps/search
Входные данные остаются специфичными для ресурса. Профили могут принимать имена пользователей, для известных сущностей могут требоваться URL, а эндпоинты поиска принимают запросы и поддерживаемые фильтры. Единый API должен нормализовать операционное поведение, не втискивая неверные входные данные в одно универсальное тело запроса.
Общий асинхронный процесс
Длительный сбор не должен держать HTTP-соединение открытым. SocQ создает задачу:
Client
└─ POST platform resource
└─ task_id
└─ poll common task endpoint
├─ queued
├─ running
├─ succeeded → paginated records
└─ failed/cancelled → normalized error
Сохраняйте ID задачи до начала опроса. Используйте экспоненциальную задержку, считайте queued и running нормальными состояниями, обрабатывайте записи только после успешного выполнения и продолжайте, если результат сообщает о наличии следующих страниц.
Благодаря этому общему конечному автомату один обработчик может управлять всем каталогом:
def submit(platform, resource, payload):
return post(f"/v1/{platform}/{resource}", json=payload)["data"]["task_id"]
def wait_for_task(task_id):
while True:
task = get(f"/v1/tasks/{task_id}")["data"]
if task["status"] == "succeeded":
return task
if task["status"] in {"failed", "cancelled"}:
raise CollectionError(task)
backoff()
Продакшен-код также должен сохранять курсоры, ограничивать число повторных попыток, классифицировать ошибки и делать запись в последующие системы идемпотентной.
Нормализованная модель записей
Там, где это применимо, записи следуют общим соглашениям:
{
"id": "source-id",
"platform": "tiktok",
"resource": "videos",
"type": "video",
"url": "https://source.example/item",
"author": {
"id": "author-id",
"username": "creator",
"name": "Creator"
},
"metrics": {
"likes_count": 120,
"comments_count": 8
},
"media": [],
"created_at": "2026-09-09T08:00:00Z",
"collected_at": "2026-09-10T08:00:00Z",
"extra": {}
}
Не у каждого ресурса есть все поля. Профиль может содержать name, description и avatar_url; публикация может использовать text; у видео бывают длительность или аудио; вакансия несет данные о трудоустройстве; результат Shop хранит цену и контекст SKU в extra. Моделируйте необязательные поля как допускающие null и ветвите логику по resource или type, когда нужна обработка, специфичная для источника.
Что можно унифицировать
Аутентификация
Один API-ключ SocQ аутентифицирует запросы ко всему каталогу.
Жизненный цикл задачи
Для отправки, опроса, конечных состояний, пагинации и наблюдаемости задач можно использовать одну схему обработчика.
Происхождение данных
Каждая сохраненная запись должна хранить platform, resource, исходный URL или запрос, время сбора и ID исходной задачи.
Общие сущности
ID, URL, авторы, публичные метрики, ссылки на медиа, время публикации и время сбора могут следовать общим соглашениям, если источник их предоставляет.
Обработка ошибок
Приложение может свести ошибки проверки входных данных, недоступные публичные ресурсы, временные сбои источника, лимиты запросов и окончательные сбои сбора к одной внутренней классификации.
Что не стоит втискивать в одну форму
Метрики не взаимозаменяемы
Воспроизведение в TikTok, просмотр в Instagram, просмотр в YouTube, показ в X, рейтинг в Reddit, реакция в LinkedIn, показ рекламы, число проданных товаров и рейтинг на карте могут иметь разные определения и разную доступность. Сохраняйте исходное название метрики вместо того, чтобы создавать одно вводящее в заблуждение число engagement.
Глубина ресурсов различается
У YouTube есть расшифровки и каналы. У LinkedIn — вакансии и компании. У Reddit — сабреддиты. У TikTok — хештеги. У библиотек рекламы — креативы. У карт — места. Матрица покрытия должна показывать эти различия.
Семантика поиска различается
Ранжирование в поиске, глубина истории, локализация, лимиты результатов и свежесть зависят от платформы. Один и тот же запрос в разных сетях — или в Shop, Ad Library и Maps — не дает сопоставимого измерения.
Доступ и видимость различаются
Публичная доступность, удаленный контент, закрытые аккаунты, возрастные или региональные ограничения и представления для авторизованных пользователей зависят от платформы. Единый API не должен создавать впечатление, что ограничения доступа исчезают.
Примеры запросов по категориям
Сбор профилей TikTok:
curl -X POST "https://api.socq.ai/v1/tiktok/profiles" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"usernames":["tiktok","natgeo"]}'
Поиск в TikTok Shop:
curl -X POST "https://api.socq.ai/v1/tiktok-shop/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"running shoes","results_limit":100,"region":"US"}'
Поиск в Facebook Ad Library:
curl -X POST "https://api.socq.ai/v1/facebook-ad-library/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"running shoes","results_limit":100,"country":"US","status":"ACTIVE","media_type":"VIDEO","sort_by":"total_impressions"}'
Поиск в Google Maps:
curl -X POST "https://api.socq.ai/v1/google-maps/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"coffee","location":"New York, NY","country":"US","results_limit":3}'
Авторизация и процесс задач остаются прежними; меняются только допустимые входные данные ресурса. Пошаговые руководства по платформам: TikTok, X и SocQ MCP.
Схема клиента на TypeScript
Используйте размеченные типы запросов вместо нетипизированного универсального тела:
type RequestMap = {
"tiktok/profiles": { usernames: string[] };
"instagram/reels": { usernames: string[]; results_limit?: number };
"x/search": { query: string; results_limit?: number; sort_by?: "latest" | "top" };
"linkedin/jobs": { urls: string[] };
"tiktok-shop/search": { query: string; results_limit?: number; region?: string };
"facebook-ad-library/search": { query: string; results_limit?: number; country?: string };
"google-maps/search": { query: string; location: string; country?: string; results_limit?: number };
};
async function submit<K extends keyof RequestMap>(
endpoint: K,
payload: RequestMap[K],
) {
const response = await fetch(`https://api.socq.ai/v1/${endpoint}`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SOCQ_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify(payload),
});
if (!response.ok) throw new Error(`SocQ ${response.status}`);
return response.json();
}
Генерируйте или поддерживайте эти типы на основе внутреннего реестра эндпоинтов, чтобы документация, валидация и клиенты не расходились друг с другом.
Проектирование базы данных
Практичное хранилище использует общую оболочку и таблицы по ресурсам:
social_record
platform
resource
source_id
canonical_url
author_id
created_at
collected_at
source_task_id
raw_json
social_metric_snapshot
platform
resource
source_id
collected_at
metric_name
metric_value
resource-specific tables
transcript segments
job details
profile attributes
product and listing fields
place and review fields
media metadata
Не складывайте все возможные поля платформ в одну таблицу из 200 столбцов. Сохраняйте нормализованную оболочку, а для специфичной глубины источников используйте типизированные таблицы ресурсов или проверенный JSON.
Нормализация ошибок и повторные попытки
Разделяйте:
- Неверные входные данные, которые никогда не будут обработаны успешно.
- Неподдерживаемые или недоступные публичные ресурсы.
- Ошибки аутентификации и аккаунта.
- Лимиты запросов или кредитов.
- Временные сбои источника.
- Ошибки поставщика или сбои проверки схемы.
Повторяйте попытки только для временных классов ошибок. Используйте ограниченную экспоненциальную задержку со случайным разбросом (jitter). Записывайте номер попытки и ID задачи и делайте upsert идемпотентным, чтобы повторная попытка не дублировала записи.
Единый API или нативные API платформ
| Фактор решения | Единый API публичных данных | Нативные API платформ |
|---|---|---|
| Интеграция | Одна схема аутентификации и задач | Своя для каждой платформы |
| Схема | Нормализованное ядро | Нативные объекты платформы |
| Поддержка | Поставщик берет на себя большую часть изменений источников | Ваша команда отслеживает каждую платформу |
| Публичные внешние данные | Покрытие поддерживаемых ресурсов | Часто ограничены продуктом и разрешениями |
| Публикация и действия с аккаунтом | SocQ не предоставляет | Требуются официальные API |
| Глубина по конкретной платформе | В пределах каталога | Максимальная при одобренном доступе |
| Управление | Один поставщик плюс обязательства перед источниками | Прямые отношения с платформой |
Это не выбор по принципу «все или ничего». Используйте нативные API для записи, аналитики собственных аккаунтов и сценариев с разрешениями, а единый API публичных данных — для поддерживаемого чтения публичных данных, когда такая модель доступа подходит.
Типичные сценарии использования
- Мониторинг брендов и тем в разных социальных сетях.
- Исследование блогеров и авторов контента.
- Анализ контента и креативов конкурентов.
- Исследование публичных данных Shop, Marketplace и товаров.
- Сбор мест и отзывов.
- Датасеты магазинов приложений и SEO.
- Инструменты исследования для ИИ-агентов с общим каталогом.
- Датасеты комментариев, публикаций, видео и расшифровок.
- Обогащение публичных профилей или данных о компаниях с надлежащими мерами защиты.
Проектируйте пайплайн под минимально необходимые для сценария данные, а не под все поля, которые может отдать источник.
Когда не стоит использовать единый API публичных данных
Не используйте SocQ, когда:
- Нужно публиковать, отвечать, отправлять личные сообщения или управлять рекламой.
- Нужна закрытая статистика аккаунта с авторизацией пользователя.
- Участие в официальной партнерской программе обязательно.
- Критически важна одна функция конкретной платформы, которой нет в каталоге.
- Ваши юридические, договорные или управленческие требования запрещают предлагаемый сбор данных.
Правильным ответом может быть официальный API, поставщик подключенных аккаунтов, лицензированный датасет или отказ от сбора.
Переход от одной платформы к каталогу
- Определите нормализованную внутреннюю оболочку до добавления источников.
- Интегрируйте один ценный ресурс и сохраняйте исходные ответы.
- Проверьте ID, временные метки, метрики, медиа и обработку null.
- Добавьте вторую платформу или категорию через тот же обработчик задач.
- Держите адаптеры, специфичные для источников, на границе валидации.
- Запустите старый и новый пайплайны параллельно на фиксированной выборке.
- Сравните принятые уникальные записи, свежесть и стоимость.
- Переходите постепенно и сохраняйте возможность отката.
Добавление платформ становится вопросом конфигурации только после того, как смысл данных, наблюдаемость и обработка сбоев действительно стандартизированы.
Безопасность, конфиденциальность и ответственное использование
Храните API-ключи в менеджере секретов, предоставляйте минимально необходимый доступ к сохраненным данным, шифруйте передачу и хранение, журналируйте административный доступ и определите процедуры хранения и удаления.
Собирайте только поддерживаемые публичные данные, необходимые для законной цели. Не обходите закрытые аккаунты, требования входа, настройки аудитории и другие ограничения. Изучите условия платформ, обязательства по конфиденциальности, правила интеллектуальной собственности и применимое законодательство. Единый технический интерфейс не объединяет и не отменяет юридических обязательств.
FAQ
Заменяет ли единый API соцсетей официальные API?
Нет. SocQ обрабатывает поддерживаемое чтение публичных данных. Официальные API по-прежнему нужны для публикации, действий пользователей через OAuth, закрытой статистики и партнерских продуктов платформ.
Возвращают ли все 27 платформ одинаковые поля?
Нет. Они следуют общим нормализованным соглашениям там, где понятия совпадают, а поля, специфичные для ресурсов, остаются отдельными.
Нужен ли отдельный API-ключ для каждой платформы?
Один ключ SocQ покрывает весь каталог SocQ. Официальным интеграциям и интеграциям с другими поставщиками по-прежнему нужны собственные учетные данные.
Может ли SocQ публиковать посты в соцсетях?
Нет. Текущие эндпоинты — это операции чтения публичных данных.
Как обрабатываются лимиты запросов?
Приложение должно соблюдать лимиты аккаунта SocQ, сохранять состояние асинхронных задач, увеличивать интервал при опросе и повторять только временные сбои.
Подходит ли это для ИИ-агентов?
Да, если агент использует типизированные инструменты, ограниченные входные данные, сохранение состояния задач, валидацию и одобрение человеком для значимых последующих действий. Если клиент поддерживает протокол MCP, начните с MCP.
Что охватывает текущий каталог?
27 платформ и более 170 эндпоинтов: социальные сети, библиотеки рекламы, e-commerce, карты, магазины приложений и SEO. Актуальный список — на странице /apis.
MULTI-PLATFORM API
Проверить сценарий на публичном URL Multi-platform
Отправляйте публичные входные данные и получайте нормализованные записи с отслеживаемым источником.
API для Multi-platform