# Naver (/docs/naver)



Naver [#naver]

Naver is South Korea's dominant search portal. It indexes the Korean web, and especially Korean
blogs, community cafes and Q\&A, far more deeply than Google does, so for the Korean market it is
usually the more meaningful signal.

Base URL: `/v1/naver/...`

Eight search corpora and the two query utilities are 1 credit each. The three Data Lab trend
endpoints are 5. The `brief` composite, which fans one query across five corpora in a single
call, is 10.

What you can get [#what-you-can-get]

| Group           | Endpoints                                                                | What it gives you                                                  |
| --------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------ |
| Search corpora  | `blog`, `news`, `cafearticle`, `kin`, `local`, `image`, `encyc`, `webkr` | Ranked results per corpus, all in one response shape               |
| Query utilities | `errata`, `adult`                                                        | Korean typo correction, adult-term classification                  |
| Trends          | `search-trend`                                                           | Search-volume interest over time (Naver's Google Trends)           |
| Shopping trends | `shopping-insight/category`, `shopping-insight/keyword`                  | Click-share trends by category or by keyword within a category     |
| Composite       | `brief`                                                                  | One query fanned across 5 corpora, with an optional English digest |

Getting Started [#getting-started]

Every endpoint is a `GET` with an `x-api-key` header.

```bash
curl "https://www.socialcrawl.dev/v1/naver/blog/search?query=%EC%86%8C%EC%89%AC%EC%96%BC%ED%81%AC%EB%A1%A4&display=10" \
  -H "x-api-key: YOUR_API_KEY"
```

Swap `blog` for any other corpus. You do not need a Naver Cloud account, an API HUB application,
or a client-id/secret pair; we hold those.

All eight corpora take `query`, `display`, and `sort`, and all but `local` take `start` for
paging. Two corpora differ, both because Naver made them differ:

* **`local`** caps `display` at 5 and **defaults it to 1**, so omitting `display` returns a
  single place. It also ignores `start` entirely, which is why it is the one corpus with no
  pagination.
* **`image`** additionally takes `filter` (`all`, `large`, `medium`, `small`) to restrict
  results to a size band.

Which corpus answers which question [#which-corpus-answers-which-question]

The eight corpora share one response shape but index genuinely different parts of the Korean
internet, and picking the wrong one is the most common reason a Korean query comes back thin.

* **`/v1/naver/blog/search`** — long-form Korean blog writing. This is where most Korean product
  reviews, comparisons and how-to guides actually live, and it is usually the highest-signal
  corpus for a brand or product query.
* **`/v1/naver/cafearticle/search`** — Naver Cafe communities, the Korean equivalent of forums.
  Many cafes are members-only, so a result may link to a teaser rather than the full post; the
  title and snippet are still yours.
* **`/v1/naver/kin/search`** — KnowledgeiN (지식iN) question-and-answer threads. Use it when you
  want the questions Korean users ask about a topic in their own words, which is a different and
  often better input to content planning than what marketers wrote about it. `sort=point` ranks
  by answer quality here, and only here.
* **`/v1/naver/news/search`** — Korean press coverage, returning both the publisher's own URL
  and Naver's hosted copy. For news outside Korea use
  [`/v1/google_news/search`](/docs/google_news.md).
* **`/v1/naver/webkr/search`** — broad Korean web pages from Naver's own index, the closest
  analogue to a plain web search.
* **`/v1/naver/encyc/search`** — Naver's curated Knowledge Encyclopedia. Reference definitions
  written by editors, as opposed to KnowledgeiN's public answers.
* **`/v1/naver/image/search`** — images from Naver's crawl of the Korean web, returning the
  image files themselves with dimensions, not the pages hosting them.
* **`/v1/naver/local/search`** — Korean business listings from Naver Maps with category, phone,
  district and street addresses, and map coordinates. For Google's version of the same place use
  [`/v1/google/business/info`](/docs/google.md).

Two utilities for Korean input [#two-utilities-for-korean-input]

`GET /v1/naver/errata?query=…` returns Naver's spelling correction for a mistyped Korean query
as a single `errata` string, and an empty string when the query was already correct. This
matters more in Korean than in English: Korean mistypes usually come from hitting the wrong jamo
key, which produces a syllable that looks nothing like the intended one, so edit-distance
correction misses them entirely. Run user-supplied queries through it before searching.

`GET /v1/naver/adult?query=…` classifies a term as adult-only. It returns `adult` as the
**string** `"1"` or `"0"`, not a boolean — a detail worth encoding once rather than debugging
twice. Use it to moderate user-supplied search input, or to filter a keyword list before
publishing it.

One call across the Korean internet [#one-call-across-the-korean-internet]

`GET /v1/naver/brief?query=…` runs one query across news, blog, cafearticle, kin and webkr
together and returns per-corpus counts alongside the results, for 10 credits. `corpora` takes a
CSV subset when you do not want all five, `display` sets items per corpus (1-100, default 20),
and `cursor` is the preferred way to page — prefer it over `start`.

Set `include=digest` for an LLM-written English digest with translated quotes alongside the
Korean originals, which is the fastest way for a non-Korean-reading team to act on Korean
results.

```bash
curl "https://www.socialcrawl.dev/v1/naver/brief?query=%EC%A0%84%EA%B8%B0%EC%B0%A8&corpora=news,blog,cafearticle&include=digest" \
  -H "x-api-key: YOUR_API_KEY"
```

Endpoints [#endpoints]

<PlatformEndpoints platform="naver" />

Reading trend data [#reading-trend-data]

`/v1/naver/search-trend` is Naver's search-volume index, the Korean equivalent of Google Trends,
and `/v1/naver/shopping-insight/category` and `/v1/naver/shopping-insight/keyword` are its
shopping-click siblings — the first comparing whole categories, the second comparing product
terms inside one category. All three cost 5 credits and all three return a time series under
`data.results[].data[]` as `{period, ratio}` pairs.

All three also share the same four optional dimensions: `time_unit` (`date`, `week`, `month` —
default `month`), `device` (`pc` or `mo`), `gender` (`f` or `m`), and `ages`. Omit a dimension
and you get the total.

**`ratio` is a relative index, not a count.** It is scaled 0-100 within the window you asked
for, so the highest point in your range is always 100. Two separate requests are not comparable
to each other, and no endpoint returns absolute search or click volumes. Naver does not publish
those.

A keyword or category with no measurable volume returns no data points, and that call is not
charged.

Four gotchas worth knowing [#four-gotchas-worth-knowing]

Only some endpoints compare, and the rest combine [#only-some-endpoints-compare-and-the-rest-combine]

Which one you get depends on the endpoint, so check before you read the series:

| Endpoint                    | Multiple values behave as                                                                                                                            |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `search-trend`              | **One combined series.** The keywords are summed, so `keywords=삼성전자,갤럭시` is "either term" demand, not two lines. Call once per term to compare them. |
| `shopping-insight/category` | One comparable series per category id, up to 3, sharing a scale.                                                                                     |
| `shopping-insight/keyword`  | One comparable series per keyword, up to 5, sharing a scale.                                                                                         |

Sending more values than an endpoint accepts returns a `400` naming the limit. We do not
silently drop the extras, because a shorter list of series looks identical to "Naver had no data
for those".

Setting `breakdown` on either Shopping Insight endpoint changes the shape again: it splits a
single value by `device`, `gender` or `age` instead of comparing several, so only the first
category id or keyword you passed is used.

The two Data Lab APIs start at different dates [#the-two-data-lab-apis-start-at-different-dates]

| Endpoint                                                | History starts |
| ------------------------------------------------------- | -------------- |
| `search-trend`                                          | **2016-01-01** |
| `shopping-insight/category`, `shopping-insight/keyword` | **2017-08-01** |

An earlier `start_date` is clamped up to the relevant floor rather than rejected, so asking for
"everything" is safe on both.

`ages` uses different codes on different endpoints [#ages-uses-different-codes-on-different-endpoints]

This is Naver's own inconsistency, and we surface it rather than silently guess for you:

| Endpoint                                                | `ages` values                                                                                                       |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `search-trend`                                          | `1` through `11` (eleven fine-grained bands; `1` is 0-12, `11` is 60+). Note it is **1-based**, so there is no `0`. |
| `shopping-insight/category`, `shopping-insight/keyword` | `10`, `20`, `30`, `40`, `50`, `60` (decade buckets)                                                                 |

Sending the wrong set returns a `400` from us before the call is made, so you are never charged
for it.

Shopping Insight needs a category id [#shopping-insight-needs-a-category-id]

Naver publishes no category-list API, so the ids have to come from a table. The top-level ones:

| Category                        | `category_code` |
| ------------------------------- | --------------- |
| 패션의류 (Fashion / clothing)       | `50000000`      |
| 패션잡화 (Fashion accessories)      | `50000001`      |
| 화장품/미용 (Cosmetics / beauty)     | `50000002`      |
| 디지털/가전 (Digital / appliances)   | `50000003`      |
| 가구/인테리어 (Furniture / interior)  | `50000004`      |
| 출산/육아 (Maternity / childcare)   | `50000005`      |
| 식품 (Food)                       | `50000006`      |
| 스포츠/레저 (Sports / leisure)       | `50000007`      |
| 생활/건강 (Living / health)         | `50000008`      |
| 여가/생활편의 (Leisure / convenience) | `50000009`      |
| 면세점 (Duty free)                 | `50000010`      |
| 도서 (Books)                      | `50005542`      |

Deeper subcategory ids are visible in the URL when you browse a category on [Naver
Shopping](https://shopping.naver.com). Pass up to 3 comma-separated ids to compare them, or one
id plus `breakdown` to split it by device, gender, or age.

Retired endpoints [#retired-endpoints]

Naver **shut down its Shopping, Book, and Academic-document search corpora on 31/07/2026** with
no grace period and published no replacement API, so `/v1/naver/shop/search`,
`/v1/naver/book/search`, and `/v1/naver/doc/search` no longer exist. This was Naver's decision,
not ours, and no provider can resell those corpora because the upstream is gone.

If you were using them:

* **Shopping listings and prices:** there is no API replacement. `shopping-insight/category`
  gives you demand and click *trends* for a category, which covers a lot of the analytical use,
  but not individual products or prices. For those you would need to scrape shopping.naver.com
  yourself.
* **Books:** consider the 알라딘 Open API or Kakao Book Search.
* **Academic documents:** no comparable open API exists.

`brief` rejects `corpora=shop` for the same reason.

Notes [#notes]

* All endpoints use `GET` with query parameters, and return the unified SocialCrawl envelope.
* Titles and descriptions in search results come back HTML-tagged with `<b>` around matched
  terms, so you can highlight hits directly.
* `local/search` is the one corpus Naver does not paginate. It returns at most 5 places and
  ignores any offset, so it is a single-page endpoint and returns no pagination cursor. Every
  other corpus paginates normally up to `start=1000`.
* `sort` values are validated per corpus, because Naver's accepted values differ: `sim`/`date`
  for blog, news, cafe and image, plus `point` on KnowledgeiN, and `random`/`comment` on local.
  `encyc` and `webkr` ignore `sort` entirely. Sending a value the corpus does not accept returns
  a `400` before the call is made, so it costs you nothing.
* Korean text is returned as-is, never transliterated or machine-translated. Use `brief` with
  `include=digest` if you want an English synthesis alongside the Korean originals.