Universal Search API

통합 소셜 검색 API

Name: Universal Search Data API
Brand: SocialCrawl
Availability: InStock

SocialCrawl API 키로 한 쿼리를 여러 소셜·리서치 소스에 동시에 펼칩니다. 순위·융합 결과를 단일 JSON 봉투로 받습니다. 호출은 크레딧으로 과금됩니다.

문서 보기 동작 방식 직접 호출

/v1/search

활성 메타 엔드포인트는 3개입니다. everywhere, forums, news입니다.

GET /v1/search/everywhere
GET /v1/search/forums
GET /v1/search/news

Universal Search 엔드포인트

/v1/search 아래 동급 메타 엔드포인트는 3개입니다. 교차 플랫폼 everywhere, 포럼 레인, 다국가 뉴스 플랜입니다. 소셜·포럼 소스가 우선이며 단독 오픈 웹 SERP가 아닙니다.

전체 소셜 검색

20 크레딧

/v1/search/everywhere

한 쿼리를 소셜·리서치 소스에 병렬로 펼칩니다. 플래너, 융합, 재순위, 클러스터를 수행합니다. 보강 가능한 게시물에는 상위 댓글이 포함될 수 있습니다. JSON 또는 SSE입니다. 호출당 고정 20 크레딧입니다.

query, lookback_days, from_date, to_date, sources, exclude

포럼 검색

10 크레딧

/v1/search/forums

Reddit, Hacker News, 한국 포럼(지식iN, 카페) 스레드를 융합합니다. 핵심 스레드에는 기본적으로 상위 댓글이 붙습니다. 고정 10 크레딧이며 커버리지 실패 시 부분 환불 경로가 있습니다. 동기 JSON입니다.

query, sources, exclude, comments, timeframe, lookback_days

다국가 뉴스

종량제, 2-14 크레딧

/v1/search/news

각도를 계획하고 국가별로 지역화한 뒤 google_news 레그(최대 12)를 펼칩니다. 레그 출처가 있는 중복 제거 NewsArticle 행을 반환합니다. JSON 또는 SSE입니다. 기본 2 크레딧에 기사 반환 레그당 1 크레딧입니다.

query, countries, time_range, from, to, publisher, depth, max_legs

Universal Search API3개 엔드포인트 지원

문서 보기

질의 하나를 Reddit, X, YouTube, TikTok, Instagram 등에서 동시에 돌려 순위와 군집을 매긴 결과 하나로, 상위 댓글까지 붙여 반환합니다.

플랫폼마다 검색 엔드포인트를 직접 부르는 대신 한 주제의 반응을 한 번에 볼 때 사용하세요.

GET/v1/search/everywhere?query=kanye+west&lookback_days=30&sources=reddit%2Cyoutube%2Cgithub

query

query · Search query (1–512 chars)

$ curl https://www.socialcrawl.dev/v1/search/everywhere?query=kanye+west&lookback_days=30&sources=reddit%2Cyoutube%2Cgithub \
    -H "x-api-key: sc_YOUR_API_KEY"

— · 대기 중

// 실제 실행에는 API 키가 필요합니다. "실행해보기"를 누르면 예시 응답을 표시합니다

Universal Search API 동작

Universal Search는 SocialCrawl 메타 표면입니다. API 키로 GET /v1/search/… 를 호출하고 고정 또는 종량 비용을 쓰며 하나의 봉투를 받습니다. 팬아웃에 플랫폼별 OAuth는 필요 없습니다.

호출 인증

x-api-key 헤더에 키를 보냅니다. Reddit, TikTok, Google Trends, Tavily를 포함한 카탈로그 전 구간에 같은 키를 사용합니다.

GET과 쿼리 파라미터

세 라우트 모두 GET입니다. query와 레인 옵션(lookback, sources, countries, timeframe)을 전달합니다. 과금 전에 검증하며 알 수 없는 소스 이름은 400입니다.

크레딧 과금

everywhere는 고정 20, forums는 고정 10(커버리지 실패 시 부분 환불), news는 종량 2-14(계획 기본 + 성공 레그)입니다. 적용 가능한 캐시 히트는 0입니다. 하드 실패는 환불됩니다.

JSON 봉투

응답은 success, data, credits_used, credits_remaining, request_id, cached입니다. everywhere와 news는 Accept: text/event-stream으로 진행형 청크를 지원합니다.

연동 순서

대부분 제품은 넓게 everywhere로 시작한 뒤 스레드 품질이 필요하면 forums, 보도 신호가 필요하면 news로 내려갑니다.

01Everywhere

GET /v1/search/everywhere?query=…

융합 items[], clusters, 소스별 요약, 선택적 top_comments입니다.

한 호출로 여러 플랫폼 검색과 클라이언트 병합을 대체합니다.

02Forums

GET /v1/search/forums?query=…

융합 포럼 items[], raw 버킷, 클러스터, question_share 계열 지표입니다.

VoC와 지원 언어는 짧은 게시물만이 아니라 긴 스레드에 있습니다.

03News

GET /v1/search/news?query=…&countries=…

plan, query_source가 있는 legs[], 중복 제거 NewsArticle items[]입니다.

플래너를 직접 만들지 않고 다국가 Google News 레그를 씁니다.

요청

GET /v1/search/everywhere
  ?query=social+media+api
  &lookback_days=30
Host: www.socialcrawl.dev
x-api-key: sc_your_api_key_here
Accept: application/json

# SSE stream
# Accept: text/event-stream

응답 봉투

{
  "success": true,
  "data": {
    "items": [],
    "clusters": [],
    "sources": {}
  },
  "credits_used": 20,
  "credits_remaining": 9999,
  "request_id": "req_…",
  "cached": false
}

data 형태

각 레인은 안정적인 메타 봉투를 유지합니다. 필드 이름이 일관되어 에이전트와 대시보드가 세 라우트에서 파서를 공유할 수 있습니다.

Analytics (everywhere)everywhere

순위·융합 items[], clusters[], sources/items_by_source, 보강 가능한 게시물의 top_comments

Analytics (forums)forums

융합 items[], 소스별 raw 버킷, 스레드 클러스터, 계산 블록(question_share, top_communities)

Analytics (news)news

plan과 legs[] 출처, 국가·각도 맥락이 있는 중복 제거 NewsArticle items[]

게이트웨이

/v1 플랫폼 라우트와 같은 게이트웨이입니다. 메타 fetcher가 플래너, 팬아웃, 융합, 과금 정산을 SocialCrawl 안에서 수행합니다.

엣지 수신

Next.js catch-all이 Hono 소셜 API로 들어갑니다. request_id를 발급하고 키를 인증한 뒤 키 단위 한도와 동시성을 적용합니다.

검증 후 차감 또는 홀드

레지스트리에서 search/everywhere, forums, news를 찾습니다. 파라미터가 먼저 검증됩니다. 잘못된 입력은 400이며 과금하지 않습니다. 고정 레인은 선차감하고 news는 상한을 홀드한 뒤 실제 레그로 정산합니다.

계획·팬아웃·융합

everywhere와 forums는 다중 소스 팬아웃과 융합·클러스터를 수행합니다. news는 각도를 계획하고 국가별로 지역화한 뒤 google_news 레그를 호출합니다. Accept가 text/event-stream이면 everywhere와 news가 중간 청크를 스트림합니다.

정규화 후 반환

결과는 메타 Analytics 봉투에 담기고 크레딧이 정산됩니다. news 미사용 상한과 빈 레그 환불을 포함합니다. 성공 봉투는 빌링 감사에 남깁니다.

과금 규칙

everywhere 라이브 호출은 고정 20 크레딧입니다.
forums 라이브 호출은 고정 10 크레딧입니다.
news는 종량제 2-14 크레딧입니다(기본 2 + 성공 레그당 1).
news의 빈 레그와 실패 레그는 과금하지 않습니다.
forums 커버리지 실패 시 부분 환불 경로가 있습니다.
적용 가능한 캐시 히트는 0 크레딧입니다.
잘못된 파라미터는 400이며 과금하지 않습니다.
잔액이 없으면 402이며 과금하지 않습니다.
SSE는 everywhere와 news에서 가능합니다(forums는 동기 JSON).

데이터 수집

Universal Search는 오픈 웹만이 아니라 소셜·리서치 소스로 팬아웃합니다. Exa, Tavily, Firecrawl을 단독으로 쓸 때와 다른 지점입니다.

API에서의 Universal Search

플랫폼, 포럼, 다국가 뉴스를 한 쿼리로 연구합니다. 융합된 소셜 신호가 필요한 에이전트, 대시보드, VoC 작업용이며 단일 SERP 페이지 대체가 아닙니다.

업스트림

내부 메타 fetcher가 등록된 플랫폼 엔드포인트를 병렬 호출합니다. everywhere는 소셜·리서치 소스, forums는 Reddit·Hacker News·한국 포럼, news는 국가·각도별 google_news 레그를 계획합니다.

응답 형태

융합 items, 클러스터 또는 legs, 크레딧 필드를 담은 통합 JSON 봉투를 반환합니다. everywhere와 news는 SSE로 스트림할 수 있습니다. forums는 핵심 스레드 인라인 댓글이 있는 동기 JSON입니다.

미제공 항목

전체 웹 크롤 스위트 대체가 아닙니다. 플랫폼 쓰기 접근이 없습니다. forums는 v1에서 동기 전용입니다(SSE 미지원). news는 Google News 에디션이며 임의 HTML 스크래프가 아닙니다.

필드 매핑

per-platform posts + comments→ items[] + top_comments소셜 소스 게시물과 선택적 top_comments 융합

forum threads→ fused items[] + raw buckets포럼 스레드 융합과 소스별 raw 버킷

google_news legs→ deduped NewsArticle rowsgoogle_news 레그를 중복 제거 NewsArticle 행으로 병합

이 API의 활용 분야

이 API가 가장 많이 사용되는 작업입니다.

3active Universal Search endpoints in the registry

20 / 10 / 2-14everywhere, forums, news 크레딧 사다리

교차 플랫폼 주제 스윕과 다국가 뉴스

넓게 볼 때는 everywhere, 긴 토론이 필요할 때는 forums, 국가별 보도가 필요할 때는 news를 사용합니다. 긴 everywhere·news 실행에서 SSE가 사용됩니다. 소셜 우선 팬아웃과 everywhere 20·forums 10 고정 요금, 종량 다국가 뉴스를 제공합니다. 오픈 웹 도구만으로는 이 소셜 축을 갖지 않습니다.

everywhere는 다중 소스 파이프라인이라 단일 플랫폼 읽기보다 길며, 종종 수 초 이상이고 SSE로 진행 상황을 받습니다. forums는 동기입니다. news는 레그 수에 비례합니다.

Universal Search API 활용 사례

Universal Search 데이터가 가장 많이 쓰이는 작업입니다. 각 항목에서 엔드포인트 순서와 과금 방식을 확인합니다.

소셜 리스닝아래 모든 소스로 질의 하나를 한 번에 확장합니다.

시장 조사조사 질문 하나를 포럼과 커뮤니티, 웹으로 한 번에 확장합니다.

뉴스·공개출처 모니터링아래 모든 소스로 질의 하나를 한 번에 확장하며 조회 기간과 선택적 소스 필터를 지원합니다.

활용 사례

이 데이터를 활용하는 대표적인 방식과 각 방식에서 주로 사용하는 스택입니다.

리서치·VoC 팀

Python, 노트북, BI

플랫폼 전반 브랜드·제품 언어는 everywhere, 스레드 깊이가 필요하면 forums를 사용합니다.

뉴스·OSINT 잡

Node, 워커, SSE 클라이언트

국가 CSV로 search/news를 호출합니다. plan_refined 후 레그가 정착하는 대로 스트림합니다.

에이전트 빌더

Go, LLM 도구, Explorer

플랫폼 도구 N개 대신 메타 호출 1회를 사용합니다. 융합 후 심화 라우트도 같은 SocialCrawl 키입니다.

호출 예시

everywhere는 고정 20 크레딧, forums는 고정 10 크레딧, news는 2-14 크레딧 종량제입니다. everywhere와 news SSE는 Accept를 text/event-stream으로 설정합니다.

curl "https://www.socialcrawl.dev/v1/search/everywhere?query=social+media+api&lookback_days=30" \
  -H "x-api-key: sc_your_api_key_here"

curl "https://www.socialcrawl.dev/v1/search/forums?query=airpods+pro+3+battery&comments=on" \
  -H "x-api-key: sc_your_api_key_here"

SocialCrawl Universal Search

카탈로그와 같은 API 키

플랫폼 문서 API 키 받기

엔드포인트

Universal Search API는 어떤 데이터를 돌려주나요

모든 엔드포인트가 같은 응답 구조의 JSON을 보내드려요. 엔드포인트가 해당 지표를 지원하고 계산에 필요한 원본 값이 있을 때만 참여율·콘텐츠 카테고리 같은 계산 필드가 포함돼요.

EverywhereUniversal social search across 14 platforms ForumsFused forum search across Reddit, Hacker News, and Naver 지식iN/카페 — with top comments inline on hero threads by default.NewsPlanned multi-country news search: one query, localized and fanned out across Google News editions in a single call.

비교

SocialCrawl과 플랫폼별 직접 연동, 뭐가 다른가요?

같은 Universal Search 데이터를 받는 두 가지 방법을 나란히 비교했어요. 인증부터 비용까지 한눈에 확인해 보세요.

항목	SocialCrawl	플랫폼별 직접 연동
호출당 플랫폼 수	GET 한 번으로 14개 플랫폼(해시태그 모드에선 최대 17개 소스)을 검색해요	플랫폼마다 연동 하나씩, 클라이언트 14개를 직접 만들고 돌려야 해요
인증	x-api-key 하나로 전체 팬아웃을 처리해요	플랫폼마다 키·쿼터·심사 대기열을 따로 관리해야 해요
결과 융합	가중 RRF에 LLM 재정렬·클러스터링까지 기본으로 들어 있어요	결과 병합, 중복 제거, 순위 로직을 전부 직접 설계해야 해요
스트리밍	JSON 또는 플랫폼별 결과가 도착하는 대로 오는 SSE 청크를 골라 써요	스트리밍 계층을 모든 클라이언트 위에 직접 얹어야 해요
요금	호출당 20 크레딧 정액, 결과가 없으면 자동 환불돼요	청구서 14장과 플랫폼별 요청 한도를 따로 챙겨야 해요
유지보수	모든 커넥터를 SocialCrawl이 하나의 계약 뒤에서 관리해요	플랫폼이 바뀔 때마다 연동 중 하나가 깨져요

호출당 플랫폼 수

SocialCrawl

GET 한 번으로 14개 플랫폼(해시태그 모드에선 최대 17개 소스)을 검색해요

플랫폼별 직접 연동

플랫폼마다 연동 하나씩, 클라이언트 14개를 직접 만들고 돌려야 해요

인증

SocialCrawl

x-api-key 하나로 전체 팬아웃을 처리해요

플랫폼별 직접 연동

플랫폼마다 키·쿼터·심사 대기열을 따로 관리해야 해요

결과 융합

SocialCrawl

가중 RRF에 LLM 재정렬·클러스터링까지 기본으로 들어 있어요

플랫폼별 직접 연동

결과 병합, 중복 제거, 순위 로직을 전부 직접 설계해야 해요

스트리밍

SocialCrawl

JSON 또는 플랫폼별 결과가 도착하는 대로 오는 SSE 청크를 골라 써요

플랫폼별 직접 연동

스트리밍 계층을 모든 클라이언트 위에 직접 얹어야 해요

요금

SocialCrawl

호출당 20 크레딧 정액, 결과가 없으면 자동 환불돼요

플랫폼별 직접 연동

청구서 14장과 플랫폼별 요청 한도를 따로 챙겨야 해요

유지보수

SocialCrawl

모든 커넥터를 SocialCrawl이 하나의 계약 뒤에서 관리해요

플랫폼별 직접 연동

플랫폼이 바뀔 때마다 연동 중 하나가 깨져요

자주 묻는 질문

API, 요금제, 기능에 대한 질문과 답변입니다.

문의하기

소셜 미디어 검색 API가 뭔가요?

플랫폼마다 들어가서 일일이 검색하는 대신, 코드 한 줄로 소셜 플랫폼을 검색하게 해 주는 API예요. SocialCrawl의 GET /v1/search/everywhere는 검색어 하나를 레딧, X, 유튜브, 틱톡, 인스타그램, 해커뉴스, 폴리마켓, 깃허브, 스레드, 핀터레스트, 퍼플렉시티, 태빌리, 링크드인, 럼블 14개 플랫폼에 동시에 뿌리고 하나의 정리된 결과로 돌려드려요.

유니버설 검색 파이프라인은 어떻게 동작하나요?

LLM 플래너가 검색어를 플랫폼별 하위 질의로 다듬고, 최대 17개 소스에 병렬로 검색을 보낸 뒤, 가중 RRF로 결과를 합치고 LLM이 다시 순위를 매겨 클러스터로 묶어 드려요. 결과마다 참여도, 최신성, 소스 품질 신호와 게시물의 실제 인기 댓글이 함께 와요.

어떤 플랫폼을 검색할 수 있나요?

레딧, X(AI 검색), 유튜브, 틱톡, 인스타그램, 해커뉴스, 폴리마켓, 깃허브, 스레드, 핀터레스트, 퍼플렉시티, 태빌리, 링크드인, 럼블까지 14개 플랫폼이에요. 해시태그 모드에서는 틱톡, 인스타그램, 유튜브에 해시태그 검색이 하나씩 더 붙어서 최대 17개 소스까지 늘어나요.

유니버설 검색은 요금이 얼마인가요?

몇 개 플랫폼이 응답했는지와 상관없이 호출당 20 크레딧 정액이에요. 모든 소스가 실패하거나 결과가 하나도 없으면 20 크레딧이 자동으로 환불돼요. 새 계정에는 신용카드 없이 100 크레딧이 무료로 제공돼요.

결과를 스트리밍으로 받을 수 있나요?

네, Accept: text/event-stream 헤더를 보내면 타입이 정의된 SSE 청크로 와요. 가장 느린 소스를 기다릴 필요 없이 플랫폼별 결과가 도착하는 대로 화면에 띄울 수 있어요. 기본값인 application/json은 동기 응답 하나로 정리돼서 와요.

Exa나 Tavily 같은 검색 API와는 뭐가 다른가요?

그 API들은 웹 문서를 검색하지만 SocialCrawl은 소셜 플랫폼 자체를 검색해요. 레딧 추천 댓글, 유튜브 인기 댓글, 깃허브 이슈 토론처럼 실제 게시물과 사람들의 반응이 참여도 신호와 함께 와요. 플랫폼에 '관한' 웹 페이지가 아니라 플랫폼 '안의' 데이터예요.

모든 소셜 미디어를 한 번에 검색하는 가장 좋은 방법은 뭔가요?

GET /v1/search/everywhere 호출 한 번이면 돼요. 레딧, X, 유튜브, 틱톡, 인스타그램 등 14개 플랫폼에 병렬로 검색을 보내고, 결과를 합쳐 순위를 매긴 뒤 클러스터로 정리해 드려요. 요금은 호출당 20 크레딧 정액이고, 결과가 하나도 없으면 자동으로 환불돼요.

Universal Search 데이터 스크래핑, 법적으로 괜찮을까요?

SocialCrawl은 누구나 볼 수 있는 공개 Universal Search 데이터만 돌려드리고, 로그인이 필요한 비공개 콘텐츠에는 접근하지 않아요. 다만 실제 적법성은 활용 목적과 국가별 법률에 따라 달라져요. Universal Search 이용약관과 GDPR·CCPA 같은 개인정보 보호 법규를 지키는 책임은 이용자에게 있어요. 이 답변은 일반 안내일 뿐, 법률 자문은 아니에요.

Universal Search 스크래핑 API와 공식 Universal Search API는 뭐가 다른가요?

SocialCrawl은 앱 심사나 승인 대기가 없어요. 가입 직후 x-api-key 하나로 Universal Search 엔드포인트를 바로 호출할 수 있고, 응답은 다른 모든 플랫폼과 같은 통합 스키마로 와요. 요금도 플랫폼별 쿼터 대신 크레딧 하나로 계산해요. 글 게시 같은 쓰기 작업이 필요하다면 공식 API가 맞아요 — SocialCrawl은 읽기 전용 데이터만 다뤄요.

AI에게 SocialCrawl을 물어보세요

ChatGPT에 물어보기 Perplexity에 물어보기 Gemini에 물어보기 Claude에 물어보기 Grok에 물어보기

Universal Search API 레퍼런스 문서 보기

🤖 AI 에이전트나 LLM이신가요? 이 페이지를 markdown으로 읽어보세요