통합 API소셜 미디어 API개발자 가이드

통합 소셜 미디어 API: 공개 소셜 데이터를 하나의 API로

API 키 하나, 작업 모델 하나, 정규화된 스키마 하나로 27개 플랫폼의 공개 소셜·광고·커머스·지도·앱스토어·SEO 데이터를 수집하세요.

SocQ2026년 11월 9일 업데이트약 12분 소요

제품에 두 번째 소셜 플랫폼을 붙인다고 해서 연동 작업이 딱 두 배로 늘어나는 경우는 드뭅니다. 네트워크마다 인증 방식, 리소스 용어, 응답 구조, 페이지네이션 방식, 오류 분류, 유지보수 일정이 모두 다르기 때문입니다. 연동이 27개면 서로 다른 시스템 27개를 관리해야 할 수도 있습니다.

SocQ 소셜 미디어 API는 공개 데이터를 API 키 하나, 비동기 작업 워크플로 하나, 정규화된 레코드 모델 하나로 제공합니다. 현재 카탈로그에는 소셜 네트워크, 광고 라이브러리, 커머스, 지도, 앱스토어, SEO까지 27개 플랫폼에 걸쳐 170개가 넘는 엔드포인트가 있습니다.

SocQ 공개 데이터 카탈로그

빠른 답변: 리소스가 요구하는 입력값으로 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공개 앱 상세 정보, 순위, 리뷰
SEOSEO 키워드 및 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, 연결 계정 제공업체, 라이선스를 받은 데이터셋일 수도 있고, 아예 수집하지 않는 것일 수도 있습니다.

단일 플랫폼에서 카탈로그로 마이그레이션하기

  1. 소스를 추가하기 전에 정규화된 내부 엔벨로프를 정의합니다.
  2. 가치가 높은 리소스 하나를 먼저 연동하고 원본 응답을 보존합니다.
  3. ID, 타임스탬프, 지표, 미디어, null 처리를 검증합니다.
  4. 같은 작업 워커로 두 번째 플랫폼이나 카테고리를 추가합니다.
  5. 원본 고유의 어댑터는 검증 경계에 둡니다.
  6. 고정된 표본으로 기존 파이프라인과 새 파이프라인을 병렬 실행합니다.
  7. 채택된 고유 레코드, 최신성, 비용을 비교합니다.
  8. 단계적으로 마이그레이션하고 롤백 경로를 유지합니다.

데이터의 의미, 관찰 가능성, 장애 처리가 실제로 표준화된 뒤에야 플랫폼 추가가 설정 작업으로 바뀝니다.

보안, 개인정보, 책임 있는 사용

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 살펴보기