Skill: chloepark85/naver-datalab-cli (version 0.1.0)

--- name: naver-datalab-cli description: Korean search-keyword and shopping-trend analytics via the official NAVER DataLab API (openapi.naver.com/v1/datalab/*). Six subcommands wrapping 통합 검색어 트렌드 and 쇼핑인사이트 (분야별, 분야 내 키워드, 디바이스/성별/연령대 분포). Use when researching Korean consumer demand, planning SEO/content for the naver.com search market, comparing keyword popularity over time, building K-pop / K-beauty / K-commerce trend dashboards, or filling the gap that Google Trends leaves on Korean queries. Pairs with naver-papago-translate (translate insights), tistory-api-cli / velog-cli (publish trend posts), and kr-holiday-cli (align campaigns with KR calendar). Free tier (1k req/day for shopping insights, 25k req/day for search trends). version: 0.1.0 license: MIT --- # naver-datalab-cli Command-line wrapper for the **NAVER DataLab Open API** — Korea's primary search-keyword and shopping-insight trend service. The Korean equivalent of Google Trends, with two key advantages on KR-market analysis: 1. **NAVER drives ~55% of Korean search traffic** (vs ~35% Google), so its trends are closer to real Korean demand. 2. **쇼핑인사이트** exposes shopping-cart-level trends across 50+ category trees with breakdown by device / age / gender — Google Trends cannot do this. Six subcommands, one per official endpoint: | Command | Endpoint | Purpose | |---|---|---| | `scripts/search.sh` | `/v1/datalab/search` | 통합 검색어 트렌드 — compare up to 5 keyword groups (each with up to 20 synonyms) over time. | | `scripts/shop-cat.sh` | `/v1/datalab/shopping/categories` | 쇼핑인사이트 분야별 트렌드 — compare shopping-category click volumes. | | `scripts/shop-keyword.sh` | [REDACTED_SECRET] | 분야 내 키워드 트렌드 — within one category, compare keyword interest. | | `scripts/shop-device.sh` | [REDACTED_SECRET] | Device split (pc / mo) for one category. | | `scripts/shop-gender.sh` | [REDACTED_SECRET] | Gender split (f / m) for one category. | | `scripts/shop-age.sh` | [REDACTED_SECRET] | Age split (10/20/30/40/50/60) for one category. | All output is JSONL (one row per period per group) so it pipes directly into `jq`, `csvkit`, `pandas`, or downstream skills. ## When to use this skill - **SEO / content planning** — pick the higher-volume of "전기차 보조금" vs "EV 보조금" before writing. - **K-commerce demand sensing** — see which sub-category in 화장품/미용 spiked last month before pitching. - **Campaign timing** — confirm "수능 도시락" peaks early-November before launching ads. - **Brand health** — compare brand keyword vs competitor weekly. - **Influencer / blog audit** — back trend claims with NAVER's first-party numbers. - **Multi-platform AI agents** — feed Korean trend signals into chat/blog/video generators. ## Do **not** use this skill for - **Absolute search volume** — DataLab returns *relative* indices (0–100 range, normalized to the period peak), not raw query counts. NAVER intentionally never publishes raw counts. - **Real-time trends** — DataLab data lags ~24-48 hours. - **Google / YouTube / 다음 trends** — use `google-trends` or platform-specific skills. - **Naver search results pages** — use `naver-search` (existing ClawHub skill). ## Prerequisites 1. **Register a NAVER Developers application** at <https://developers.naver.com/apps/#/register>: - Choose **검색어트렌드** AND **쇼핑인사이트** when picking APIs (you need both for full coverage). - Application type: usually **Web 서비스** with localhost callback is fine for personal use. - Approval is automatic — no business-day wait. 2. Export credentials: ```bash export NAVER_CLIENT_ID='abcdEFG12345' export NAVER_CLIENT_SECRET='AbCdEfGhIj' ``` 3. Dependencies: `bash`, `curl`, `jq` (default on macOS/Linux). Free-tier quota: **25,000 req/day** for `/v1/datalab/search`, **1,000 req/day** for shopping endpoints. ## Commands ### 1. `search` — 통합 검색어 트렌드 Compare up to 5 keyword groups over a time range: ```bash scripts/search.sh \ --start 2024-01-01 --end 2024-12-31 --time-unit month \ --group "한국어:한국어,한글" \ --group "영어:영어,English" ``` Optional filters: `--device pc|mo`, `--gender f|m`, `--ages 1,2,3` (1=under 12, 2=13-18, 3=19-24, 4=25-29, 5=30-34, 6=35-39, 7=40-49, 8=50-59, 9=60+). Up to 5 `--group` blocks; each group has 1-20 keywords. Output (one record per group per period): ```json {"groupName":"한국어","period":"2024-01-01","ratio":78.32} ``` ### 2. `shop-cat` — 쇼핑인사이트 분야별 트렌드 ```bash scripts/shop-cat.sh \ --start 2024-01-01 --end 2024-12-31 --time-unit month \ --category "패션의류:50000000" \ --category "화장품/미용:50000002" ``` Same filters as `search`. Up to 3 categories per call. Category IDs come from <https://datalab.naver.com/shoppingInsight/sCategory.naver>. ### 3. `shop-keyword` — 분야 내 키워드 트렌드 Drill into one category: ```bash scripts/shop-keyword.sh \ --start 2024-06-01 --end 2024-12-31 --time-unit week \ --category 50000000 \ --keyword "원피스:원피스" \ --keyword "치마:치마,스커트" ``` ### 4-6. `shop-device` / `shop-gender` / `shop-age` Single-category breakdown by demographic: ```bash scripts/shop-device.sh --start 2024-01-01 --end 2024-06-30 --time-unit month --category 50000000 scripts/shop-gender.sh --start 2024-01-01 --end 2024-06-30 --time-unit month --category 50000000 scripts/shop-age.sh --start 2024-01-01 --end 2024-06-30 --time-unit month --category 50000000 ``` Output rows include the demographic dimension: ```json {"period":"2024-01-01","group":"pc","ratio":42.1} {"period":"2024-01-01","group":"mo","ratio":100.0} ``` ## Examples See `examples/` for canned recipes: - `examples/yearly-search.sh` — yearly comparison "전기차 vs 하이브리드". - `examples/k-beauty-by-age.sh` — 화장품/미용 demographic split. - `examples/seasonal-campaign.sh` — find "수능 도시락" peak month. ## Quirks the API doesn't document well - `timeUnit` accepts **`date`, `week`, `month`** — *not* `day`. (Date with daily granularity *is* `date`.) - `period` returned by daily/weekly is the *start* of the bucket, not the end. - For shopping endpoints, the body field is `category` (singular) for the breakdown calls but `category` (array of objects) for `categories`. The wrapper hides this. - Empty result → API returns `200 OK` with empty `results[].data`. The wrapper emits **no JSONL lines** for that group; check exit status and stderr. - The `ratio` is **relative**, not absolute. The peak point in the entire response is normalized to 100. ## Categorical spec (excerpt) | Code | Name | |---|---| | 50000000 | 패션의류 | | 50000001 | 패션잡화 | | 50000002 | 화장품/미용 | | 50000003 | 디지털/가전 | | 50000004 | 가구/인테리어 | | 50000005 | 출산/육아 | | 50000006 | 식품 | | 50000007 | 스포츠/레저 | | 50000008 | 생활/건강 | Full tree: <https://datalab.naver.com/shoppingInsight/sCategory.naver>. ## Pairs with - `naver-papago-translate` — translate the trend report into EN/JP/ZH for cross-market briefs. - `tistory-api-cli` / `velog-cli` — publish weekly Korean-trend posts. - `kr-holiday-cli` — overlay holiday/business-day calendar to interpret seasonal spikes. - `kakao-local-cli` + `juso-address-cli` — geo-resolve any place names that emerge from trend keywords.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)