# SocialCrawl API — naver endpoints
# Base URL: https://www.socialcrawl.dev
# Auth: x-api-key header
# Full docs: https://www.socialcrawl.dev/docs/naver

## GET /v1/naver/blog/search
Search Naver Blog
Credit cost: 1 (standard)
Parameters:
- query (required) — Free-text search term (UTF-8). Required.
- display (optional, integer) — Number of items to return per page. Defaults to 10, cap 100; `display=101` returns 400.
- start (optional, integer) — 1-indexed offset for pagination. Defaults to 1, cap 1000; `start=1001` returns 400.
- sort (optional, enum: sim | date) — Sort order. Accepted values: sim|date. Defaults to `sim` (relevance) when the corpus supports sort. Values outside this corpus's domain are rejected with a 400 before any upstream call.
curl "https://www.socialcrawl.dev/v1/naver/blog/search?query=소셜크롤" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/naver/news/search
Search Naver News
Credit cost: 1 (standard)
Parameters:
- query (required) — Free-text search term (UTF-8). Required.
- display (optional, integer) — Number of items to return per page. Defaults to 10, cap 100; `display=101` returns 400.
- start (optional, integer) — 1-indexed offset for pagination. Defaults to 1, cap 1000; `start=1001` returns 400.
- sort (optional, enum: sim | date) — Sort order. Accepted values: sim|date. Defaults to `sim` (relevance) when the corpus supports sort. Values outside this corpus's domain are rejected with a 400 before any upstream call.
curl "https://www.socialcrawl.dev/v1/naver/news/search?query=삼성전자" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/naver/encyc/search
Search Naver Encyclopedia
Credit cost: 1 (standard)
Parameters:
- query (required) — Free-text search term (UTF-8). Required.
- display (optional, integer) — Number of items to return per page. Defaults to 10, cap 100; `display=101` returns 400.
- start (optional, integer) — 1-indexed offset for pagination. Defaults to 1, cap 1000; `start=1001` returns 400.
- sort (optional, string) — Sort order. Accepted values: (sort ignored). Defaults to `sim` (relevance) when the corpus supports sort. Values outside this corpus's domain are rejected with a 400 before any upstream call.
curl "https://www.socialcrawl.dev/v1/naver/encyc/search?query=양자역학" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/naver/cafearticle/search
Search Naver Cafe articles
Credit cost: 1 (standard)
Parameters:
- query (required) — Free-text search term (UTF-8). Required.
- display (optional, integer) — Number of items to return per page. Defaults to 10, cap 100; `display=101` returns 400.
- start (optional, integer) — 1-indexed offset for pagination. Defaults to 1, cap 1000; `start=1001` returns 400.
- sort (optional, enum: sim | date) — Sort order. Accepted values: sim|date. Defaults to `sim` (relevance) when the corpus supports sort. Values outside this corpus's domain are rejected with a 400 before any upstream call.
curl "https://www.socialcrawl.dev/v1/naver/cafearticle/search?query=주식" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/naver/kin/search
Search Naver KnowledgeiN (지식iN)
Credit cost: 1 (standard)
Parameters:
- query (required) — Free-text search term (UTF-8). Required.
- display (optional, integer) — Number of items to return per page. Defaults to 10, cap 100; `display=101` returns 400.
- start (optional, integer) — 1-indexed offset for pagination. Defaults to 1, cap 1000; `start=1001` returns 400.
- sort (optional, enum: sim | date | point) — Sort order. Accepted values: sim|date|point. Defaults to `sim` (relevance) when the corpus supports sort. Values outside this corpus's domain are rejected with a 400 before any upstream call.
curl "https://www.socialcrawl.dev/v1/naver/kin/search?query=코로나 증상" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/naver/local/search
Search Naver Local (장소 검색)
Credit cost: 1 (standard)
Parameters:
- query (required) — Free-text search term (UTF-8). Required.
- display (optional, integer) — Number of places to return. This corpus caps at 5 and **defaults to 1**, so omitting it returns a single place. Values above 5 are silently clamped by Naver rather than rejected.
- sort (optional, enum: random | comment) — Sort order. Accepted values: random|comment (display max 5, start max 1). Defaults to `sim` (relevance) when the corpus supports sort. Values outside this corpus's domain are rejected with a 400 before any upstream call.
curl "https://www.socialcrawl.dev/v1/naver/local/search?query=강남역 카페" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/naver/image/search
Search Naver Image
Credit cost: 1 (standard)
Parameters:
- query (required) — Free-text search term (UTF-8). Required.
- display (optional, integer) — Number of items to return per page. Defaults to 10, cap 100; `display=101` returns 400.
- start (optional, integer) — 1-indexed offset for pagination. Defaults to 1, cap 1000; `start=1001` returns 400.
- sort (optional, enum: sim | date) — Sort order. Accepted values: sim|date. Defaults to `sim` (relevance) when the corpus supports sort. Values outside this corpus's domain are rejected with a 400 before any upstream call.
- filter (optional, enum: all | large | medium | small) — Restrict to an image size band: `all` (default), `large`, `medium`, or `small`.
curl "https://www.socialcrawl.dev/v1/naver/image/search?query=한라산" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/naver/webkr/search
Search Naver Web (웹문서)
Credit cost: 1 (standard)
Parameters:
- query (required) — Free-text search term (UTF-8). Required.
- display (optional, integer) — Number of items to return per page. Defaults to 10, cap 100; `display=101` returns 400.
- start (optional, integer) — 1-indexed offset for pagination. Defaults to 1, cap 1000; `start=1001` returns 400.
- sort (optional, string) — Sort order. Accepted values: (sort ignored). Defaults to `sim` (relevance) when the corpus supports sort. Values outside this corpus's domain are rejected with a 400 before any upstream call.
curl "https://www.socialcrawl.dev/v1/naver/webkr/search?query=기후변화" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/naver/errata
Correct a mistyped Korean search query (오타변환)
Credit cost: 1 (standard)
Parameters:
- query (required) — The possibly-mistyped search term (UTF-8). Required.
curl "https://www.socialcrawl.dev/v1/naver/errata?query=네이볘" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/naver/adult
Check whether a Korean search term is adult-only (성인 검색어 판별)
Credit cost: 1 (standard)
Parameters:
- query (required) — The search term to classify (UTF-8). Required.
curl "https://www.socialcrawl.dev/v1/naver/adult?query=성인영화" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/naver/search-trend
Get Naver search-volume trend for Korean keywords (검색어트렌드)
Credit cost: 5 (advanced)
Parameters:
- keywords (required) — Comma-separated Korean keywords, up to 20, combined into ONE trend series (volumes summed, not compared). Required. To compare terms, issue one call per term.
- start_date (optional, string) — Window start, `YYYY-MM-DD`. Defaults to 12 months before `end_date`. Clamped up to 2016-01-01, the earliest data Naver holds.
- end_date (optional, string) — Window end, `YYYY-MM-DD`. Defaults to today.
- time_unit (optional, enum: date | week | month) — Aggregation bucket: `date`, `week`, or `month` (default `month`).
- group_name (optional, string) — Label for the series in the response. Defaults to the first keyword.
- device (optional, enum: pc | mo) — Restrict to `pc` or `mo` (mobile). Omit for both.
- gender (optional, enum: f | m) — Restrict to `f` or `m`. Omit for both.
- ages (optional, string) — Comma-separated age-band codes, `1` to `11` (Naver's eleven bands, finest at the young end: `1` is 0-12, `11` is 60+). NOTE this endpoint uses different codes from `shopping-insight/*`, which takes 10/20/30/40/50/60.
curl "https://www.socialcrawl.dev/v1/naver/search-trend?keywords=삼성전자,갤럭시" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/naver/shopping-insight/category
Get Naver Shopping click trend for a category (쇼핑인사이트)
Credit cost: 5 (advanced)
Parameters:
- category_code (required) — Comma-separated Naver Shopping category ids, up to 3 (e.g. `50000000` for 패션의류). Required. When `breakdown` is set, only the first id is used. Naver publishes no category-list API, so see the platform guide for the id table.
- start_date (optional, string) — Window start, `YYYY-MM-DD`. Defaults to 12 months before `end_date`. Clamped up to 2017-08-01, the earliest Shopping Insight data Naver holds.
- end_date (optional, string) — Window end, `YYYY-MM-DD`. Defaults to today.
- time_unit (optional, enum: date | week | month) — Aggregation bucket: `date`, `week`, or `month` (default `month`).
- device (optional, enum: pc | mo) — Restrict to `pc` or `mo` (mobile). Omit for both.
- gender (optional, enum: f | m) — Restrict to `f` or `m`. Omit for both.
- ages (optional, string) — Comma-separated age buckets: `10`, `20`, `30`, `40`, `50`, `60`. NOTE these differ from `search-trend`, which takes 1-11.
- breakdown (optional, enum: device | gender | age) — Split a single category by `device`, `gender`, or `age` instead of comparing several categories.
curl "https://www.socialcrawl.dev/v1/naver/shopping-insight/category?category_code=50000000" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/naver/shopping-insight/keyword
Get Naver Shopping click trend for keywords inside a category (쇼핑인사이트)
Credit cost: 5 (advanced)
Parameters:
- category_code (required) — A single Naver Shopping category id to search within (e.g. `50000000`). Required.
- keyword (required) — Comma-separated keywords, up to 5, each returned as its own comparable series inside that category. Required. When `breakdown` is set, only the first keyword is used.
- start_date (optional, string) — Window start, `YYYY-MM-DD`. Defaults to 12 months before `end_date`. Clamped up to 2017-08-01, the earliest Shopping Insight data Naver holds.
- end_date (optional, string) — Window end, `YYYY-MM-DD`. Defaults to today.
- time_unit (optional, enum: date | week | month) — Aggregation bucket: `date`, `week`, or `month` (default `month`).
- device (optional, enum: pc | mo) — Restrict to `pc` or `mo` (mobile). Omit for both.
- gender (optional, enum: f | m) — Restrict to `f` or `m`. Omit for both.
- ages (optional, string) — Comma-separated age buckets: `10`, `20`, `30`, `40`, `50`, `60`. NOTE these differ from `search-trend`, which takes 1-11.
- breakdown (optional, enum: device | gender | age) — Split a single keyword by `device`, `gender`, or `age` instead of comparing several keywords.
curl "https://www.socialcrawl.dev/v1/naver/shopping-insight/keyword?category_code=50000000" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/naver/brief
One query across the Korean internet (5 Naver corpora) + optional digest.
Credit cost: 10 (override; tier advanced)
Parameters:
- query (required) — Search query (Korean or any language).
- corpora (optional, string) — CSV subset of news,blog,cafearticle,kin,webkr (default all five). `shop` was retired by Naver on 2026-07-31 and is rejected.
- display (optional, integer) — Items per corpus (1–100, default 20).
- start (optional, integer) — 1-indexed offset per corpus (1–1000, default 1). Prefer `cursor` for paging.
- sort (optional, string) — sim (relevance, default) or date; kin also point.
- include (optional, string) — Set to `digest` for an LLM English digest with translated quotes.
- cursor (optional, string) — Opaque pagination token from a prior response's next_cursor.
curl "https://www.socialcrawl.dev/v1/naver/brief?query=삼성전자" \
  -H "x-api-key: sc_your_api_key_here"