> ## 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.

# Keyword data

> Google and Naver search volume, related keywords, autocomplete suggestions, and site keyword analysis

These APIs retrieve search data from Google and Naver. The [fan-out queries](https://dev-docs.trychainshift.ai/en/guides/analytics.md#fan-out-query-aggregation) an AI issues when building an answer are ultimately search terms. You need to know which search terms have demand and how competitive they are before you can decide what content to create to get cited by AI.

## Google keyword metrics

Retrieve search volume, difficulty, CPC, and search intent for a list of keywords (1 to 100, each up to 80 characters) in one call. The example below uses the Korean keywords for "used car" and "used car prices".

```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": ["중고차", "중고차 시세"]}'
```

Below is a real response (monthly search volume is trimmed to the latest 2 months; the API actually returns up to 7 years).

```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 }
        ]
      }
    }
  ]
}
```

What these two keywords show: "중고차" (used car) is searched 74,000 times a month but has an SEO difficulty of 74, making it hard to break into, while "중고차 시세" (used car prices) has a search volume of 6,600 with a low difficulty of **18** and quarterly search volume growing 22%. Low-difficulty, growing keywords like this take content priority over the big head terms.

* `searchIntent`: search intent, one of `informational` (looking for information) / `commercial` (evaluating a purchase) / `transactional` (ready to buy) / `navigational` (looking for a specific site)
* `keywordDifficulty`: SEO entry difficulty (0 to 100)
* Change the target market with `languageCode` (default `ko`) and `countryCode` (default `KR`).

> [!NOTE]
>
> If `metrics` is `null`, there is no data for that keyword. If `metrics` is
> present but `searchVolume` is `null`, the keyword falls into a restricted
> Google Ads category such as healthcare or finance, and search volume is not
> disclosed.

## Google related keywords and autocomplete

Retrieve related keywords (`related`) or autocomplete long-tail suggestions (`suggestions`) from a single seed keyword. `limit` defaults to 30 and is capped at 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"
```

Looking only at the related keywords portion of a real response (each keyword's `metrics` structure is the same as above):

| Related keyword | Search volume | Difficulty | Intent | Yearly trend |
| - | - | - | - | - |
| 중고차 시세 | 6,600 | 18 | commercial | 0% |
| sk 엔카 중고차 | 4,400 | 68 | transactional | -34% |
| 중고차 판매 사이트 | 1,300 | 78 | commercial | -19% |
| 중고차 매매 | 1,300 | 47 | transactional | -23% |

You can also read from this data that the branded search "sk 엔카 중고차" (SK Encar used cars) is declining 34% year over year. Keyword data lets you observe the signal of search shifting to AI answers.

## Naver keyword metrics

Naver provides metrics (`metrics`), related keywords (`related`), autocomplete suggestions (`suggestions`), and a 12-month search volume trend (`trend`). It is specific to the Korean market, so there are no language or country parameters.

> [!NOTE]
>
> Naver `metrics` and `trend` accept 1 to 15 keywords per call (Google accepts
> 1 to 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
      }
    }
  ]
}
```

For the same keyword "중고차", Naver's monthly search volume (272,300) is 3.7 times Google's (74,000), and 73% of it is mobile. This is why a content strategy for the Korean market needs to look at Naver data separately.

* `avgClickPC` / `avgClickMobile`: average monthly clicks; `avgCTRPC` / `avgCTRMobile`: average click-through rate (%)
* `competition`: level of ad competition (`낮음` low / `중간` medium / `높음` high); `adDepth`: average number of ads shown
* Keywords with very low search volume return `pcBelowThreshold` / `mobileBelowThreshold` as `true`, and exact figures are not provided.

## Naver search volume trend

Relative search volume for the last 12 months. The values are not absolute; they are ratios where the maximum in the period is 100. You can convert to absolute values using `anchor` (the absolute search volume for that month).

```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": ["중고차"]}'
```

Below is a real response (trimmed to 3 of the 12 points).

```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 }
      }
    }
  ]
}
```

Naver search volume for "중고차" dropped by more than a third in one year (100 → 65.7). To see where that search demand went, and whether it moved to AI answers, look at it together with your [run collection data](https://dev-docs.trychainshift.ai/en/guides/submitting-runs.md).

## Site keyword analysis

Give it a website URL and it crawls the site to extract core keywords. It follows the same submit → poll pattern as running prompts.

```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` is required and must be between 1 and 50. Poll the status with `GET /siteKeywordAnalyses/{taskID}`. The status moves from `PENDING` → `IN_PROGRESS` → `COMPLETED` (or `FAILED`), and once complete the response includes the extracted keyword list. Use the `includeSourceURLs` and `includeContext` parameters to also receive the URLs and context where each keyword was found.

## Error cases

| Code | HTTP | Cause |
| - | - | - |
| `KEYWORD_COUNTRY_NOT_SUPPORTED` | 400 | Unsupported country code |
| `KEYWORD_METRICS_PROVIDER_REJECTED` | 400 | The metrics provider rejected the request (for example, an invalid language and country combination) |
| `KEYWORD_METRICS_PROVIDER_UNAVAILABLE` | 502 | The external metrics provider call failed. Retry after a short wait |
| `KEYWORD_METRICS_NOT_CONFIGURED` | 503 | The keyword metrics feature is disabled in this environment |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.