---
title: 이슈 키워드 조회 API(/trend_finder/issue_list) 활용 가이드
description: "Trend Finder 이슈 키워드 조회 API는 \"이 키워드 주변에서 최근 무슨 이슈가 있었나\"를 알고 싶을 때 사용합니다. Google 자동완성(서제스트) 데이터의 이슈성을 추적하고, 검색결과(SERP) 데이터를 분석하여 일간 주목받는 키워드를 제공합니다. 마케팅 캠페인, 콘텐츠 기획, 광고 전략에서 관심 주제, 이슈 요약, 키워드…"
url: "https://kr.listeningmind.com/data-api/api-reference/trend-finder-issue-list/"
updated: "2026-10-16"
category: API 레퍼런스
tags:
  - 데이터 API
  - 리스닝마인드 DaaS
  - 키워드 조회
---

# 이슈 키워드 조회 API(/trend_finder/issue_list) 활용 가이드

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` 원문 확인이 필요합니다. 출처에 이슈와 무관한 오래된 문서가 섞일 수 있습니다.