> ## Documentation Index
> Fetch the complete documentation index at: https://dev-docs.trychainshift.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 키워드 데이터
> 구글·네이버 검색량, 연관 키워드, 자동완성과 사이트 키워드 분석
구글과 네이버의 검색 데이터를 조회하는 API입니다. AI가 답변을 만들 때 던지는 [fan-out 쿼리](/guides/analytics#fan-out-쿼리-집계)는 결국 검색어입니다 — 어떤 검색어에 수요가 있고 경쟁이 어느 정도인지 알아야, 어떤 콘텐츠를 만들어 AI에 인용될지 정할 수 있습니다.
## 구글 키워드 지표
키워드 목록(1\~100개, 각 최대 80자)의 검색량·난이도·CPC·검색 의도를 한 번에 조회합니다.
```bash theme={null}
curl -X POST "https://dev-platform-api.trychainshift.ai/api/v1beta/platform/keywords/google/metrics" \
-H "API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"keywords": ["중고차", "중고차 시세"]}'
```
아래는 실제 응답입니다(월별 검색량은 최근 2개월만 남겼습니다 — 실제로는 최대 7년치가 반환됩니다).
```json theme={null}
{
"languageCode": "ko",
"countryCode": "KR",
"items": [
{
"keyword": "중고차",
"metrics": {
"searchVolume": 74000,
"keywordDifficulty": 74,
"cpc": 1.34,
"searchIntent": "transactional",
"searchVolumeTrend": { "monthly": 0, "quarterly": 0, "yearly": 0 },
"monthlySearches": [
{ "year": 2026, "month": 6, "searchVolume": 60500 },
{ "year": 2026, "month": 5, "searchVolume": 60500 }
]
}
},
{
"keyword": "중고차 시세",
"metrics": {
"searchVolume": 6600,
"keywordDifficulty": 18,
"cpc": 2.11,
"searchIntent": "commercial",
"searchVolumeTrend": { "monthly": 0, "quarterly": 22, "yearly": 0 },
"monthlySearches": [
{ "year": 2026, "month": 6, "searchVolume": 6600 },
{ "year": 2026, "month": 5, "searchVolume": 6600 }
]
}
}
]
}
```
이 두 키워드가 보여주는 것: "중고차"는 월 74,000회 검색되지만 SEO 난이도가 74로 진입이 어렵고, "중고차 시세"는 검색량 6,600에 난이도가 **18**로 낮으면서 분기 검색량이 22% 성장 중입니다. 대형 키워드 대신 이런 저난이도·성장형 키워드가 콘텐츠 우선순위가 됩니다.
* `searchIntent` — 검색 의도: `informational`(정보) / `commercial`(구매 검토) / `transactional`(구매 행동) / `navigational`(특정 사이트 찾기)
* `keywordDifficulty` — SEO 진입 난이도 (0\~100)
* `languageCode`(기본 `ko`) · `countryCode`(기본 `KR`)로 조회 시장을 바꿀 수 있습니다.
`metrics`가 `null`이면 데이터가 없는 키워드입니다. `metrics`는 있는데 `searchVolume`이 `null`이면 의료·금융 등 Google Ads 제한 카테고리라 검색량이 비공개인 경우입니다.
## 구글 연관 키워드 · 자동완성
시드 키워드 하나로 연관 키워드(`related`) 또는 자동완성 롱테일(`suggestions`)을 조회합니다. `limit`은 기본 30, 최대 100입니다.
```bash theme={null}
curl -H "API-Key: YOUR_API_KEY" \
"https://dev-platform-api.trychainshift.ai/api/v1beta/platform/keywords/google/related?keyword=중고차&limit=5"
```
실제 응답에서 연관 키워드 부분만 보면(각 키워드의 `metrics` 구조는 위와 동일):
| 연관 키워드 | 검색량 | 난이도 | 의도 | 연간 추이 |
| ---------- | ----- | --- | ------------- | ----- |
| 중고차 시세 | 6,600 | 18 | commercial | 0% |
| sk 엔카 중고차 | 4,400 | 68 | transactional | -34% |
| 중고차 판매 사이트 | 1,300 | 78 | commercial | -19% |
| 중고차 매매 | 1,300 | 47 | transactional | -23% |
브랜드가 붙은 검색("sk 엔카 중고차")이 연간 34% 줄고 있다는 것도 이 데이터에서 읽힙니다 — 검색이 AI 답변으로 이동하는 신호를 키워드 데이터로 관찰할 수 있습니다.
## 네이버 키워드 지표
네이버는 지표(`metrics`), 연관(`related`), 자동완성(`suggestions`), 12개월 검색량 추이(`trend`)를 제공합니다. 한국 시장 전용이라 언어·국가 파라미터가 없습니다.
네이버 `metrics`·`trend`의 키워드는 한 번에 1~~15개까지입니다(구글은 1~~100개).
```bash theme={null}
curl -X POST "https://dev-platform-api.trychainshift.ai/api/v1beta/platform/keywords/naver/metrics" \
-H "API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"keywords": ["중고차"]}'
```
```json theme={null}
{
"items": [
{
"keyword": "중고차",
"metrics": {
"searchVolumeTotal": 272300,
"searchVolumePC": 73000,
"searchVolumeMobile": 199300,
"pcBelowThreshold": false,
"mobileBelowThreshold": false,
"avgClickPC": 4358.3,
"avgClickMobile": 21333.4,
"avgCTRPC": 6.44,
"avgCTRMobile": 11.44,
"competition": "높음",
"adDepth": 10
}
}
]
}
```
같은 "중고차"인데 네이버 월 검색량(272,300)이 구글(74,000)의 3.7배이고, 그중 73%가 모바일입니다. 한국 시장 콘텐츠 전략에서 네이버 데이터를 따로 봐야 하는 이유입니다.
* `avgClickPC` / `avgClickMobile` — 월평균 클릭 수, `avgCTRPC` / `avgCTRMobile` — 평균 클릭률(%)
* `competition` — 광고 경쟁 정도(낮음/중간/높음), `adDepth` — 평균 노출 광고 수
* 검색량이 매우 낮은 키워드는 `pcBelowThreshold` / `mobileBelowThreshold`가 `true`로 반환되며 정확한 수치가 제공되지 않습니다.
## 네이버 검색량 추이
최근 12개월의 상대 검색량입니다. 절대치가 아니라 기간 내 최댓값을 100으로 하는 비율이며, `anchor`(해당 월의 절대 검색량)로 절대치 환산이 가능합니다.
```bash theme={null}
curl -X POST "https://dev-platform-api.trychainshift.ai/api/v1beta/platform/keywords/naver/trend" \
-H "API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"keywords": ["중고차"]}'
```
아래는 실제 응답입니다(12개 포인트 중 3개만 남겼습니다).
```json theme={null}
{
"items": [
{
"keyword": "중고차",
"trend": {
"points": [
{ "year": 2025, "month": 7, "ratio": 100 },
{ "year": 2025, "month": 12, "ratio": 75.87 },
{ "year": 2026, "month": 6, "ratio": 65.71 }
],
"anchor": { "year": 2026, "month": 6, "searchVolumeTotal": 272300 }
}
}
]
}
```
1년 사이 "중고차" 네이버 검색량이 1/3 넘게 줄었습니다(100 → 65.7). 검색 수요가 어디로 갔는지 — AI 답변으로 이동했는지 — 를 [실행 수집 데이터](/guides/submitting-runs)와 함께 보면 그림이 완성됩니다.
## 사이트 키워드 분석
웹사이트 URL을 주면 사이트를 크롤링해 핵심 키워드를 추출합니다. 프롬프트 실행과 같은 제출 → 폴링 패턴입니다.
```bash theme={null}
curl -X POST "https://dev-platform-api.trychainshift.ai/api/v1beta/platform/siteKeywordAnalyses" \
-H "API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://acme.com", "maxPages": 30}'
```
```json theme={null}
{ "taskID": "sK4jN8bV2xC6mZ1qW5eR9t" }
```
`maxPages`는 필수이며 1\~50 사이로 지정합니다. `GET /siteKeywordAnalyses/{taskID}`로 상태를 폴링합니다. 상태는 `PENDING` → `IN_PROGRESS` → `COMPLETED`(또는 `FAILED`) 순서로 진행되고, 완료되면 응답에 추출된 키워드 목록이 포함됩니다. `includeSourceURLs`·`includeContext` 파라미터로 키워드가 발견된 URL과 문맥을 함께 받을 수 있습니다.
## 에러 케이스
| 코드 | HTTP | 원인 |
| -------------------------------------- | ---- | ------------------------------- |
| `KEYWORD_COUNTRY_NOT_SUPPORTED` | 400 | 지원하지 않는 국가 코드 |
| `KEYWORD_METRICS_PROVIDER_REJECTED` | 400 | 지표 공급자가 거부한 요청 (예: 언어·국가 조합 오류) |
| `KEYWORD_METRICS_PROVIDER_UNAVAILABLE` | 502 | 외부 지표 공급자 호출 실패. 잠시 후 재시도하세요 |
| `KEYWORD_METRICS_NOT_CONFIGURED` | 503 | 키워드 지표 기능이 비활성화된 환경 |