Trend Finder 이슈 키워드 조회 API는 “이 키워드 주변에서 최근 무슨 이슈가 있었나”를 알고 싶을 때 사용합니다. Google 자동완성(서제스트) 데이터의 이슈성을 추적하고, 검색결과(SERP) 데이터를 분석하여 일간 주목받는 키워드를 제공합니다. 마케팅 캠페인, 콘텐츠 기획, 광고 전략에서 관심 주제, 이슈 요약, 키워드 그룹, 출처 링크를 확인해 보세요.
핵심 특징 요약
키워드를 입력하면, 구글 자동완성 키워드·검색결과(SERP) 기반의 일별 이슈 인덱스에서 요약문·핵심 구문·출처 링크·토픽·이슈 점수를 반환합니다. 기본 최신 2주(14일), 최대 최신 1년(365일)까지 조회 가능합니다.
| 항목 | 상세 |
| 엔드포인트 | POST /trend_finder/issue_list |
| 요청 키워드 수 | 1개 |
| 반환 형식 | data: objects[] (이슈 항목 배열) |
| 반환 기본 개수 | 1,000 |
| 반환 개수 (선택) | 1,000 ~ 최대 10,000 |
| 정렬 | score (이슈 점수) / date (기록일) 기준 (오름차순/ 내림차순) |
| 콘텐츠 유형 필터 | news / video / web 중 1개 지정 가능 (미지정시 전체 반환) |
| 지원 국가(gl) | kr (한국) / jp (일본) / us (미국) |
| 과금 방식 | 입력 키워드 1개당 50 크레딧 + 출력 이슈 항목당 2 크레딧 |
정기 수집시 주의 사항 : 응답 필드에 “index_date”를 제공하고 있습니다. 이는 이슈가 속한 일별 인덱스 날짜입니다. “index_data” 기준으로 수집하세요. 보통 키워드별 배치 시각이 다를 수 있으므로 매일 전날(D-1) index_date를 확정분으로 수집 관리하는 편이 안전합니다. (참고 : 최신 이슈를 수집할 때에는 안전하게 period_days: 2 정도로 받은 뒤, 클라이언트에서 index_date == D-1로 걸러내면 좋습니다)
이슈 키워드 조회 API(/trend_finder/issue_list) 는 언제 사용하나
| 사용자 질문 | 사용 features | 확인할 필드 |
|---|---|---|
| 브랜드/제품 키워드에 최근 무슨 이슈가 있나? | 기본값(period_days 14, sort score) | keyword, summary, issue_score |
| 언론에 보도된 이슈만 보고 싶다 | content_type: "news" | summary, source_links, recorded_at |
| 영상·숏폼에서 뜨는 이슈는? | content_type: "video" | keyword, key_phrase, source_links |
| 가장 최근 기록된 이슈부터 보고싶다 | sort: "date", order: "desc" | recorded_at, index_date, freshness |
| 반짝 이슈인가, 지속되는 트렌드인가? | period_days 14 → 90 → 365 비교 | total, index_date 분포 |
| 한국·일본·미국의 이슈를 비교하고 싶다. | gl: kr / jp / us 국가별 개별 호출 | keyword, summary, total |
각 API별 역할 분담
| API | 답하는 질문 |
|---|---|
/keyword_info | 검색량이 얼마이고 어떻게 변해 왔나 (수치) |
/serp | 지금 검색결과 화면이 어떻게 구성돼 있나 (현재 스냅샷) |
/trend_finder/issue_list | 최근 어떤 이슈가 있었고 근거는 무엇인가 (콘텐츠) |
요청 파라미터 (Request)
파라미터 상세
| 파라미터 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
keyword | string | Y | – | 시드 키워드 1개 (최소 1자) |
gl | string | Y | – | 국가 코드: kr / jp / us |
period_days | integer | N | 14 | 최신 N일의 일별 이슈 인덱스 검색 (1~365) |
limit | integer | N | 1000 | 반환 이슈 항목 수 (1~10,000) |
sort | string | N | score | score: 이슈 점수 / date: 기록일 |
order | string | N | desc | desc / asc |
content_type | string | null | N | null(전체) | 최상단 콘텐츠 유형 필터: news / video / web |
파라미터 사용 시 주의사항
- ⚠️ limit 기본값이 1,000이므로 미지정 시 최대 1,000건이 반환되고 최대 2,050 크레딧(50 + 1,000×2)이 과금될 수 있습니다. 필요한 만큼 지정하세요.
- 입력 키워드의 띄어쓰기에 따라 결과가 달라집니다.
- 영문 키워드는 소문자로 요청하는 것을 권장합니다. 응답의 key_phrase도 소문자로 정규화돼 있습니다.
요청 예시
최소 요청:
{
"keyword": "아이폰",
"gl": "kr"
}모든 옵션 지정(최근 30일 뉴스 이슈, 최신순 5건):
{
"keyword": "아이폰",
"gl": "kr",
"period_days": 30,
"limit": 5,
"sort": "date",
"order": "desc",
"content_type": "news"
}응답 데이터 구조 (Response)
{
"result": "OK",
"reason": "SUCCESS",
"source": "listeningmind-data-api",
"version": "1.0.6",
"user_type": "data",
"request_at": "2026-09-21T02:53:11.884Z",
"request_detail": {
"keyword": "아이폰", "gl": "kr", "period_days": 14,
"limit": 5, "sort": "score", "order": "desc"
},
"cost_detail": {
"input_cost": 50, "input_count": 1, "input_total_cost": 50,
"output_cost": 2, "output_count": 5, "output_total_cost": 10,
"total_cost": 60
},
"used_credits": 16670908,
"total": 1736,
"data": [
{
"keyword": "애플",
"issue_score": 97.1298,
"content_type": "web",
"topic": "애플",
"category": "trend",
"freshness": 0.9676,
"summary": [
"애플은 새로운 폴더블폰 '아이폰 듀오'를 공개할 예정입니다.",
"이 폴더블폰은 내달 23일에 국내에서 출시될 예정입니다.",
"애플은 새로운 아이폰 18 프로와 애플 워치 시리즈 12를 공개할 예정입니다."
],
"key_phrase": ["애플", "아이폰 듀오", "폴더블폰", "ai시대", "가변 조리개", "a20 프로"],
"source_links": [
"https://www.apple.com/kr/",
"https://zdnet.co.kr/view/?no=20260910062532",
"https://www.etnews.com/20260910000004"
],
"recorded_at": "2026-09-10 20:08:28",
"index_date": "2026-09-10"
}
]
}응답 최상위 필드
| 필드 | 타입 | 설명 |
|---|---|---|
result | string | OK / FAILED |
reason | string | 상태 설명 (성공 시 SUCCESS) |
version | string | API 버전 |
request_at | string | 요청 시각, UTC 기준 ISO 8601 |
request_detail | object | 기본값이 채워진 실제 적용 파라미터 |
cost_detail | object | 이번 호출의 과금 내역 (아래 표) |
used_credits | integer | 계정 누적 사용 크레딧 (실측, 이번 호출분이 아님) |
total | integer | 조건에 매칭된 이슈 총 개수 (limit보다 클 수 있음) |
data | array | 이슈 항목 목록, 매칭 없으면 [] |
data[] 이슈 항목 필드
| 필드 | 타입 | 설명 |
|---|---|---|
keyword | string | 이슈 키워드. 시드와 다를 수 있음 (예: 시드 아이폰 → 애플, 아이폰 두요) |
issue_score | number | 이슈 점수. 높을수록 이슈성이 큼 |
content_type | string | 해당 키워드 SERP 최상단의 지배적 콘텐츠 유형: news / video / web |
topic | string | null | 이슈 토픽. null일 수 있음 |
category | string | null | 이슈 카테고리. 실측에서는 trend 또는 null만 관찰 |
freshness | number | 검색결과 게시일 기반 최신성 지표. 실측 범위 0~1 |
summary | string[] | 키워드의 구글 SERP를 AI가 요약한 문장 (실측 대부분 3문장) |
key_phrase | string[] | 이슈 핵심 구문 (영문은 소문자) |
source_links | string[] | 근거 출처 URL. 실측 약 17~38개 |
recorded_at | string | 이슈 기록 시각 (YYYY-MM-DD HH:MM:SS, 시간대 미표기) |
index_date | string | 이슈가 속한 일별 인덱스 날짜 |
cost_detail 과금 필드
| 필드 | 설명 | 실측 예 (limit 5) |
|---|---|---|
input_cost | 키워드 1개당 입력 과금 | 50 |
input_count | 과금된 입력 키워드 수 (매칭 0건이면 0) | 1 |
output_cost | 이슈 항목 1개당 출력 과금 | 2 |
output_count | 실제 반환된 항목 수 (total이 아님) | 5 |
total_cost | input_total_cost + output_total_cost | 60 |
주요 지표 해석
점수는 같은 요청 안에서 상대 비교용으로 쓰고, 이슈 자체는 summary와 source_links로 확인합니다.
| 지표 | 실측 범위 | 해석 |
|---|---|---|
issue_score | 1.29 ~ 97.13 | 같은 결과 안에서 이슈성 순위. 키워드간·기간간 절대 비교는 주의 |
freshness | 0 ~ 0.97 | 1에 가까울수록 SERP가 최근 게시물로 채워진 상태. 0은 상시 검색어형(예: 제품 정보·쇼핑)에서 자주 관찰 |
content_type | news / video / web | news는 언론 보도형 이슈, video는 영상·숏폼 확산형 이슈 |
total | 0 ~ 294,858 | 매칭 규모. 값이 비정상적으로 크면 시드가 너무 일반적이라는 신호 |
index_date 분포 | – | 여러 날짜에 걸쳐 반복 등장하면 지속 이슈, 하루에 몰리면 단발 스파이크로 볼 수 있음 |
예시 해석 (실측, kr · 14일): 시드 아이폰은 1,736건이 매칭됐고, 상위 5건 중 4건이 9월 9~12일 ‘아이폰 듀오(폴더블)’ 공개·가격 이슈였습니다. 오타 키워드 아이폰 두요도 같이 잡힙니다.
활용 시나리오별 파라미터 조합
| 목적 | keyword | 주요 파라미터 | 확인할 필드 |
|---|---|---|---|
| 브랜드 이슈 모니터링 (주간) | 브랜드명 1단어 | period_days: 7, sort: score, limit: 20 | summary, source_links |
| PR·위기 대응 | 브랜드명 | content_type: news, sort: date | recorded_at, source_links |
| 콘텐츠 소재 발굴 | 카테고리 핵심어 | content_type: video, period_days: 30 | keyword, key_phrase |
| 신제품 출시 반응 추적 | 제품명 | period_days: 30, sort: date, order: asc | index_date, issue_score |
| 단발 vs 지속 판단 | 이슈 키워드 | period_days 14 / 90 / 365 비교 | total, index_date 분포 |
| 국가별 비교 | 현지어 키워드 | gl만 바꿔 3회 호출 | keyword, summary |
자주 묻는 질문 (FAQ)
Q1. 실시간 데이터인가요? 실시간 호출 결과 대신 일별로 구축된 이슈 인덱스를 조회합니다. 호출시 가장 최근 index_date는 당일이 될 수 있습니다.
Q2. 결과가 0건이면 어떻게 하나요? 오류가 아니라 ‘해당 기간에 매칭 이슈 없음’ 결과입니다. period_days를 30 → 90 → 365로 늘려 재조회하고, 붙여쓴 복합어라면 띄어쓰기를 바꿔 보세요. 0건 응답은 과금되지 않습니다.
Q3. 결과에 시드와 무관한 이슈가 섞여요. 이슈 키워드는 단어 또는 매칭으로 추정한 값입니다. 핵심 단어 1개로 요청하고 받은 뒤 key_phrase로 필터링하세요.
Q4. 과금은 어떻게 계산되나요? 매칭이 있으면 입력 키워드당 50 + 반환 키워드당 2 크레딧입니다. total이 아니라 실제 반환 건수(output_count) 기준이므로 limit으로 비용을 제어합니다.
Q5. total과 data 건수가 다릅니다. total은 전체 매칭 수, data는 limit만큼 잘라낸 목록입니다.
Q6. 여러 키워드를 한 번에 요청할 수 있나요? 없습니다. keyword는 문자열 1개만 입력할 수 있습니다. 키워드별로 따로 호출하세요.
Q7. 여러 국가를 한 번에 볼 수 있나요? 없습니다. gl을 바꿔 국가별로 호출하고, 국가마다 현지어 키워드를 쓰는 것이 좋습니다.
Q8. 얼마나 오래된 데이터까지 조회되나요? 최대 365일입니다.
Q9. issue_score는 몇 점 만점인가요? 상한 제한은 따로 두고 있지 않습니다. 같은 요청 안에서의 순위를 확인하는 용도로만 쓰는 것을 권장합니다.
Q10. summary를 그대로 보고서에 인용해도 되나요? AI 요약이므로 대외 인용 전 source_links 원문 확인이 필요합니다. 출처에 이슈와 무관한 오래된 문서가 섞일 수 있습니다.
