> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrapebadger.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Naver API Overview

> Search Naver — South Korea's dominant portal — across web, news, blog, cafe, Knowledge iN, image, video and local, plus the full Naver Shopping stack: rankings, catalog search, SmartStore/Brand storefronts, product detail, reviews & Q&A, and Shopping Live. Clean JSON, no Naver API key required.

## Overview

The ScrapeBadger **Naver API** turns `naver.com` — the search portal most of
South Korea actually uses — into a clean JSON feed. It covers three areas:

* **Search & content** — the web SERP, the dedicated web/news/blog/cafe/
  Knowledge iN/image/video/clip verticals, and search-box autocomplete, all
  with resolved destination URLs and absolute publish timestamps.
* **Naver Place** — local business search, full place detail with menus and
  photos, place reviews, and the place photo viewer.
* **Naver Shopping** — the ranking and insight feeds (bestsellers, keyword and
  brand rankings, curated verticals), product and catalog search with
  price-comparison, SmartStore and Brand Store storefronts, product detail,
  reviews & Q\&A, and the full **Shopping Live** broadcast/channel/shortclip
  stack.

> [!NOTE]
>
> All endpoints are `GET`, live under `https://scrapebadger.com/v1/naver/*`,
> and authenticate with the `X-API-Key` header. Credits are charged per request
> and reported on the `X-Credits-Used` response header. A request that returns
> an empty result, or that Naver answers with a challenge, is **not billed**.

## Features

* **Web & content verticals** — the integrated
  [`/search`](https://docs.scrapebadger.com/api-reference/endpoint/naver/search) SERP plus the dedicated
  [`/search/web`](https://docs.scrapebadger.com/api-reference/endpoint/naver/search-web),
  [`/news`](https://docs.scrapebadger.com/api-reference/endpoint/naver/news),
  [`/blog`](https://docs.scrapebadger.com/api-reference/endpoint/naver/blog),
  [`/cafe`](https://docs.scrapebadger.com/api-reference/endpoint/naver/cafe),
  [`/kin`](https://docs.scrapebadger.com/api-reference/endpoint/naver/kin) (Knowledge iN),
  [`/image`](https://docs.scrapebadger.com/api-reference/endpoint/naver/image),
  [`/video`](https://docs.scrapebadger.com/api-reference/endpoint/naver/video) and
  [`/clip`](https://docs.scrapebadger.com/api-reference/endpoint/naver/clip) feeds, each with resolved
  destination URLs and absolute publish times.
* **Autocomplete** — Naver's search-box suggestions for 2 credits.
* **Naver Place** — local business search, full place detail, reviews and the
  place [photo viewer](https://docs.scrapebadger.com/api-reference/endpoint/naver/place-photos.md).
* **Shopping rankings & insight** — bestseller, keyword and brand rankings,
  keyword insight, curated deals/verticals/IT-item feeds, and the ranking
  category trees.
* **Shopping search & catalog** — the finder product search and filter facets,
  filtered search, the deep full-catalog search, and per-catalog
  price-comparison across sellers.
* **SmartStore & Brand Stores** — store profile, category tree, product
  listing and per-store bestsellers.
* **Products, reviews & Q\&A** — full product detail, variant groups, rating
  summaries, paginated reviews and product Q\&A.
* **Shopping Live** — broadcast detail/products/counts/replay, channel profile/
  products/broadcasts/shortclips, shortclip detail/products, and the live
  keyword ranking.

## Market

Naver serves **South Korea** only. Results are returned in Korean (`ko-KR`),
ranked for Korean users, and requests exit from a Korean IP. There is no market
or country parameter — every endpoint is single-market.

## SmartStore vs. Brand Store

The storefront, product, review and Q\&A endpoints take a `host` parameter that
selects the storefront platform — `smartstore` (Naver SmartStore) or `brand`
(Naver Brand Store). Brand Store coverage is the most complete; some SmartStore
calls require an extra identifier (`channel_uid` or `checkout_merchant_no`) and
may return a partial record. Each endpoint page documents its own requirements.

## Credits

Costs are charged per request and reported on the `X-Credits-Used` response
header; the live per-endpoint price is also published at `/public/pricing`. The
standard tier is **5 credits**, with these exceptions:

| Endpoint | Path | Credits |
| - | - | - |
| Web search, News, Blog, Local | `GET /v1/naver/search`, `/news`, `/blog`, `/local` | 8 |
| Place reviews | `GET /v1/naver/place/{place_id}/reviews` | 8 |
| Shopping catalog search, price compare | `GET /v1/naver/shopping/search-catalog`, `/shopping/price-compare` | 8 |
| Shopping bestsellers, insight, keywords | `GET /v1/naver/shopping/bestsellers`, `/shopping/insight`, `/shopping/keywords` | 8 |
| Place detail | `GET /v1/naver/place/{place_id}` | 11 (browser-rendered) |
| Shopping Live broadcast, channel and shortclip detail | `GET /v1/naver/shopping/live/broadcasts/{id}`, `/channels/{id}`, `/shortclips/{id}` | 3 |
| Shopping Live keyword search | `GET /v1/naver/shopping/live/search/keywords` | 3 |
| Review SSR queries, review video key | `GET /v1/naver/reviews/{id}/ssr-queries`, `/reviews/video-inkey` | 3 |
| Autocomplete | `GET /v1/naver/autocomplete` | 2 |
| Shopping categories | `GET /v1/naver/shopping/categories` | 0 (free reference) |
| Everything else | `GET /v1/naver/*` | 5 |

> [!NOTE]
>
> The catalog and price-comparison searches
> ([`/shopping/search-catalog`](https://docs.scrapebadger.com/api-reference/endpoint/naver/shopping-search-catalog)
> and
> [`/shopping/price-compare`](https://docs.scrapebadger.com/api-reference/endpoint/naver/shopping-price-compare))
> clear Naver's shopping challenge in a live browser session, so they are the
> heaviest calls and a page can take up to \~90 seconds.

## Quickstart

```bash cURL theme={null}
curl "https://scrapebadger.com/v1/naver/search?query=제주도+맛집" \
  -H "X-API-Key: YOUR_API_KEY"
```

```javascript Node.js theme={null}
const res = await fetch(
  "https://scrapebadger.com/v1/naver/search?" +
    new URLSearchParams({ query: "제주도 맛집" }),
  { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } },
);
const data = await res.json();
console.log(data.result_count, "results returned");
```

```python Python theme={null}
import requests

res = requests.get(
    "https://scrapebadger.com/v1/naver/search",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"query": "제주도 맛집"},
)
data = res.json()
print(data["result_count"], "results returned")
```

## Other notes

* **Organic `url` values are final destinations** — any Naver redirect wrapper
  is resolved so you get the real target URL.
* **`related_searches[]` and `place_results[]`** appear only when Naver serves
  them for that query.
* **Shopping ids chain together** — take a `category_id` from
  [`/shopping/categories`](https://docs.scrapebadger.com/api-reference/endpoint/naver/shopping-categories), a
  catalogue `nv_mid` from a search or ranking feed, and a storefront slug from a
  product URL to move between the shopping endpoints.
* **Pagination styles vary by endpoint** — content verticals use `page`,
  storefront and live lists use `page`/`size`, and the live channel feeds and
  the place photo viewer use an opaque cursor. Each page documents its own.

## Errors

| Status | Meaning |
| - | - |
| `404` | The place, product or resource does not exist. |
| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. |
| `502` | Unexpected upstream failure — **not billed**. |

> [!TIP]
>
> Start from [`/autocomplete`](https://docs.scrapebadger.com/api-reference/endpoint/naver/autocomplete)
> (2 credits) to expand a seed term into real Naver queries, then run
> [`/search`](https://docs.scrapebadger.com/api-reference/endpoint/naver/search) on each suggestion.

## Run this asynchronously

Calls on this API can run in the background, so you don't hold a connection open while they work. Add one of these to the call:

| Add | What you get |
| - | - |
| `async=true` | The normal response if the call finishes within 25 s. Otherwise `202` with a `request_id`, which you poll at `GET /v1/requests/{request_id}` for free. |
| `callback_url=https://…` | `202` at once. When the call completes, the result is POSTed to your URL, signed with your webhook secret. |
| `Idempotency-Key: <your id>` header | A resent submit returns the first call instead of running it again. |

```bash theme={null}
curl -s "https://scrapebadger.com/v1/...?your=params&async=true" \
  -H "X-API-Key: $SCRAPEBADGER_API_KEY"
# 202 {"request_id": "…", "status": "running", …}, then:
curl -s "https://scrapebadger.com/v1/requests/REQUEST_ID" \
  -H "X-API-Key: $SCRAPEBADGER_API_KEY"
```

An async call is billed once, when it completes. See [Async requests and webhooks](https://docs.scrapebadger.com/long-running-requests.md) for webhooks, signatures and the SDK helpers.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.