# Naver (/docs/naver)

Search Naver blog, news, cafe, KnowledgeiN, local, image, encyclopedia and web, plus Korean search-volume and shopping-click trends, with one API key.

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/...`

  Naver shut down its Shopping, Book and Academic-document corpora on
  31/07/2026, so `/v1/naver/shop/search`, `/v1/naver/book/search` and
  `/v1/naver/doc/search` no longer exist. See [Retired
  corpora](#retired-corpora) for what to do instead.

## Quickstart

### 1. Search a corpus

Every endpoint is a `GET` with an `x-api-key` header. You do not need a Naver Cloud account, an API HUB application, or a client-id/secret pair. We hold those.

```bash title="cURL"
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.

### 2. Or hit five corpora in one call

`brief` fans one query across news, blog, cafearticle, kin and webkr together and returns per-corpus counts alongside the results.

```bash title="cURL"
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"
```

`include=digest` adds 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.

## Search the Korean web

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. All eight are 1 credit.

| Endpoint                           | Credits | What it returns                                                                                                    | Key parameters                                     |
| ---------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- |
| `GET /v1/naver/blog/search`        | 1       | Long-form Korean blog writing, where most Korean product reviews, comparisons and how-to guides live               | `query`, `display`, `start`, `sort`                |
| `GET /v1/naver/cafearticle/search` | 1       | Naver Cafe community posts, the Korean equivalent of forums                                                        | `query`, `display`, `start`, `sort`                |
| `GET /v1/naver/kin/search`         | 1       | KnowledgeiN (지식iN) question-and-answer threads, in users' own words                                              | `query`, `display`, `start`, `sort` (adds `point`) |
| `GET /v1/naver/news/search`        | 1       | Korean press coverage, with both the publisher's own URL and Naver's hosted copy                                   | `query`, `display`, `start`, `sort`                |
| `GET /v1/naver/webkr/search`       | 1       | Broad Korean web pages from Naver's own index, the closest analogue to a plain web search                          | `query`, `display`, `start`                        |
| `GET /v1/naver/encyc/search`       | 1       | Naver's curated Knowledge Encyclopedia: reference definitions written by editors                                   | `query`, `display`, `start`                        |
| `GET /v1/naver/image/search`       | 1       | Images from Naver's crawl of the Korean web, returning the image files with dimensions, not the pages hosting them | `query`, `display`, `start`, `sort`, `filter`      |
| `GET /v1/naver/local/search`       | 1       | Korean business listings from Naver Maps with category, phone, district and street addresses, and map coordinates  | `query`, `display`, `sort`                         |

`display` defaults to 10 and caps at 100, and `start` is a 1-indexed offset that caps at 1000. Both reject an out-of-range value with a `400` that costs nothing. Naver serves no result past rank 1000, so the page that reaches it is the last one: `has_more` is `false` and there is no next cursor.

**Naver ranks only the first 100 results by relevance.** Past rank 100, a `sort=sim` page (the default, and `point` on KnowledgeiN) is refilled with rows from Naver's own top 100: on a common query, `start=101`, `201` and `301` came back with page 1's exact rows. We compare each deep page with that top 100 and remove the repeats, and `_warnings` says how many (`recycled_rows`). A page left empty costs nothing, and the cursor still moves past the whole window, because deeper pages often carry new rows again. To collect more than 100 rows on one query, use `sort=date`, which pages to 1,000 without repeats.

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 ignores `start` entirely, which is why it is the one corpus with no pagination. A `display` above 5 is silently clamped by Naver rather than rejected.
- **`image`** additionally takes `filter` (`all`, `large`, `medium`, `small`) to restrict results to a size band.

Reach for `kin` 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. Many cafes are members-only, so a `cafearticle` result may link to a teaser rather than the full post. The title and snippet are still yours.

**Which rows carry a date.** Blog and news rows carry `published_at`. Naver sends no date for KnowledgeiN, cafe or web-document results:

- **`kin`** rows carry `published_at_est` (`YYYY-MM-DD`, Korea time) with `date_basis: "kin_docid_estimate"`. A question's id rises with time, so we estimate its date from question pages whose posted date we read. It is usually within a few days, which is enough for a "last 90 days" cut. It is still an estimate, it never fills `published_at`, and questions from before mid-2010 carry none.
- **`cafearticle`** and **`webkr`** rows have no date at all, and the page says so in `_warnings` (`undated_rows`). Do not count them into a dated trend.

**Keep the rows that are about your query.** Blog, news and cafe search take `relevance=filter`, which reads each row's title and excerpt against your query, leaves off the rows about something else, and lists their ids in `data.relevance.dropped_ids`. With your query as the topic it costs the page's 1 credit. Every row on those three also carries `computed.relevance` and the `sponsored`, `intent` and `niche` labels by default, free, and `intent.label: "promoting"` is the quickest way to set clinic and brand posts apart from people writing about their own experience. `judgments=off` returns the page without them.

**`sort=date` reaches only the newest 1,000 rows.** On a common word that is hours or days, not months, and Naver also loosens the match on a multi-word query sorted by date. Search short noun phrases (Naver does not treat quotes as an exact phrase), and to cover a longer window use narrower terms with `since=`.

For news outside Korea use [`/v1/google_news/search`](/docs/google_news.md). For Google's version of a Korean place, use [`/v1/google/business/info`](/docs/google.md).

## Clean up Korean input

| Endpoint               | Credits | What it returns                                                                      | Key parameters |
| ---------------------- | ------- | ------------------------------------------------------------------------------------ | -------------- |
| `GET /v1/naver/errata` | 1       | Naver's spelling correction for a mistyped Korean query, as a single `errata` string | `query`        |
| `GET /v1/naver/adult`  | 1       | Whether a term is adult-only, as `adult`                                             | `query`        |

`errata` returns 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.

`adult` returns 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

| Endpoint              | Credits | What it returns                                                                     | Key parameters                                                      |
| --------------------- | ------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| `GET /v1/naver/brief` | 10      | One query run across news, blog, cafearticle, kin and webkr, with per-corpus counts | `query`, `corpora`, `display`, `start`, `sort`, `include`, `cursor` |

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

## Read trend data

| Endpoint                                  | Credits | What it returns                                                               | Key parameters                                                                                         |
| ----------------------------------------- | ------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `GET /v1/naver/search-trend`              | 5       | Naver's search-volume index over time, the Korean equivalent of Google Trends | `keywords` (up to 20) or `groups` (up to 5 series), `start_date`, `end_date`, `time_unit`, `group_name`, `device`, `gender`, `ages` |
| `GET /v1/naver/shopping-insight/category` | 5       | Shopping click-share trend, comparing whole categories                        | `category_code` (up to 3), the same window and dimension params, plus `breakdown`                      |
| `GET /v1/naver/shopping-insight/keyword`  | 5       | Shopping click-share trend, comparing product terms inside one category       | `category_code`, `keyword` (up to 5), the same params, plus `breakdown`                                |

All three return a time series under `data.results[].data[]` as `{period, ratio}` pairs, and all three 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. `group_name` on `search-trend` labels the series in the response and defaults to the first keyword.

**`ratio` is a relative index, not a count.** It is scaled so the busiest series in the request peaks at 100. Two separate requests are not comparable to each other, and no endpoint returns absolute search or click volumes. Naver does not publish those. To compare, put everything in one request: `groups` on `search-trend`, several ids on `shopping-insight/*`.

On `search-trend`, every series lists every period of the window. Naver leaves out a period that falls below its reporting threshold; we return it as `ratio: 0`, which is also what Naver's own Data Lab chart draws, so an average over the series is not inflated by the missing quiet periods. Naver counts whole weeks (Monday to Sunday) and whole months, so a window that starts on a Wednesday still gets the full first week. The week or month still in progress carries `partial: true`: its ratio is lower only because it covers just the days published so far.

A request with no measurable volume in any series returns no data points, and that call is not charged.

## Four gotchas worth knowing

### 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`              | **`keywords` is one combined series.** The keywords are summed, so `keywords=삼성전자,갤럭시` is "either term" demand, not two lines. To compare, send `groups` instead: up to 5 series, one per group, sharing one scale. |
| `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.                                                                                                |

`groups` separates the groups with `|` and the keywords inside a group with `,`, and names each series by its first keyword:

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/naver/search-trend?groups=%EC%86%90%20%EB%8B%A4%ED%95%9C%EC%A6%9D,%EB%B0%9C%20%EB%8B%A4%ED%95%9C%EC%A6%9D%7C%EB%AF%B8%EB%9D%BC%EB%93%9C%EB%9D%BC%EC%9D%B4&time_unit=week" \
  -H "x-api-key: YOUR_API_KEY"
```

That is `groups=손 다한증,발 다한증|미라드라이`: two lines on one scale, the first summing both hand and foot searches.

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

`gender`, `ages` and `device` filter a whole `search-trend` request, and listing several `ages` codes sums those bands into one audience. So comparing two demographic segments takes two calls, each scaled to its own peak: compare the shape of their curves (when each rises), never their levels. Naver offers no search-trend breakdown on one scale.

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

| 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

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

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 corpora

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.

## All endpoints

## Platform notes

- **`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 pages up to `start=1000`; with `sort=sim` only the first 100 rows are ranked, so page past 100 with `sort=date` (see [Search the Korean web](#search-the-korean-web)).
- **`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.
- **Titles and descriptions come back HTML-tagged** with `<b>` around matched terms, so you can highlight hits directly.
- **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.
- All endpoints use `GET` with query parameters and return the unified SocialCrawl envelope.

## Next steps

- [Google Trends](/docs/google_trends.md): The non-Korean side of the same demand question.
- [Prism](/docs/prism.md): korea-gap contrasts the Korean conversation with the global one.
- [Pagination](/docs/pagination.md): Offset, cursor, and single-page endpoints across the API.