# Naver Shopping Insight Keyword Rankings (`searchapi/naver-keyword-scraper`) Actor

Collects public popular-keyword rankings from Naver Shopping Insight by category, period, device, gender, and age.

- **URL**: https://apify.com/searchapi/naver-keyword-scraper.md
- **Developed by:** [Search API](https://apify.com/searchapi) (community)
- **Stats:** 3 total users, 2 monthly users, 25.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.99 / 1,000 search results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

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

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Naver Shopping Insight Keyword Rankings

CSV rank: **833**. Original Store listing: [billygogo/naver-keyword-scraper](https://apify.com/billygogo/naver-keyword-scraper).

This Actor collects the public TOP 500 popular search-keyword ranking from [Naver Shopping Insight](https://datalab.naver.com/shoppingInsight/sCategory.naver). It uses the same category, date, device, gender, and age values as the website and maps Naver's response into a strict, stable dataset contract.

### Input

- `categoryPath`: exact Korean category labels separated by `>`, such as `패션의류 > 여성의류`.
- `categoryId`: optional advanced eight-digit category ID; overrides `categoryPath` and is validated against Naver.
- `startDate` and `endDate`: optional `YYYY-MM-DD` dates. The period may not exceed one year.
- `timeUnit`: `date`, `week`, or `month`.
- `devices`: any of `pc`, `mo`; empty means all.
- `genders`: any of `f`, `m`; empty means all.
- `ages`: any of `10`, `20`, `30`, `40`, `50`, `60`; empty means all.
- `maxItems`, `maxPages`, concurrency, retry, timeout, and optional proxy controls.

The Actor first opens and validates the public Shopping Insight page. It resolves human-readable category paths through Naver's category endpoint, submits the normalized filter payload to Naver's ranking endpoint, validates page order and response shape, deduplicates by category and normalized keyword, and writes records only after the complete bounded extraction succeeds.

### Output

Each record contains the category ID/name/path, rank, keyword, applied filter values, result page, public source URL, and ISO-8601 collection time. Raw responses, cookies, headers, proxy URLs, and internal transport fields are never stored.

If Naver returns a CAPTCHA or access-control response, the Actor fails closed with `TARGET_BLOCKED` in `OUTPUT_SUMMARY` and writes no dataset placeholders.

### Local verification

```bash
npm install
apify validate-schema
apify run --purge
```

# Actor input Schema

## `categoryPath` (type: `string`):

Exact Korean category path, for example 패션의류 or 패션의류 > 여성의류. Ignored when categoryId is set.

## `categoryId` (type: `string`):

Optional eight-digit Naver Shopping category ID. Overrides categoryPath and is validated against Naver's category endpoint.

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

First day in YYYY-MM-DD. Defaults to 30 days before the latest complete Korean day.

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

Last day in YYYY-MM-DD. Defaults to the latest complete day in Korea.

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

Aggregate the selected period into daily, weekly, or monthly ranking data.

## `devices` (type: `array`):

Enter pc and/or mo. Leave empty for all devices; unsupported values are rejected.

## `genders` (type: `array`):

Enter f and/or m. Leave empty for all genders; unsupported values are rejected.

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

Enter 10, 20, 30, 40, 50, and/or 60 (60 means 60+). Leave empty for all ages; unsupported values are rejected.

## `maxItems` (type: `integer`):

Stop after this many unique keyword ranks, up to Naver's TOP 500.

## `maxPages` (type: `integer`):

Maximum 20-record pages to request, up to the website's 25 pages.

## `maxConcurrency` (type: `integer`):

Maximum simultaneous ranking-page requests.

## `maxRequestRetries` (type: `integer`):

Bounded retries for temporary network, rate-limit, and server failures.

## `requestTimeoutSecs` (type: `integer`):

Maximum time allowed for each Naver request.

## `proxyConfiguration` (type: `object`):

Optional Apify Proxy or custom proxy configuration. Credentials are never logged or stored.

## `debug` (type: `boolean`):

Enable additional non-sensitive diagnostic logging.

## Actor input object example

```json
{
  "categoryPath": "패션의류",
  "timeUnit": "date",
  "devices": [],
  "genders": [],
  "ages": [],
  "maxItems": 100,
  "maxPages": 25,
  "maxConcurrency": 2,
  "maxRequestRetries": 3,
  "requestTimeoutSecs": 30,
  "debug": false
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

## `runSummary` (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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("searchapi/naver-keyword-scraper").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("searchapi/naver-keyword-scraper").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 '{}' |
apify call searchapi/naver-keyword-scraper --silent --output-dataset

```

## MCP server setup

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

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/6mekf1rIhQfLt5EQV/builds/Z8M2jFg4OXpgsBC9M/openapi.json