제품에 두 번째 소셜 플랫폼을 붙인다고 해서 연동 작업이 딱 두 배로 늘어나는 경우는 드뭅니다. 네트워크마다 인증 방식, 리소스 용어, 응답 구조, 페이지네이션 방식, 오류 분류, 유지보수 일정이 모두 다르기 때문입니다. 연동이 27개면 서로 다른 시스템 27개를 관리해야 할 수도 있습니다.
SocQ 소셜 미디어 API는 공개 데이터를 API 키 하나, 비동기 작업 워크플로 하나, 정규화된 레코드 모델 하나로 제공합니다. 현재 카탈로그에는 소셜 네트워크, 광고 라이브러리, 커머스, 지도, 앱스토어, SEO까지 27개 플랫폼에 걸쳐 170개가 넘는 엔드포인트가 있습니다.

빠른 답변: 리소스가 요구하는 입력값으로
POST /v1/{platform}/{resource}를 호출하고, 반환된 작업 ID를 저장한 뒤 공통 작업 엔드포인트를 폴링하세요. 레코드는 플랫폼, 리소스, 식별자, 작성자, 지표, 미디어, 타임스탬프에 대해 정규화된 규칙을 공유하고, 원본에만 있는 값은 명시적인 필드와extra에 그대로 남깁니다.
통합 소셜 미디어 API란
통합 API는 여러 플랫폼 연동 위에 놓인 추상화 계층입니다. 소스마다 새로운 인증 체계와 서로 호환되지 않는 응답 구조를 애플리케이션에 가르치는 대신, 공통 사양 하나를 연동하고 경로에서 플랫폼과 리소스를 선택합니다.
“통합”이 “모든 플랫폼이 똑같은 척한다”는 뜻이어서는 안 됩니다. LinkedIn의 채용 공고는 TikTok 동영상이 아니고, Marketplace의 판매 상품은 Instagram 프로필이 아니며, Google Maps의 장소는 Reddit에 대응하는 개념이 없습니다. 책임 있는 통합 모델은 실제로 공통된 개념만 표준화하고, 서로 다른 부분은 원본의 의미를 그대로 보존합니다.
공개 데이터 API와 연결 계정 API
“통합 소셜 미디어 API”로 검색하면 서로 다른 두 가지 제품이 나옵니다.
연결 계정 API는 OAuth로 인증된 사용자가 게시물을 발행하고 예약하며, 댓글이나 메시지를 관리하고, 비공개 계정 인사이트를 읽을 수 있게 해 줍니다. 소셜 미디어 관리 소프트웨어에 알맞은 유형입니다.
공개 데이터 API는 조사, 모니터링, 분석, 데이터 보강을 위해 공개적으로 볼 수 있는 지원 리소스를 수집합니다. SocQ는 이 두 번째 유형에 속합니다. 게시물 발행, DM 전송, 광고 관리는 지원하지 않으며, 인증이 필요한 계정 동작을 위한 공식 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 광고 라이브러리 | 공개된 광고 소재와 광고주 페이지 (광고 관리자가 아님) |
| 커머스 | TikTok Shop, Facebook Marketplace, Amazon | 상품, 판매 상품, 리뷰 (판매자 백오피스가 아님) |
| 지도 | Google Maps | 장소, 검색, 리뷰 |
| 앱스토어 | Google Play, Apple App Store | 공개 앱 상세 정보, 순위, 리뷰 |
| SEO | SEO 키워드 및 SERP 리소스 | 검색 결과와 키워드 레코드 |
플랫폼 이름보다 중요한 것은 지원의 깊이입니다. Instagram은 “하나의 Instagram API”가 아니며, 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 결과에는 extra에 가격과 SKU 정보가 담깁니다. 선택 필드는 null을 허용하도록 모델링하고, 원본 고유 로직이 필요할 때는 resource나 type으로 분기하세요.
통합할 수 있는 것
인증
SocQ API 키 하나로 카탈로그 전체의 요청을 인증할 수 있습니다.
작업 수명 주기
제출, 폴링, 종료 상태, 페이지네이션, 작업 관찰 가능성에 같은 워커 패턴을 쓸 수 있습니다.
출처
저장하는 모든 레코드에는 platform, resource, 원본 URL 또는 검색어, 수집 시각, 원본 작업 ID를 남겨야 합니다.
공통 엔티티
ID, URL, 작성자, 공개 지표, 미디어 참조, 게시 시각, 수집 시각은 원본이 제공하는 범위에서 공통 규칙을 따를 수 있습니다.
오류 처리
입력 검증 오류, 조회할 수 없는 공개 리소스, 일시적인 업스트림 장애, 속도 제한, 최종 수집 실패를 애플리케이션 내부의 하나의 분류 체계로 매핑할 수 있습니다.
하나의 구조로 억지로 합치면 안 되는 것
지표는 서로 바꿔 쓸 수 없습니다
TikTok의 재생, Instagram의 조회, YouTube의 조회수, X의 노출, Reddit의 점수, LinkedIn의 반응, 광고 노출, 상품 판매 수, 지도 평점은 정의도 제공 여부도 다를 수 있습니다. 오해를 부르는 engagement 숫자 하나를 만들지 말고 원래의 지표 이름을 유지하세요.
리소스의 깊이가 다릅니다
YouTube에는 스크립트와 채널이 있습니다. LinkedIn에는 채용 공고와 회사가 있습니다. Reddit에는 서브레딧이, TikTok에는 해시태그가, 광고 라이브러리에는 광고 소재가, 지도에는 장소가 있습니다. 지원 범위 매트릭스는 이런 차이를 드러내야 합니다.
탐색 방식이 다릅니다
검색 순위, 과거 도달 범위, 현지화, 결과 수 제한, 최신성은 플랫폼마다 다릅니다. 여러 네트워크에서, 또는 Shop·광고 라이브러리·지도에서 같은 검색어로 검색해도 동일한 조건의 측정이 아닙니다.
접근 권한과 공개 범위가 다릅니다
공개 여부, 삭제된 콘텐츠, 비공개 계정, 연령·지역 제한, 로그인 상태에서만 보이는 화면은 플랫폼마다 다릅니다. 통합 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 광고 라이브러리 검색:
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 클라이언트 패턴
타입이 지정되지 않은 범용 페이로드 대신 판별 유니온(discriminated union) 요청 타입을 사용하세요.
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에 담으세요.
오류 정규화와 재시도
다음을 구분하세요.
- 영원히 성공할 수 없는 잘못된 입력.
- 지원되지 않거나 조회할 수 없는 공개 리소스.
- 인증 및 계정 오류.
- 속도 제한 또는 크레딧 제한.
- 일시적인 업스트림 장애.
- 업체 측 버그 또는 스키마 검증 실패.
재시도는 일시적인 유형에만 하세요. 지터를 더한 제한된 지수 백오프를 사용합니다. 시도 횟수와 작업 ID를 기록하고, 재시도해도 레코드가 중복되지 않도록 upsert를 멱등하게 만드세요.
통합 API와 플랫폼 네이티브 API 비교
| 판단 기준 | 통합 공개 데이터 API | 플랫폼 네이티브 API |
|---|---|---|
| 연동 | 인증과 작업 패턴 하나 | 플랫폼마다 다름 |
| 스키마 | 정규화된 핵심 | 플랫폼 고유 객체 |
| 유지보수 | 원본의 변화 상당 부분을 업체가 흡수 | 팀이 플랫폼마다 직접 대응 |
| 외부 공개 데이터 | 지원되는 리소스 범위 | 제품과 권한에 따라 제한되는 경우가 많음 |
| 게시 및 계정 동작 | SocQ는 미제공 | 공식 API 필요 |
| 플랫폼 고유 기능의 깊이 | 카탈로그 범위로 한정 | 접근이 승인되면 가장 강력 |
| 거버넌스 | 업체 한 곳과 원본의 의무 | 플랫폼과 직접 관계 |
둘 중 하나만 골라야 하는 문제는 아닙니다. 쓰기, 자체 계정 분석, 권한이 필요한 워크플로에는 네이티브 API를, 접근 모델이 맞는 지원되는 공개 읽기에는 통합 공개 데이터 API를 쓰세요.
대표적인 활용 사례
- 소셜 네트워크 전반의 브랜드 및 주제 모니터링.
- 인플루언서와 크리에이터 조사.
- 경쟁사의 콘텐츠 및 광고 소재 분석.
- 공개 Shop, Marketplace, 상품 조사.
- 장소와 리뷰 수집.
- 앱스토어 및 SEO 데이터셋.
- 하나의 카탈로그를 공유하는 AI 에이전트 조사 도구.
- 댓글, 게시물, 동영상, 스크립트 데이터셋.
- 적절한 안전장치를 갖춘 공개 프로필 또는 회사 정보 보강.
원본이 제공할 수 있는 모든 필드가 아니라, 활용 목적에 필요한 최소한의 데이터를 기준으로 파이프라인을 설계하세요.
통합 공개 데이터 API를 쓰지 말아야 할 때
다음과 같은 경우에는 SocQ를 쓰지 마세요.
- 게시, 답글 작성, DM 전송, 광고 관리가 필요한 경우.
- 사용자 인증을 거친 비공개 계정 인사이트가 필요한 경우.
- 공식 파트너 프로그램이 필수인 경우.
- 플랫폼 고유의 기능 하나가 꼭 필요한데 카탈로그에 없는 경우.
- 법적, 계약상, 거버넌스상의 요건이 계획한 수집을 금지하는 경우.
정답은 공식 API, 연결 계정 제공업체, 라이선스를 받은 데이터셋일 수도 있고, 아예 수집하지 않는 것일 수도 있습니다.
단일 플랫폼에서 카탈로그로 마이그레이션하기
- 소스를 추가하기 전에 정규화된 내부 엔벨로프를 정의합니다.
- 가치가 높은 리소스 하나를 먼저 연동하고 원본 응답을 보존합니다.
- ID, 타임스탬프, 지표, 미디어, null 처리를 검증합니다.
- 같은 작업 워커로 두 번째 플랫폼이나 카테고리를 추가합니다.
- 원본 고유의 어댑터는 검증 경계에 둡니다.
- 고정된 표본으로 기존 파이프라인과 새 파이프라인을 병렬 실행합니다.
- 채택된 고유 레코드, 최신성, 비용을 비교합니다.
- 단계적으로 마이그레이션하고 롤백 경로를 유지합니다.
데이터의 의미, 관찰 가능성, 장애 처리가 실제로 표준화된 뒤에야 플랫폼 추가가 설정 작업으로 바뀝니다.
보안, 개인정보, 책임 있는 사용
API 키는 시크릿 매니저에 보관하고, 저장된 데이터에는 최소 권한 접근을 적용하고, 전송과 저장을 암호화하고, 관리자 접근을 로그로 남기고, 보관 및 삭제 절차를 정의하세요.
정당한 목적에 필요한 지원되는 공개 데이터만 수집하세요. 비공개 계정, 로그인 장벽, 공개 대상 설정, 그 밖의 제한을 우회하지 마세요. 플랫폼 약관, 개인정보 보호 의무, 지식재산권 규정, 관련 법률을 검토하세요. 기술적 인터페이스가 통합된다고 해서 법적 의무까지 통합되거나 없어지지는 않습니다.
자주 묻는 질문(FAQ)
통합 소셜 미디어 API가 공식 API를 대체하나요?
아니요. SocQ는 지원되는 공개 읽기를 처리합니다. 게시, OAuth 기반 사용자 동작, 비공개 인사이트, 플랫폼 파트너 제품에는 여전히 공식 API가 필요합니다.
27개 플랫폼 모두 정확히 같은 필드를 반환하나요?
아니요. 개념이 일치하는 부분은 정규화된 규칙을 공유하고, 리소스 고유의 필드는 그대로 구분되어 남습니다.
플랫폼마다 API 키가 따로 필요한가요?
SocQ 키 하나로 SocQ 카탈로그 전체를 사용할 수 있습니다. 공식 API나 다른 업체와의 연동에는 여전히 각자의 자격 증명이 필요합니다.
SocQ로 소셜 게시물을 발행할 수 있나요?
아니요. 현재 엔드포인트는 읽기 전용의 공개 데이터 작업입니다.
속도 제한은 어떻게 처리하나요?
애플리케이션에서 SocQ 계정 제한을 지키고, 비동기 작업 상태를 저장하고, 폴링 중에는 백오프하며, 일시적인 실패만 재시도하세요.
AI 에이전트에도 적합한가요?
네. 에이전트가 타입이 지정된 도구, 제한된 입력, 작업 상태 저장, 검증을 사용하고, 후속 조치의 영향이 클 때는 사람의 승인을 거친다면 적합합니다. 클라이언트가 해당 프로토콜을 지원한다면 MCP부터 시작하세요.
현재 카탈로그는 무엇을 다루나요?
소셜 네트워크, 광고 라이브러리, 커머스, 지도, 앱스토어, SEO에 걸쳐 27개 플랫폼과 170개 이상의 엔드포인트를 다룹니다. 최신 목록은 /apis에서 확인하세요.
MULTI-PLATFORM API
공개 Multi-platform URL로 워크플로를 테스트하세요
공개 데이터 입력을 제출하면 출처를 추적할 수 있는 컨텍스트가 포함된 정규화된 레코드를 받을 수 있습니다.
Multi-platform API 살펴보기