Unified APIAPI соцсетейруководство для разработчиков

Единый API соцсетей: один API для публичных данных соцсетей

Один API-ключ, одна модель задач и нормализованная схема для сбора публичных данных соцсетей, рекламы, e-commerce, карт, магазинов приложений и SEO на 27 платформах.

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

Добавление второй социальной платформы в продукт редко просто удваивает работу по интеграции. Каждая сеть приносит свою модель аутентификации, словарь ресурсов, формат ответа, схему пагинации, классификацию ошибок и график изменений. Двадцать семь отдельных интеграций могут превратиться в двадцать семь отдельных систем.

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

Каталог публичных данных SocQ

Коротко: вызовите 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-commerceTikTok 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, поставщик подключенных аккаунтов, лицензированный датасет или отказ от сбора.

Переход от одной платформы к каталогу

  1. Определите нормализованную внутреннюю оболочку до добавления источников.
  2. Интегрируйте один ценный ресурс и сохраняйте исходные ответы.
  3. Проверьте ID, временные метки, метрики, медиа и обработку null.
  4. Добавьте вторую платформу или категорию через тот же обработчик задач.
  5. Держите адаптеры, специфичные для источников, на границе валидации.
  6. Запустите старый и новый пайплайны параллельно на фиксированной выборке.
  7. Сравните принятые уникальные записи, свежесть и стоимость.
  8. Переходите постепенно и сохраняйте возможность отката.

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

Безопасность, конфиденциальность и ответственное использование

Храните 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