브랜드 모니터링브랜드 언급감성 분석평판 관리API 가이드

브랜드 모니터링 API: 감성, 감정, 권위 점수가 포함된 웹 언급 데이터

SocQ의 신규 엔드포인트 2개로 브랜드를 언급하는 웹 페이지를 감성·감정·권위 점수와 함께 수집하고, 전체 언급을 긍정, 부정, 중립으로 나눠 볼 수 있습니다.

SocQ2026년 11월 19일 업데이트약 7분 소요

브랜드 모니터링은 보통 두 가지 질문에서 시작합니다. 웹 어디에서 우리 이야기를 하고 있는지, 그리고 우리를 어떻게 느끼는지입니다. 첫 번째 질문에는 읽고 담당자에게 전달할 수 있는 페이지 단위 데이터가 필요합니다. 두 번째 질문에는 수백만 개의 페이지를 내려받지 않고도 차트로 그릴 수 있는 집계 데이터가 필요합니다.

2026-11-17에 SocQ는 질문마다 엔드포인트 하나씩을 갖춘 Brand Monitoring 플랫폼을 출시했습니다. 이 가이드에서는 각 엔드포인트의 반환 내용, 요청 예시, 가격, 사용 시점을 정리합니다.

빠른 답변: 브랜드, 제품 또는 주제를 query에 담아 POST /v1/brand-monitoring/mentions로 보내면 이를 언급하는 웹 페이지 목록을 감성, 감정, 권위 점수와 함께 받을 수 있습니다. 같은 query를 POST /v1/brand-monitoring/sentiment로 보내면 전체 언급을 감성과 감정별로 나눈 행 하나를 받습니다. 결과는 GET /v1/tasks/{task_id}를 폴링해 읽습니다.

신규 Brand Monitoring 엔드포인트

1 SocQ 크레딧 = $0.005입니다.

엔드포인트반환 내용가격
Brand Mentions API검색어를 언급하는 웹 페이지마다 한 행: URL, 제목, 언급 주변 문단, 작성자, 언어, 국가, 사이트 유형, 감성·감정 점수, 페이지·도메인 권위요청당 10 크레딧($0.05) + 페이지당 0.02 크레딧($0.0001)
Brand Sentiment Analysis API검색어를 언급하는 모든 페이지를 주된 감성과 가장 강한 감정별로 묶은 행 하나. 그룹마다 페이지 수와 주요 사이트, 국가, 언어, 사이트 유형 포함호출당 10 크레딧($0.05)

Brand Mentions는 페이지를 하나도 찾지 못한 경우에도 기본 요금 10 크레딧이 부과됩니다.

인증과 비동기 작업 흐름

모든 SocQ 요청은 API 키로 인증하며, 작업 제출, 작업 상태 조회, 결과 요청에 같은 헤더를 사용합니다.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

모든 수집은 백그라운드 작업으로 실행됩니다.

submit -> task_id -> queued -> running -> succeeded
                                   \-> failed

제출 응답에는 data.task_id와 data.status가 들어 있습니다. 이 ID로 작업을 폴링하세요.

curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=50" \
  -H "Authorization: Bearer $SOCQ_API_KEY"

status가 succeeded이면 응답의 data.results.items에 정규화된 레코드의 첫 페이지가 포함됩니다. limit의 기본값은 50이고 최대 500까지 지정할 수 있으며, has_more가 true이면 results.next_cursor를 cursor로 넘겨 다음 페이지를 읽으세요. 작업이 queued, running, failed 상태인 동안에는 results 없이 작업 메타데이터만 반환됩니다.

제출 본문에 선택 항목인 callback_url을 넣으면 작업이 끝났을 때 SocQ가 작업 요약을 담은 POST를 한 번 보내며, 레코드는 GET /v1/tasks/{task_id}로 읽으면 됩니다. 클라이언트 측 타임아웃이 발생해도 작업은 취소되지 않으므로, 중복 비용을 내지 말고 같은 작업 ID로 조회를 이어가세요. 402는 크레딧이 부족하다는 뜻이고, 429는 키가 속도 또는 크레딧 한도에 도달했다는 뜻입니다.

Brand Mentions API: 나를 언급하는 모든 페이지

Brand Mentions API는 블로그 리뷰, 뉴스 보도, 포럼 스레드, 상품 페이지 등 웹 전반에서 검색어를 언급하는 페이지를 반환합니다. query에는 브랜드, 제품 또는 주제를 최대 100자까지 넣습니다. 구문을 정확히 일치시키려면 큰따옴표로 감싸세요. content_type으로 결과를 news, blogs, message-boards, ecommerce, organization 사이트로 제한할 수 있습니다. results_limit의 기본값은 100이며 1~1,000을 지정할 수 있습니다.

curl -X POST "https://api.socq.ai/v1/brand-monitoring/mentions" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "notion",
    "results_limit": 100
  }'

각 행은 페이지 하나를 설명합니다.

  • 어디서: url, title, domain, language, country(두 글자, WW는 전 세계), 그리고 news, blogs, ecommerce 같은 page_types.
  • 무엇을: 언급 주변 문단인 text, 그리고 제공되는 경우 author_name.
  • 어떤 느낌으로: 01 범위이며 합이 1이 되는 positive, negative, neutral 점수를 담은 sentiment, 그리고 01 범위의 점수 여섯 개(happiness, love, fun, share, sadness, anger)를 담은 emotions.
  • 얼마나 중요한지: content_quality_score(0100), spam_score(0100, 높을수록 스팸 징후가 많음), domain_rank와 page_rank(0~1,000).
  • 언제: 페이지를 마지막으로 읽은 시각인 fetched_at.

권위 점수와 스팸 점수로 대량의 결과를 정렬하면 팀이 권위가 높고 스팸이 적은 페이지부터 읽을 수 있고, 감성 분류로 대응이 필요한 페이지를 표시할 수 있습니다. 페이지 100개는 12 크레딧($0.06)이고, 최대치인 1,000개는 30 크레딧($0.15)입니다. 전체 필드 목록: Brand Mentions 문서.

언론 보도만 살펴보려면 필터를 추가하세요.

{
  "query": "\"notion ai\"",
  "content_type": "news",
  "results_limit": 200
}

Brand Sentiment Analysis API: 숫자 뒤에 있는 분석

Brand Sentiment Analysis API는 개별 페이지를 반환하지 않고 "웹은 우리를 어떻게 느끼는가"라는 질문에 답합니다. 검색어를 언급하는 페이지를 주된 감성별로 묶고, 이와 별도로 가장 강한 감정별로도 묶습니다. 각 그룹에는 포함된 페이지 수와 가장 크게 기여하는 사이트, 국가, 언어, 사이트 유형이 표시됩니다.

curl -X POST "https://api.socq.ai/v1/brand-monitoring/sentiment" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "notion"
  }'

결과 행 하나에는 배열 두 개가 들어 있습니다.

  • sentiments: positive, negative, neutral마다 그룹 하나씩.
  • emotions: happiness, love, fun, share, sadness, anger마다 그룹 하나씩.

모든 그룹에는 label, mentions_count, 그리고 top_domains, countries, languages, page_types가 있으며, 각각은 name과 count의 목록으로 큰 순서대로 정렬됩니다. 이 구조 덕분에 비판이 뉴스 매체에서 나오는지 특정 포럼 한 곳에서 나오는지, 어느 국가가 이를 주도하는지 구분할 수 있습니다. 요청당 비용은 10 크레딧($0.05)입니다. 언급이 수백만 건에 이르는 매우 광범위한 검색어는 분석에 최대 몇 분까지 더 걸리므로 인내심을 갖고 폴링하세요. Brand Sentiment Analysis 문서를 참고하세요.

어떤 엔드포인트를 써야 할까요?

  • 주간 평판 대시보드: 내 브랜드와 각 경쟁사에 대해 Brand Sentiment Analysis를 실행하고 수치를 저장해 시간 흐름에 따라 차트로 그리세요. 브랜드 4개는 실행당 40 크레딧($0.20)입니다.
  • 커뮤니케이션팀의 대응 대기열: content_type을 news 또는 message-boards로 설정해 Brand Mentions를 실행한 뒤 negative 감성과 domain_rank 순으로 정렬하세요.
  • 급증 원인 조사: 감성 수치가 움직이면 부정 그룹의 top_domains로 어느 사이트가 원인인지 확인하고, Brand Mentions로 해당 페이지를 가져오세요.

두 엔드포인트 모두 위의 다섯 가지 사이트 유형에 속한 웹 페이지를 대상으로 합니다. 소셜 네트워크의 게시물과 댓글은 통합 소셜 미디어 API 가이드에 소개된 플랫폼 엔드포인트를 사용하세요. AI 어시스턴트가 내 브랜드에 대해 무엇을 말하는지는 AI 검색 API 가이드를 참고하세요.

자주 묻는 질문(FAQ)

브랜드 모니터링 API란 무엇인가요?

브랜드, 제품 또는 주제가 어디에서 언급되는지, 그 언급이 어떤 느낌인지 찾아 주는 API입니다. SocQ의 브랜드 모니터링 API는 감성, 감정, 권위 점수가 포함된 페이지 단위 언급과 함께 감성·감정 집계 분석을 반환합니다.

정확한 구문을 일치시키려면 어떻게 하나요?

query 안에서 큰따옴표로 감싸세요. 예를 들어 JSON에서는 "\"notion ai\""처럼 씁니다. 검색어는 최대 100자까지 입력할 수 있습니다.

어떤 종류의 사이트를 다루나요?

페이지는 news, blogs, message-boards, ecommerce, organization으로 분류됩니다. Brand Mentions는 content_type으로 이 중 한 유형으로 제한할 수 있습니다.

아무것도 찾지 못해도 과금되나요?

Brand Mentions는 페이지를 찾지 못해도 기본 요금 10 크레딧을 부과하며, 반환된 페이지마다 0.02 크레딧이 추가됩니다. Brand Sentiment Analysis는 요청당 10 크레딧입니다.

감성 분석 작업이 아직도 실행 중인 이유는 무엇인가요?

언급이 수백만 건에 이르는 매우 광범위한 검색어는 분석에 최대 몇 분까지 더 걸립니다. 같은 task_id로 계속 폴링하고, 다시 제출하지 마세요.

BRAND MONITORING API

공개 Brand Monitoring URL로 워크플로를 테스트하세요

공개 데이터 입력을 제출하면 출처를 추적할 수 있는 컨텍스트가 포함된 정규화된 레코드를 받을 수 있습니다.

Brand Monitoring API 살펴보기