# Naver DataLab Search Trend (English) (`hantaeyoung/naver-datalab-trend`) Actor

Official Naver Search Trend API wrapper. Type English or Korean keywords and get a relative search-index time series. Not a scraper. Shopping search API is gone — this is Search Trend only.

- **URL**: https://apify.com/hantaeyoung/naver-datalab-trend.md
- **Developed by:** [Taeyoung](https://apify.com/hantaeyoung) (community)
- **Categories:** SEO tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $150.00 / 1,000 keyword series

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Naver DataLab Search Trend (English)

Apify Actor that wraps **NAVER API HUB Search Trend** — the official Naver integrated-search trend API — and presents it in English.

Type `snail cream`, `retinol`, or `달팽이크림` and get a clean time series. This is **not a scraper**. It calls only documented official HTTP APIs.

**Shopping / book / academic search APIs ended 31 July 2026 with no replacement.** This Actor is **Search Trend only**.

### What the index means

The official field is `ratio`. Naver scales it so the **largest value among all keyword groups in that one HTTP request equals 100**. It is **not** absolute search volume and **not** comparable to Google Trends, nor across different Actor runs / request batches.

This Actor copies that value to `index` and stamps every row:

> index is relative to the peak (=100) inside this request group, not absolute search volume

Official HUB wording: *「구간별 검색량의 상대적 비율 - 구간별 결과에서 가장 큰 값을 100으로 설정한 상댓값」*.

The official API accepts at most **5 `keywordGroups` per request**. Keywords beyond that are split into further calls. **Only keywords that share a batch sit on the same 0–100 scale.**

### Confirmed official API (fetched 18 Aug 2026)

| Item | Official value |
| --- | --- |
| Method + URL | `POST https://naverapihub.apigw.ntruss.com/search-trend/v1/search` |
| Headers | `X-NCP-APIGW-API-KEY-ID`, `X-NCP-APIGW-API-KEY`, `Content-Type: application/json` |
| Required body | `startDate`, `endDate` (`yyyy-mm-dd`, from **2016-01-01**), `timeUnit` (`date` | `week` | `month`), `keywordGroups` |
| `keywordGroups` | max **5** pairs; each has `groupName` + `keywords` (max **20** strings) |
| Optional | `device`: `pc` | `mo` (omit = all); `gender`: `m` | `f` (omit = all); `ages`: official codes `1`–`11` |
| Response | `results[].data[].period`, `results[].data[].ratio` |
| HTTP 429 | official: daily allowance exceeded (`호출 한도 초과`) |

Sources:

- https://api.ncloud-docs.com/docs/naver-api-hub-overview
- https://api.ncloud-docs.com/docs/naver-api-hub-search-trend
- https://api.ncloud-docs.com/docs/naver-api-hub-search-trend-examples

#### What changed in 2026 (do not use developers.naver.com)

Per [Naver notice 32530](https://developers.naver.com/notice/article/32530):

| Date | What happened |
| --- | --- |
| 25 Jun 2026 | NAVER API HUB launched on NAVER Cloud Platform |
| **31 Jul 2026** | Developers Center **blocked new applications** for Search, Search Trend, Shopping Insight. Shopping / book / academic **search** APIs **ended** with no replacement. |
| 30 Jun 2027 | Developers Center keys fade out; HUB only after that |

**This Actor never calls** `https://openapi.naver.com/v1/datalab/search` **and never sends** `X-Naver-Client-Id`. New keys must come from the NCP console.

### How to get keys (NCP console — not developers.naver.com)

1. Sign up / log in at [NAVER Cloud Platform](https://www.ncloud.com/).
2. Console → region & platform → **Menu** → **All Services** → **Application Services** → **NAVER API HUB**.
3. **Application** → **Application 등록**.
4. Enable **검색어 트렌드 / Search Trend**.
5. Open the app → **API 관리** → **인증 정보**.
6. Copy **Client ID** and **Client Secret**.

Paste them into this Actor as:

| Actor secret | NCP field |
| --- | --- |
| `NAVER_CLIENT_ID` | Client ID (`X-NCP-APIGW-API-KEY-ID`) |
| `NAVER_CLIENT_SECRET` | Client Secret (`X-NCP-APIGW-API-KEY`) |

Do **not** create a new Search Trend app on https://developers.naver.com — new applications have been blocked since 31 Jul 2026.

### English vs Korean keywords

Naver Search Trend indexes **Naver integrated search**. Korean (Hangul) terms such as `달팽이크림` match how Koreans actually search.

- **Default:** English is sent **as-is**. `snail cream` is queried as `snail cream`.
- For Korean-market research, type Hangul yourself (`달팽이크림`, `레티놀`).
- Optional `translateEnglish` uses **NCP Papago Translation** (a *different* NCP product, own Client ID / Secret as `PAPAGO_CLIENT_ID` / `PAPAGO_CLIENT_SECRET`). Papago on developers.naver.com ended 29 Feb 2024 and is **never called**. If Papago keys are missing or the call fails, the original keyword is kept (`translated=false`) and the run continues.

### Input

| Field | Required | Default | Notes |
| --- | --- | --- | --- |
| `keywords` | yes | — | Array of strings, English or Korean. Capped at 50. |
| `startDate` | yes | prefill last 12 months | `YYYY-MM-DD`, not before 2016-01-01 |
| `endDate` | yes | prefill yesterday | `YYYY-MM-DD` |
| `timeUnit` | no | `week` | `date` | `week` | `month` |
| `device` | no | `all` (omit) | `pc` | `mo` |
| `gender` | no | `all` (omit) | `m` | `f` |
| `ages` | no | all (omit) | Official codes `1`–`11` only |
| `translateEnglish` | no | `false` | Optional NCP Papago; see above |
| `maxKeywords` | no | `50` | Actor cap, not a Naver field |

#### Example input

```json
{
  "keywords": ["snail cream", "retinol", "달팽이크림"],
  "startDate": "2025-08-18",
  "endDate": "2026-08-17",
  "timeUnit": "week",
  "device": "all",
  "gender": "all",
  "ages": ["4", "5", "6"],
  "translateEnglish": false
}
```

### Output

One **dataset** row per keyword × period:

```json
{
  "input": "달팽이크림",
  "queryKo": "달팽이크림",
  "translated": false,
  "period": "2026-03-01",
  "index": 100.0,
  "timeUnit": "week",
  "device": "all",
  "gender": "all",
  "ages": ["4", "5", "6"],
  "note": "index is relative to the peak (=100) inside this request group, not absolute search volume"
}
```

Key-value store file **`summary.json`**: per-keyword peak period, a short English gloss (`input` when the term was Latin-script; `Korean search term: …` when it was Hangul), batch count, and warnings.

### How to deploy (student)

This repo is **not** published to Apify Store. You push it to *your* account.

1. **Naver keys** — follow [How to get keys](#how-to-get-keys-ncp-console--not-developersnavercom). Enable **Search Trend** only. (Shopping search is gone.)

2. **Apify account** — https://console.apify.com/ sign up. Install [Apify CLI](https://docs.apify.com/cli).

3. From this directory:

   ```bash
   pip install -r requirements.txt
   pytest
   apify login
   apify push
   ```

4. In Apify Console → this Actor → **Settings → Environment variables** (secrets):
   - `NAVER_CLIENT_ID` = NCP API HUB Client ID
   - `NAVER_CLIENT_SECRET` = NCP API HUB Client Secret
   - Optional: `PAPAGO_CLIENT_ID` / `PAPAGO_CLIENT_SECRET` only if you turn on `translateEnglish`

5. Run from the generated input UI.

Local run without publishing:

```bash
export NAVER_CLIENT_ID=...
export NAVER_CLIENT_SECRET=...
apify run -p
```

### Pricing suggestion (PPE)

`.actor/pay_per_event.json` defines event `keyword-series` at **$0.03** (suggested band **$0.01–$0.05** per keyword time series). Enable pay-per-event in Actor monetization settings after `apify push`. The code charges `keyword-series` once per completed keyword when the run is in PPE mode.

### Legal

Official API wrapper. No HTML scraping, no undocumented endpoints, no shopping-search fallback. You must accept Naver / NCP API terms. Do not claim the index is absolute volume.

### What we could not verify

- Exact **daily free quota number** on API HUB Search Trend after the 2026 paid-plan review (HUB docs say 429 = daily allowance exceeded; they do not publish a single integer on the Search Trend page). Developers Center’s old “1,000 calls/day” figure is **not** used as a HUB limit here.
- Whether a given English brand name has meaningful Naver volume (often it does not — use Hangul).
- Live calls against your account (no keys on this box; tests are mocked HTTP).

### Local tests

```bash
pip install -r requirements.txt
pytest
```

Tests mock HTTP. They never send real keys and never hit Naver.

# Actor input Schema

## `keywords` (type: `array`):

Search terms in English or Korean. For Korean-market volume, type Hangul (e.g. 달팽이크림). English is sent as-is unless Translate English is on AND optional NCP Papago keys are set.

## `startDate` (type: `string`):

Range start (YYYY-MM-DD). Official data starts 1 January 2016.

## `endDate` (type: `string`):

Range end (YYYY-MM-DD). Must be on or after the start date.

## `timeUnit` (type: `string`):

Official interval: date (daily), week (weekly), month (monthly).

## `device` (type: `string`):

Official device filter. 'All' omits the field (every environment). pc = desktop, mo = mobile.

## `gender` (type: `string`):

Official gender filter. 'All' omits the field. m = male, f = female.

## `ages` (type: `array`):

Official age codes only. Leave empty for all ages. 1=0–12, 2=13–18, 3=19–24, 4=25–29, 5=30–34, 6=35–39, 7=40–44, 8=45–49, 9=50–54, 10=55–59, 11=60+.

## `translateEnglish` (type: `boolean`):

Off by default: Latin-script keywords are sent to Search Trend unchanged. Turn on only if you also set PAPAGO\_CLIENT\_ID / PAPAGO\_CLIENT\_SECRET from NCP Papago Translation (a different product). developers.naver.com Papago is dead and is never called. Hangul keywords are never translated. Papago failure keeps the original term and does not abort the run.

## `maxKeywords` (type: `integer`):

Hard cap (Actor-level, not a Naver field). Extra keywords are dropped. Official API allows 5 keyword groups per request; this Actor batches automatically.

## Actor input object example

```json
{
  "keywords": [
    "snail cream",
    "retinol",
    "달팽이크림"
  ],
  "startDate": "2025-08-18",
  "endDate": "2026-08-17",
  "timeUnit": "week",
  "device": "all",
  "gender": "all",
  "translateEnglish": false,
  "maxKeywords": 50
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `summary` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "keywords": [
        "snail cream",
        "retinol",
        "달팽이크림"
    ],
    "startDate": "2025-08-18",
    "endDate": "2026-08-17"
};

// Run the Actor and wait for it to finish
const run = await client.actor("hantaeyoung/naver-datalab-trend").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "keywords": [
        "snail cream",
        "retinol",
        "달팽이크림",
    ],
    "startDate": "2025-08-18",
    "endDate": "2026-08-17",
}

# Run the Actor and wait for it to finish
run = client.actor("hantaeyoung/naver-datalab-trend").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "keywords": [
    "snail cream",
    "retinol",
    "달팽이크림"
  ],
  "startDate": "2025-08-18",
  "endDate": "2026-08-17"
}' |
apify call hantaeyoung/naver-datalab-trend --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,hantaeyoung/naver-datalab-trend"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/DwJH57QWSGNz6ZDaD/builds/20nV8Z8PHBWlc9FIR/openapi.json