diff --git a/api-reference/endpoint/naver/autocomplete.mdx b/api-reference/endpoint/naver/autocomplete.mdx new file mode 100644 index 0000000..f1cdf27 --- /dev/null +++ b/api-reference/endpoint/naver/autocomplete.mdx @@ -0,0 +1,83 @@ +--- +title: "Autocomplete" +api: "GET https://scrapebadger.com/v1/naver/autocomplete" +description: "Get Naver search-box query suggestions for a partial term, each tagged with a type." +--- + +Get Naver's search-box suggestions for a partial term. The cheapest call in +this API — useful for expanding a seed keyword into real Naver queries before +running [`/search`](/api-reference/endpoint/naver/search) on each one. Each +suggestion is tagged with a `type` describing what kind of entity it points to. + +**Credits:** 1 + +## Authorization + + + Your ScrapeBadger API key. + + +## Query Parameters + + + Partial search term, e.g. `제주`. + + +## Response + +Echo of the requested term. +Number of suggestions. + + Suggested queries, in Naver's order. + + + The suggested query text. + The suggestion kind, e.g. `keyword`, `place`. + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/autocomplete?query=제주" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/autocomplete?" + + new URLSearchParams({ query: "제주" }), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const { suggestions } = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/autocomplete", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"query": "제주"}, +) +suggestions = res.json()["suggestions"] +``` + + + +```json Response +{ + "query": "제주", + "result_count": 6, + "suggestions": [ + { "query": "제주도 맛집", "type": "keyword" }, + { "query": "제주도 여행", "type": "keyword" }, + { "query": "제주 날씨", "type": "keyword" }, + { "query": "제주항공", "type": "keyword" }, + { "query": "제주 렌트카", "type": "keyword" }, + { "query": "제주도 가볼만한곳", "type": "keyword" } + ] +} +``` diff --git a/api-reference/endpoint/naver/blog.mdx b/api-reference/endpoint/naver/blog.mdx new file mode 100644 index 0000000..d04b686 --- /dev/null +++ b/api-reference/endpoint/naver/blog.mdx @@ -0,0 +1,103 @@ +--- +title: "Blog Search" +api: "GET https://scrapebadger.com/v1/naver/blog" +description: "Search Naver Blog — title, blog name, author, snippet and absolute publish time per post, with thumbnail imagery." +--- + +Search Naver Blog, the dominant consumer-review and how-to corpus in Korea. +Each post carries the title, the blog it lives on, the author, a snippet and +an **absolute publish time** (`published_at`), plus a thumbnail when one is +shown. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Query Parameters + + + Search keywords, e.g. `에어프라이어 추천`. + + + + 1-based result page for pagination. + + +## Response + +Echo of the requested query. +The page that was fetched. +Posts returned. + + Blog posts. + + + 1-based rank. + + Destination post URL — any Naver redirect is resolved. + + The blog the post lives on. + Post author / blogger handle. + Raw publish date as displayed by Naver. + ISO 8601 UTC publish time. + Post thumbnail, when present. + + +The Naver Blog SERP URL for this query and page. + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/blog?query=에어프라이어+추천" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/blog?" + + new URLSearchParams({ query: "에어프라이어 추천" }), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/blog", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"query": "에어프라이어 추천"}, +) +data = res.json() +``` + + + +```json Response +{ + "query": "에어프라이어 추천", + "page": 1, + "result_count": 10, + "results": [ + { + "position": 1, + "title": "2026 에어프라이어 추천 TOP 5 솔직 후기", + "url": "https://blog.naver.com/example/223456789012", + "snippet": "직접 써본 에어프라이어 5종을 용량, 소비전력, 청소 편의성 기준으로 비교했습니다...", + "blog_name": "살림꿀팁 블로그", + "author": "살림꾼", + "published": "2026.08.06.", + "published_at": "2026-08-06T09:21:00+00:00", + "thumbnail_url": "https://blogthumb.example.net/2026080612345.jpg" + } + ], + "url": "https://search.naver.com/search.naver?where=blog&query=에어프라이어+추천" +} +``` diff --git a/api-reference/endpoint/naver/cafe.mdx b/api-reference/endpoint/naver/cafe.mdx new file mode 100644 index 0000000..62763c0 --- /dev/null +++ b/api-reference/endpoint/naver/cafe.mdx @@ -0,0 +1,105 @@ +--- +title: "Cafe Search" +api: "GET https://scrapebadger.com/v1/naver/cafe" +description: "Search the Naver Cafe vertical — community posts with cafe name, snippet, comment count and absolute publish times." +--- + +Search the **Naver Cafe** vertical — posts from Naver's community forums. Each result carries the post title and URL, the hosting cafe's name and URL, a snippet, the comment count and an absolute publish timestamp. Returns 30 results per page. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Query Parameters + + + Search keywords. + + + + 1-based result page. Each page returns 30 posts. + + +## Response + + + +Posts returned in this response. + + Cafe posts. + + + 1-based rank within this page. + + Post URL. + The hosting cafe's name. + The hosting cafe's URL. + + Publish time as shown by Naver. + Absolute publish timestamp (ISO 8601). + + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/cafe?query=캠핑+장비+추천&page=1" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/cafe?" + + new URLSearchParams({"query": "캠핑 장비 추천", "page": "1"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/cafe", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"query": "캠핑 장비 추천", "page": "1"}, +) +data = res.json() +``` + + + +```json Response +{ + "query": "캠핑 장비 추천", + "page": 1, + "result_count": 30, + "results": [ + { + "position": 1, + "title": "입문자용 캠핑 장비 추천 리스트", + "url": "https://cafe.naver.com/camping/123456", + "cafe_name": "캠핑러버", + "cafe_url": "https://cafe.naver.com/camping", + "snippet": "처음 캠핑 시작하시는 분들께...", + "published": "2026.08.05.", + "published_at": "2026-08-05T00:00:00+09:00", + "comment_count": 42 + } + ] +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/clip.mdx b/api-reference/endpoint/naver/clip.mdx new file mode 100644 index 0000000..2bf3c5e --- /dev/null +++ b/api-reference/endpoint/naver/clip.mdx @@ -0,0 +1,101 @@ +--- +title: "Clip Search" +api: "GET https://scrapebadger.com/v1/naver/clip" +description: "Search the Naver Clip vertical — short-form vertical videos with author, view count and publish time." +--- + +Search the **Naver Clip** vertical — Naver's short-form, vertical-video feed. Each result carries the clip title and URL, author, view count and an absolute publish timestamp. Returns 24 clips per page. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Query Parameters + + + Search keywords. + + + + 1-based result page. Each page returns up to 24 clips. + + +## Response + + + + + + Clips. + + + + + Clip URL. + + + + Absolute publish timestamp (ISO 8601). + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/clip?query=홈카페+레시피&page=1" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/clip?" + + new URLSearchParams({"query": "홈카페 레시피", "page": "1"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/clip", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"query": "홈카페 레시피", "page": "1"}, +) +data = res.json() +``` + + + +```json Response +{ + "query": "홈카페 레시피", + "page": 1, + "result_count": 24, + "results": [ + { + "position": 1, + "title": "1분 홈카페 아인슈페너", + "url": "https://m.clip.naver.com/clips/98765", + "author": "카페인중독", + "view_count": 120345, + "published": "2026.07.11.", + "published_at": "2026-07-11T00:00:00+09:00" + } + ] +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/group-review-summary.mdx b/api-reference/endpoint/naver/group-review-summary.mdx new file mode 100644 index 0000000..e731d91 --- /dev/null +++ b/api-reference/endpoint/naver/group-review-summary.mdx @@ -0,0 +1,82 @@ +--- +title: "Get Group Review Summary" +api: "GET https://scrapebadger.com/v1/naver/product-groups/{group_product_no}/review-summary" +description: "Group-level rating summary for a Naver storefront variant group — the combined score and review count across variants." +--- + +Fetch the **group-level rating summary** for a storefront variant group — the combined average score and review count across all variants. Same shape as the per-product [`/products/{origin_product_no}/review-summary`](/api-reference/endpoint/naver/product-review-summary). + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Path Parameters + + + The variant group's product number (from [`/products/{origin_product_no}/group`](/api-reference/endpoint/naver/product-group)). + + +## Query Parameters + + + Leaf category id for the group. + + +## Response + + + + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/product-groups/G100200300/review-summary?leaf_category_id=50002345" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/product-groups/G100200300/review-summary?" + + new URLSearchParams({"leaf_category_id": "50002345"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/product-groups/G100200300/review-summary", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"leaf_category_id": "50002345"}, +) +data = res.json() +``` + + + +```json Response +{ + "group_product_no": "G100200300", + "leaf_category_id": "50002345", + "review_count": 15320, + "average_review_score": 4.7 +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `404` | The requested resource does not exist or has been removed. | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/image.mdx b/api-reference/endpoint/naver/image.mdx new file mode 100644 index 0000000..9f41e57 --- /dev/null +++ b/api-reference/endpoint/naver/image.mdx @@ -0,0 +1,107 @@ +--- +title: "Image Search" +api: "GET https://scrapebadger.com/v1/naver/image" +description: "Search the Naver image vertical — 100 images per page with thumbnail, full-resolution URL, dimensions and source." +--- + +Search the **Naver image** vertical. Backed by Naver's image JSON API, it returns up to 100 images per page, each with its thumbnail and full-resolution URLs, dimensions, title and source site. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Query Parameters + + + Search keywords. + + + + 1-based result page. Each page returns up to 100 images. + + +## Response + + + + + + Images. + + + + Naver image id. + + The page the image was found on. + Source site name. + + Full-resolution image URL. + + + + Absolute publish timestamp (ISO 8601), when present. + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/image?query=한라산+설경&page=1" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/image?" + + new URLSearchParams({"query": "한라산 설경", "page": "1"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/image", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"query": "한라산 설경", "page": "1"}, +) +data = res.json() +``` + + + +```json Response +{ + "query": "한라산 설경", + "page": 1, + "result_count": 100, + "results": [ + { + "position": 1, + "img_id": "blog_12345", + "title": "한라산 겨울 설경", + "url": "https://blog.example.com/hallasan", + "source": "제주여행블로그", + "thumbnail_url": "https://search-phinf.example.net/thumb/12345.jpg", + "original_url": "https://blogfiles.example.net/hallasan_full.jpg", + "width": 1920, + "height": 1280 + } + ] +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/kin.mdx b/api-reference/endpoint/naver/kin.mdx new file mode 100644 index 0000000..0e861ff --- /dev/null +++ b/api-reference/endpoint/naver/kin.mdx @@ -0,0 +1,107 @@ +--- +title: "Knowledge iN Search" +api: "GET https://scrapebadger.com/v1/naver/kin" +description: "Search Naver Knowledge iN (지식iN) — community question-and-answer threads with the question, best answer and author." +--- + +Search **Naver Knowledge iN** (`지식iN`), Korea's largest community Q&A service. Each result carries the question title and URL, the question body, the accepted answer, the author and an absolute publish timestamp. Returns 10 results per page. + +**Credits:** 5 + + + Knowledge iN exposes only the first page of results — the upstream “더보기” (load-more) control is JavaScript-driven and has no stable page cursor, so `page` above 1 returns the same first page. + + +## Authorization + + + Your ScrapeBadger API key. + + +## Query Parameters + + + Search keywords. + + + + 1-based result page (see the note above). + + +## Response + + + + + + Knowledge iN threads. + + + + + Thread URL. + The question body. + The accepted / top answer. + + + Absolute publish timestamp (ISO 8601). + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/kin?query=노트북+발열+해결&page=1" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/kin?" + + new URLSearchParams({"query": "노트북 발열 해결", "page": "1"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/kin", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"query": "노트북 발열 해결", "page": "1"}, +) +data = res.json() +``` + + + +```json Response +{ + "query": "노트북 발열 해결", + "page": 1, + "result_count": 10, + "results": [ + { + "position": 1, + "title": "노트북 발열 심한데 어떻게 하나요?", + "url": "https://kin.naver.com/qna/detail.naver?d1id=1&dirId=1&docId=456789", + "question": "게임만 하면 노트북이 너무 뜨거워요...", + "answer": "쿨링패드 사용과 서멀구리스 재도포를 추천합니다...", + "author": "컴닥터", + "published": "2026.07.30.", + "published_at": "2026-07-30T00:00:00+09:00" + } + ] +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/local.mdx b/api-reference/endpoint/naver/local.mdx new file mode 100644 index 0000000..337a25a --- /dev/null +++ b/api-reference/endpoint/naver/local.mdx @@ -0,0 +1,107 @@ +--- +title: "Local Search" +api: "GET https://scrapebadger.com/v1/naver/local" +description: "Search Naver Place — local businesses with rating, review count, live opening status, category and addresses." +--- + +Search Naver Place, Korea's dominant local-business directory. Each result +carries the `place_id` (use it with +[Place Detail](/api-reference/endpoint/naver/place) and +[Place Reviews](/api-reference/endpoint/naver/place-reviews)), rating and +review count, live opening status, category, both road and lot-number +addresses, and any badges Naver attaches. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Query Parameters + + + Place search keywords, e.g. `강남 파스타` or a business name. + + +## Response + +Echo of the requested query. +Places returned. + + Local places. + + + Naver Place id — use it with the detail and reviews endpoints. + + e.g. `파스타`, `카페`. + Lot-number (jibun) address. + Road-name (doro) address. + + Average visitor rating. + + Whether the place is open right now. + Human-readable status, e.g. `영업 중`, `21:00에 영업 종료`. + Labels Naver attaches, e.g. `예약`, `주차`. + Naver Place page URL. + 1-based rank within the results. + + +The Naver Place search URL for this query. + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/local?query=강남+파스타" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/local?" + + new URLSearchParams({ query: "강남 파스타" }), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/local", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"query": "강남 파스타"}, +) +data = res.json() +``` + + + +```json Response +{ + "query": "강남 파스타", + "result_count": 10, + "results": [ + { + "place_id": "1234567890", + "name": "트라토리아 강남", + "category": "파스타", + "address": "서울특별시 강남구 역삼동 123-45", + "road_address": "서울특별시 강남구 테헤란로 12길 34", + "phone": "02-555-1234", + "rating": 4.6, + "review_count": 1823, + "is_open": true, + "open_status_text": "영업 중 · 22:00에 영업 종료", + "badges": ["예약", "포장"], + "url": "https://map.naver.com/p/entry/place/1234567890", + "rank": 1 + } + ], + "url": "https://map.naver.com/p/search/강남+파스타" +} +``` diff --git a/api-reference/endpoint/naver/news.mdx b/api-reference/endpoint/naver/news.mdx new file mode 100644 index 0000000..fc4459c --- /dev/null +++ b/api-reference/endpoint/naver/news.mdx @@ -0,0 +1,100 @@ +--- +title: "News Search" +api: "GET https://scrapebadger.com/v1/naver/news" +description: "Search Naver News — headline, source, snippet and absolute publish time per article, with thumbnail imagery." +--- + +Search Naver News. Each article carries the headline, the publishing source, +a snippet and an **absolute publish time** (`published_at`) alongside Naver's +raw displayed date, plus a thumbnail when one is shown. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Query Parameters + + + Search keywords, e.g. `금리 인상`. + + + + 1-based result page for pagination. + + +## Response + +Echo of the requested query. +The page that was fetched. +Articles returned. + + News articles. + + + 1-based rank. + + Destination article URL — any Naver redirect is resolved. + + Publisher name. + Raw publish date as displayed by Naver. + ISO 8601 UTC publish time. + Article thumbnail, when present. + + +The Naver News SERP URL for this query and page. + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/news?query=금리+인상" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/news?" + + new URLSearchParams({ query: "금리 인상" }), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/news", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"query": "금리 인상"}, +) +data = res.json() +``` + + + +```json Response +{ + "query": "금리 인상", + "page": 1, + "result_count": 10, + "results": [ + { + "position": 1, + "title": "한국은행, 기준금리 동결 결정", + "url": "https://news.example.co.kr/article/2026080712345", + "snippet": "한국은행 금융통화위원회는 기준금리를 현 수준에서 동결하기로 결정했다...", + "source": "연합뉴스", + "published": "2026.08.07.", + "published_at": "2026-08-07T05:03:00+00:00", + "thumbnail_url": "https://imgnews.example.co.kr/thumb/2026080712345.jpg" + } + ], + "url": "https://search.naver.com/search.naver?where=news&query=금리+인상" +} +``` diff --git a/api-reference/endpoint/naver/place-photos.mdx b/api-reference/endpoint/naver/place-photos.mdx new file mode 100644 index 0000000..8fed41d --- /dev/null +++ b/api-reference/endpoint/naver/place-photos.mdx @@ -0,0 +1,118 @@ +--- +title: "Get Place Photos" +api: "GET https://scrapebadger.com/v1/naver/place/{place_id}/photos" +description: "Photo viewer for a Naver Place — visitor-review or owner photos with full-resolution URLs and cursor pagination." +--- + +Fetch the photo stream for a single Naver Place. Choose between visitor-review photos and the owner/place photos. Each entry carries the full-resolution and thumbnail URLs, dimensions, a caption and a date. Results are cursor-paginated. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Path Parameters + + + Naver Place id (digits), e.g. `1234567890`. Take it from a [`/local`](/api-reference/endpoint/naver/local) result. + + +## Query Parameters + + + `placeReview` for visitor-review photos, or `biz` for the owner/place photos. + + + + Opaque pagination cursor. Pass the `next_cursor` from the previous response to fetch the next batch. + + +## Response + + +Echo of the requested source. +Photos returned in this batch. + + Photos (batch size varies, ~40–60). + + + + Full-resolution media URL. + + + + Caption, when present. + Date as displayed. + `image` or `video`. + + Rating from the attached review, when present. + + +Cursor for the next batch, or `null` at the end. +Whether another batch is available. + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/place/1234567890/photos?media_source=placeReview" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/place/1234567890/photos?" + + new URLSearchParams({"media_source": "placeReview"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/place/1234567890/photos", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"media_source": "placeReview"}, +) +data = res.json() +``` + + + +```json Response +{ + "place_id": "1234567890", + "media_source": "placeReview", + "result_count": 48, + "photos": [ + { + "photo_id": "a1b2c3", + "original_url": "https://pup-review-phinf.example.net/a1b2c3.jpg", + "thumbnail_url": "https://pup-review-phinf.example.net/a1b2c3_t.jpg", + "width": 1080, + "height": 1080, + "title": "봉골레 파스타", + "date_text": "2026.07.02.", + "media_format": "image", + "media_source": "placeReview", + "rating": 5 + } + ], + "next_cursor": "eyJsYXN0Q3Vyc29yIjoiNDgifQ==", + "has_next": true +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `404` | The requested resource does not exist or has been removed. | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/place-reviews.mdx b/api-reference/endpoint/naver/place-reviews.mdx new file mode 100644 index 0000000..79a201a --- /dev/null +++ b/api-reference/endpoint/naver/place-reviews.mdx @@ -0,0 +1,102 @@ +--- +title: "Get Place Reviews" +api: "GET https://scrapebadger.com/v1/naver/place/{place_id}/reviews" +description: "Visitor reviews for a Naver Place — rating, body, author, visit count, voted keywords and photos per review." +--- + +Fetch the visitor review stream for a Naver Place. Each review carries its +rating, body text, author, how many times they have visited, the voted +keywords (Naver's structured "what was good" tags), any photos, and whether the +owner has replied. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Path Parameters + + + Naver Place id, e.g. `1234567890`. Take it from `place_id` on a + [`/local`](/api-reference/endpoint/naver/local) result. + + +## Response + + +Total reviews Naver reports for the place. +Average visitor rating. +Reviews returned in this response. + + Visitor reviews. + + + + + Review text. + + How many times the author has visited. + Where the review originated, e.g. a receipt- or booking-verified visit. + Raw visit date as displayed by Naver. + ISO 8601 UTC visit date. + Naver's structured "what was good" tags, e.g. `음식이 맛있어요`. + Photo URLs attached to the review. + Whether the owner has replied. + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/place/1234567890/reviews" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/place/1234567890/reviews", + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/place/1234567890/reviews", + headers={"X-API-Key": "YOUR_API_KEY"}, +) +data = res.json() +``` + + + +```json Response +{ + "place_id": "1234567890", + "review_count": 1823, + "rating": 4.6, + "result_count": 10, + "reviews": [ + { + "review_id": "5f3a9b2c7d1e", + "rating": 5, + "body": "봉골레 파스타가 정말 맛있었어요. 재방문 의사 100%입니다.", + "author": "맛집탐험가", + "visit_count": 3, + "origin_type": "receipt", + "visited": "2026.08.01.", + "visited_at": "2026-08-01T00:00:00+00:00", + "voted_keywords": ["음식이 맛있어요", "매장이 청결해요"], + "images": ["https://pup-review.example.net/5f3a9b2c7d1e_1.jpg"], + "has_reply": true + } + ] +} +``` diff --git a/api-reference/endpoint/naver/place.mdx b/api-reference/endpoint/naver/place.mdx new file mode 100644 index 0000000..35257eb --- /dev/null +++ b/api-reference/endpoint/naver/place.mdx @@ -0,0 +1,122 @@ +--- +title: "Get Place Detail" +api: "GET https://scrapebadger.com/v1/naver/place/{place_id}" +description: "Full Naver Place detail — category, addresses, phone, website, rating, menus, photos and map coordinates." +--- + +Fetch a single Naver Place by its `place_id`. Returns the full profile: the +primary category and every category it is listed under, both road and +lot-number addresses, phone, website, rating and review count, the menu with +prices, photos, and the map coordinates. + +**Credits:** 8 + + + This endpoint is **browser-rendered** — the richest and slowest call in this + API, hence 8 credits. Take a `place_id` from a + [`/local`](/api-reference/endpoint/naver/local) result or from the web SERP's + `place_results[]`. + + +## Authorization + + + Your ScrapeBadger API key. + + +## Path Parameters + + + Naver Place id, e.g. `1234567890`. Take it from `place_id` on a + [`/local`](/api-reference/endpoint/naver/local) result or from a + `map.naver.com/p/entry/place/{place_id}` URL. + + +## Response + + + +Primary category, e.g. `파스타`. +Every category the place is listed under. +Lot-number (jibun) address. +Road-name (doro) address. + + +Average visitor rating. + + + Menu items with prices. + + + + Price as displayed, e.g. `18,000원`. + + +Photo URLs. + + +Naver Place page URL. +The underlying page the detail was rendered from. + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/place/1234567890" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/place/1234567890", + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const place = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/place/1234567890", + headers={"X-API-Key": "YOUR_API_KEY"}, +) +place = res.json() +``` + + + +```json Response +{ + "place_id": "1234567890", + "name": "트라토리아 강남", + "category": "파스타", + "categories": ["파스타", "이탈리아음식", "레스토랑"], + "address": "서울특별시 강남구 역삼동 123-45", + "road_address": "서울특별시 강남구 테헤란로 12길 34", + "phone": "02-555-1234", + "website": "https://trattoria-gangnam.example.com", + "rating": 4.6, + "review_count": 1823, + "menus": [ + { "name": "봉골레 파스타", "price": "18,000원" }, + { "name": "트러플 크림 파스타", "price": "22,000원" } + ], + "images": [ + "https://ldb-phinf.example.net/place/1234567890_1.jpg", + "https://ldb-phinf.example.net/place/1234567890_2.jpg" + ], + "latitude": 37.500123, + "longitude": 127.036456, + "url": "https://map.naver.com/p/entry/place/1234567890", + "source_url": "https://pcmap.place.naver.com/restaurant/1234567890/home" +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `404` | The place does not exist or has been removed. | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | diff --git a/api-reference/endpoint/naver/product-detail.mdx b/api-reference/endpoint/naver/product-detail.mdx new file mode 100644 index 0000000..00c6d99 --- /dev/null +++ b/api-reference/endpoint/naver/product-detail.mdx @@ -0,0 +1,139 @@ +--- +title: "Get Product Detail" +api: "GET https://scrapebadger.com/v1/naver/products/{product_no}" +description: "Full product detail for a Naver storefront product — price, options, delivery, seller, category and review stats." +--- + +Fetch **full product detail** for a Naver storefront product by its channel product number. Returns the name, price and discount, rating and review count, brand and manufacturer, images, options, delivery, seller and category. + +**Credits:** 5 + + + Brand Store products return the full record. For a SmartStore product, pass `store_url` or `channel_uid`; the response may be a partial enrichment, in which case `detail_source` is `smartstore_enrich` and `missing_fields[]` lists the fields that could not be filled. + + +## Authorization + + + Your ScrapeBadger API key. + + +## Path Parameters + + + Channel product number (the storefront `/products/{no}` id). + + +## Query Parameters + + + `brand` or `smartstore`. + + + + Store slug. Required when `channel_uid` is omitted — resolves the channel and Referer. + + + + Opaque storefront channel key. Overrides store-home resolution. + + +## Response + + + + + + + + + + + +Purchasable option combinations. +Delivery terms. +Seller / channel summary. +Category path. +ISO registration time, when the full-detail schema is obtained. +ISO last-modified time, when the full-detail schema is obtained. +`smartstore_enrich` on a SmartStore partial record; omitted otherwise. +Leaf field paths the partial lane could not fill; omitted otherwise. + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/products/7001234567?host=brand&store_url=nike" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/products/7001234567?" + + new URLSearchParams({"host": "brand", "store_url": "nike"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/products/7001234567", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"host": "brand", "store_url": "nike"}, +) +data = res.json() +``` + + + +```json Response +{ + "product_no": "7001234567", + "name": "나이키 에어포스 1 '07", + "price": 139000, + "discount_price": 119000, + "discount_rate": 14, + "rating": 4.8, + "review_count": 5231, + "brand": "나이키", + "manufacturer": "나이키", + "images": [ + "https://shop-phinf.example.net/7001234567_1.jpg" + ], + "options": [ + { + "name": "사이즈", + "values": [ + "250", + "260", + "270" + ] + } + ], + "delivery": { + "fee": 0, + "type": "오늘출발" + }, + "seller": { + "channel_name": "나이키 공식스토어", + "channel_uid": "2sV!nike01" + }, + "category": { + "whole_category_name": "패션잡화>운동화" + }, + "registered_at": "2026-03-01T00:00:00+09:00", + "modified_at": "2026-08-01T00:00:00+09:00" +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `404` | The requested resource does not exist or has been removed. | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/product-group.mdx b/api-reference/endpoint/naver/product-group.mdx new file mode 100644 index 0000000..910a8dd --- /dev/null +++ b/api-reference/endpoint/naver/product-group.mdx @@ -0,0 +1,78 @@ +--- +title: "Get Product Group" +api: "GET https://scrapebadger.com/v1/naver/products/{origin_product_no}/group" +description: "The storefront variant group of a product — the group id and the member origin product numbers." +--- + +Resolve the **variant group** a product belongs to. SmartStore sellers group colour/size variants under one group; this returns the group id and the member `originProductNo`s so you can fetch each variant. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Path Parameters + + + The product's origin product number. + + +## Response + +Echo of the requested product. +The variant group id, or `null` when the product is not grouped. +Member origin product numbers. + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/products/5123456789/group" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/products/5123456789/group", + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/products/5123456789/group", + headers={"X-API-Key": "YOUR_API_KEY"}, +) +data = res.json() +``` + + + +```json Response +{ + "origin_product_no": "5123456789", + "group_id": "G100200300", + "origin_product_nos": [ + "5123456789", + "5123456790", + "5123456791" + ], + "is_grouped": true +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `404` | The requested resource does not exist or has been removed. | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/product-qna-list.mdx b/api-reference/endpoint/naver/product-qna-list.mdx new file mode 100644 index 0000000..42c73b3 --- /dev/null +++ b/api-reference/endpoint/naver/product-qna-list.mdx @@ -0,0 +1,120 @@ +--- +title: "List Product Q&A" +api: "GET https://scrapebadger.com/v1/naver/products/{origin_product_no}/qnas" +description: "Paginated product Q&A / inquiries for a Naver storefront product." +--- + +List the **product Q&A / inquiries** for a storefront product — shopper questions and the seller's answers, paginated. + +**Credits:** 5 + + + Brand Store products are fully supported. SmartStore Q&A requires `channel_uid` and may be unavailable. + + +## Authorization + + + Your ScrapeBadger API key. + + +## Path Parameters + + + The product's origin product number. + + +## Query Parameters + + + Store/brand slug. + + + + Channel product number (the storefront `/products/{no}` id). + + + + `brand` or `smartstore`. + + + + Storefront channel uid; required for `host=smartstore`. + + + + 1-based page. + + +## Response + + + +Total Q&A entries, when reported. + + Q&A entries. + + + + + + + + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/products/5123456789/qnas?store_url=nike&product_no=7001234567&host=brand&page=1" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/products/5123456789/qnas?" + + new URLSearchParams({"store_url": "nike", "product_no": "7001234567", "host": "brand", "page": "1"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/products/5123456789/qnas", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"store_url": "nike", "product_no": "7001234567", "host": "brand", "page": "1"}, +) +data = res.json() +``` + + + +```json Response +{ + "origin_product_no": "5123456789", + "page": 1, + "total_count": 128, + "qnas": [ + { + "question": "275 사이즈 재입고 언제 되나요?", + "answer": "다음 주 중 재입고 예정입니다.", + "author_masked": "lee****", + "created_at": "2026-07-20T00:00:00+09:00", + "answered_at": "2026-07-21T00:00:00+09:00" + } + ] +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `404` | The requested resource does not exist or has been removed. | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/product-review-summary.mdx b/api-reference/endpoint/naver/product-review-summary.mdx new file mode 100644 index 0000000..770c290 --- /dev/null +++ b/api-reference/endpoint/naver/product-review-summary.mdx @@ -0,0 +1,80 @@ +--- +title: "Get Product Review Summary" +api: "GET https://scrapebadger.com/v1/naver/products/{origin_product_no}/review-summary" +description: "Rating summary for a Naver storefront product — average score, review count, star distribution and media/type counts." +--- + +Fetch the **rating summary** for a storefront product — the average review score, total review count, the star distribution and the media/type breakdowns, without pulling the individual reviews. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Path Parameters + + + The product's origin product number. + + +## Query Parameters + + + Leaf category id for the product. Optional — improves summary resolution when known. + + +## Response + + + + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/products/5123456789/review-summary" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/products/5123456789/review-summary", + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/products/5123456789/review-summary", + headers={"X-API-Key": "YOUR_API_KEY"}, +) +data = res.json() +``` + + + +```json Response +{ + "origin_product_no": "5123456789", + "leaf_category_id": "50002345", + "review_count": 12043, + "average_review_score": 4.8 +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `404` | The requested resource does not exist or has been removed. | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/product-reviews-list.mdx b/api-reference/endpoint/naver/product-reviews-list.mdx new file mode 100644 index 0000000..56a3621 --- /dev/null +++ b/api-reference/endpoint/naver/product-reviews-list.mdx @@ -0,0 +1,134 @@ +--- +title: "List Product Reviews" +api: "GET https://scrapebadger.com/v1/naver/products/{origin_product_no}/reviews" +description: "Paginated review list for a Naver storefront product, with sort control." +--- + +List the **individual reviews** for a storefront product, paginated and sortable. Each review carries its rating, body, author (masked), options purchased and media. + +**Credits:** 5 + + + Brand Store products are fully supported. SmartStore review listing requires a `checkout_merchant_no` and may be unavailable. + + +## Authorization + + + Your ScrapeBadger API key. + + +## Path Parameters + + + The product's origin product number. + + +## Query Parameters + + + Store/brand slug. + + + + Channel product number (the storefront `/products/{no}` id, not the origin product number). + + + + `brand` or `smartstore`. + + + + SmartStore only — passed through when known. + + + + 1-based page. + + + + `REVIEW_RANKING` or `REVIEW_CREATE_DATE_DESC`. + + +## Response + + + + + +Total reviews, when reported. + + Reviews. + + + + + + + The purchased option, when shown. + + + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/products/5123456789/reviews?store_url=nike&product_no=7001234567&host=brand&page=1" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/products/5123456789/reviews?" + + new URLSearchParams({"store_url": "nike", "product_no": "7001234567", "host": "brand", "page": "1"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/products/5123456789/reviews", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"store_url": "nike", "product_no": "7001234567", "host": "brand", "page": "1"}, +) +data = res.json() +``` + + + +```json Response +{ + "origin_product_no": "5123456789", + "page": 1, + "page_size": 20, + "sort": "REVIEW_RANKING", + "total_count": 5231, + "reviews": [ + { + "review_id": "r900100", + "rating": 5, + "content": "사이즈 정사이즈이고 배송 빨라요", + "author_masked": "kim****", + "option": "270", + "created_at": "2026-07-28T00:00:00+09:00", + "images": [ + "https://review-phinf.example.net/r900100.jpg" + ] + } + ] +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `404` | The requested resource does not exist or has been removed. | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/review-detail.mdx b/api-reference/endpoint/naver/review-detail.mdx new file mode 100644 index 0000000..4820b67 --- /dev/null +++ b/api-reference/endpoint/naver/review-detail.mdx @@ -0,0 +1,96 @@ +--- +title: "Get Review Detail" +api: "GET https://scrapebadger.com/v1/naver/reviews/{review_id}" +description: "Commerce review detail by review id — fetch one or more Naver storefront reviews by their ids." +--- + +Fetch **commerce review detail** by review id. Accepts one or more comma-separated ids and returns the full review objects, reporting any ids that could not be found. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Path Parameters + + + A review id, or several comma-separated ids. + + +## Response + +The ids requested. + + The resolved reviews. + + + + + + + + + + +Requested ids that could not be resolved. + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/reviews/r900100" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/reviews/r900100", + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/reviews/r900100", + headers={"X-API-Key": "YOUR_API_KEY"}, +) +data = res.json() +``` + + + +```json Response +{ + "requested_ids": [ + "r900100" + ], + "reviews": [ + { + "review_id": "r900100", + "rating": 5, + "content": "사이즈 정사이즈이고 배송 빨라요", + "author_masked": "kim****", + "created_at": "2026-07-28T00:00:00+09:00", + "images": [ + "https://review-phinf.example.net/r900100.jpg" + ] + } + ], + "missing_ids": [] +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `404` | The requested resource does not exist or has been removed. | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/review-ssr-queries.mdx b/api-reference/endpoint/naver/review-ssr-queries.mdx new file mode 100644 index 0000000..cb6da45 --- /dev/null +++ b/api-reference/endpoint/naver/review-ssr-queries.mdx @@ -0,0 +1,78 @@ +--- +title: "Get Review SSR Queries" +api: "GET https://scrapebadger.com/v1/naver/reviews/{review_id}/ssr-queries" +description: "The server-rendered page query recipes for a review — a continuation helper that exposes the queries behind the review page." +--- + +A **continuation helper** that returns the server-rendered page query recipes behind a review — the queries and variables the review page itself issues. Useful for advanced continuation and debugging. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Path Parameters + + + The review id. + + +## Response + + +The review page the recipes were extracted from. +The query recipes keyed by name. + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/reviews/r900100/ssr-queries" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/reviews/r900100/ssr-queries", + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/reviews/r900100/ssr-queries", + headers={"X-API-Key": "YOUR_API_KEY"}, +) +data = res.json() +``` + + + +```json Response +{ + "review_id": "r900100", + "source_url": "https://m.smartstore.naver.com/plusink/products/5123456789/reviews/r900100", + "queries": { + "getReviewDetail": { + "variables": { + "reviewId": "r900100" + } + } + } +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `404` | The requested resource does not exist or has been removed. | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/review-video-inkey.mdx b/api-reference/endpoint/naver/review-video-inkey.mdx new file mode 100644 index 0000000..f37fdce --- /dev/null +++ b/api-reference/endpoint/naver/review-video-inkey.mdx @@ -0,0 +1,75 @@ +--- +title: "Get Review Video Key" +api: "GET https://scrapebadger.com/v1/naver/reviews/video-inkey" +description: "Mint the video playback key (inKey) for a review-attached video from its attachVid and videoStamp." +--- + +Mint the **video playback key** (`inKey`) for a video attached to a review. Pass the `attach_vid` and the `videoStamp` from the review's attachment and receive the video id and its playback key, which the player needs to stream the clip. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Query Parameters + + + The attached video id (`attachVid`). + + + + The `videoStamp` from the review attachment (type `M`). + + +## Response + + +The playback key, or `null` when it could not be minted. + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/reviews/video-inkey?attach_vid=A1B2C3D4&stamp=1699999999" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/reviews/video-inkey?" + + new URLSearchParams({"attach_vid": "A1B2C3D4", "stamp": "1699999999"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/reviews/video-inkey", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"attach_vid": "A1B2C3D4", "stamp": "1699999999"}, +) +data = res.json() +``` + + + +```json Response +{ + "video_id": "A1B2C3D4", + "in_key": "V_abcdef123456" +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/search-web.mdx b/api-reference/endpoint/naver/search-web.mdx new file mode 100644 index 0000000..2c1a5c2 --- /dev/null +++ b/api-reference/endpoint/naver/search-web.mdx @@ -0,0 +1,99 @@ +--- +title: "Web Vertical Search" +api: "GET https://scrapebadger.com/v1/naver/search/web" +description: "Naver's dedicated web-document vertical SERP — 15 organic documents per page with resolved destination URLs." +--- + +Search Naver's **web-document vertical** (the `웹사이트` tab). Unlike the integrated [`/search`](/api-reference/endpoint/naver/search) SERP, this is the pure web-document feed: 15 organic results per page, each with its resolved destination URL, display URL and snippet. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Query Parameters + + + Search keywords, e.g. `제주도 맛집`. + + + + 1-based result page. Each page returns 15 documents. + + +## Response + +Echo of the requested query. +The page that was fetched. +Organic results returned in this response. + + Organic web documents. + + + 1-based rank within this page. + + Destination URL — any Naver redirect is resolved. + Human-readable URL shown by Naver. + + + +The Naver web-vertical SERP URL for this query and page. + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/search/web?query=제주도+맛집&page=1" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/search/web?" + + new URLSearchParams({"query": "제주도 맛집", "page": "1"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/search/web", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"query": "제주도 맛집", "page": "1"}, +) +data = res.json() +``` + + + +```json Response +{ + "query": "제주도 맛집", + "page": 1, + "result_count": 15, + "results": [ + { + "position": 1, + "title": "제주도 맛집 추천 TOP 20", + "url": "https://blog.example.com/jeju-food", + "display_url": "blog.example.com › jeju-food", + "snippet": "제주 현지인이 추천하는 흑돼지, 고기국수 맛집 정리..." + } + ], + "url": "https://search.naver.com/search.naver?where=web&query=제주도+맛집" +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/search.mdx b/api-reference/endpoint/naver/search.mdx new file mode 100644 index 0000000..1de361b --- /dev/null +++ b/api-reference/endpoint/naver/search.mdx @@ -0,0 +1,115 @@ +--- +title: "Web Search" +api: "GET https://scrapebadger.com/v1/naver/search" +description: "Search the Naver web SERP — organic results, related searches and any local place pack, with resolved destination URLs." +--- + +Search Naver's web SERP. Organic results carry the **resolved destination +URL**, display URL, snippet and source. When Naver shows a local "place" block +for the query, those entries are returned in `place_results[]`. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Query Parameters + + + Search keywords, e.g. `제주도 맛집`. + + + + 1-based result page for pagination. + + +## Response + +Echo of the requested query. +The page that was fetched. +Organic results returned in this response. + + Organic results. + + + 1-based rank within this page. + + Destination URL — any Naver redirect is resolved. + Human-readable URL shown by Naver. + + Site or publisher name. + + +Naver's related query suggestions, when present. + + The local "place" pack Naver shows for the query, when present — same shape as + a [`/local`](/api-reference/endpoint/naver/local) result (`place_id`, `name`, + `category`, `address`, `rating`, `review_count`, `url`, …). + +The Naver SERP URL for this query and page. + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/search?query=제주도+맛집" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +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(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/search", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"query": "제주도 맛집"}, +) +data = res.json() +``` + + + +```json Response +{ + "query": "제주도 맛집", + "page": 1, + "result_count": 10, + "results": [ + { + "position": 1, + "title": "제주도 가볼 만한 맛집 BEST 20", + "url": "https://blog.example.com/jeju-food", + "display_url": "blog.example.com › jeju-food", + "snippet": "제주 현지인이 추천하는 흑돼지, 고기국수, 해산물 맛집을 정리했습니다...", + "source": "제주맛집블로그" + } + ], + "related_searches": ["제주도 흑돼지 맛집", "제주 고기국수", "제주 애월 맛집"], + "place_results": [ + { + "place_id": "1234567890", + "name": "돈사돈", + "category": "돼지고기구이", + "address": "제주특별자치도 제주시 ...", + "rating": 4.5, + "review_count": 2841, + "url": "https://map.naver.com/p/entry/place/1234567890", + "rank": 1 + } + ], + "url": "https://search.naver.com/search.naver?query=제주도+맛집" +} +``` diff --git a/api-reference/endpoint/naver/shopping-bestsellers.mdx b/api-reference/endpoint/naver/shopping-bestsellers.mdx new file mode 100644 index 0000000..a3b8900 --- /dev/null +++ b/api-reference/endpoint/naver/shopping-bestsellers.mdx @@ -0,0 +1,137 @@ +--- +title: "Shopping Bestsellers" +api: "GET https://scrapebadger.com/v1/naver/shopping/bestsellers" +description: "Naver Shopping bestseller product rankings by category, age bracket, sort metric and period." +--- + +Fetch Naver Shopping's bestseller product rankings. Scope the chart by +category, age bracket, the metric it is sorted by and the period. Each product +carries its rank, the `nv_mid` catalogue id, title, price, discount, review +score and count, mall name and imagery. + +**Credits:** 5 + + + This endpoint returns Naver Shopping's **ranking data only**. General product + search and SmartStore storefront listings are not offered. + + +## Authorization + + + Your ScrapeBadger API key. + + +## Query Parameters + + + Category to rank within. `ALL` for the overall chart, or a Naver Shopping + category id. + + + + Age bracket to rank for. `ALL`, or a specific bracket. + + + + The metric the chart is sorted by, e.g. `PRODUCT_CLICK`. + + + + The ranking period, e.g. `DAILY`. + + +## Response + +Echo of the requested category. +Echo of the requested age bracket. +Echo of the requested sort metric. +Echo of the requested period. +When Naver last synced this ranking. +Products returned. + + Ranked products. + + + 1-based rank in the chart. + Naver Shopping catalogue id. + + List price in KRW. + Discounted price in KRW, when on offer. + Discount percentage, when on offer. + Average review score. + + The mall selling the product. + + + Whether the entry is a sponsored placement. + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/shopping/bestsellers?category_id=ALL&age_type=ALL&sort_type=PRODUCT_CLICK&period_type=DAILY" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/shopping/bestsellers?" + + new URLSearchParams({ + category_id: "ALL", + age_type: "ALL", + sort_type: "PRODUCT_CLICK", + period_type: "DAILY", + }), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/shopping/bestsellers", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={ + "category_id": "ALL", + "age_type": "ALL", + "sort_type": "PRODUCT_CLICK", + "period_type": "DAILY", + }, +) +data = res.json() +``` + + + +```json Response +{ + "category_id": "ALL", + "age_type": "ALL", + "sort_type": "PRODUCT_CLICK", + "period_type": "DAILY", + "sync_date": "2026-08-07T00:00:00+00:00", + "result_count": 100, + "products": [ + { + "rank": 1, + "nv_mid": "82613579214", + "title": "삼성전자 갤럭시 버즈3 프로", + "price": 279000, + "discount_price": 229000, + "discount_rate": 18, + "review_score": 4.8, + "review_count": 12043, + "mall_name": "삼성전자 공식스토어", + "product_url": "https://shopping.naver.com/catalog/82613579214", + "image_url": "https://shopping-phinf.example.net/82613579214.jpg", + "is_ad": false + } + ] +} +``` diff --git a/api-reference/endpoint/naver/shopping-brand-categories.mdx b/api-reference/endpoint/naver/shopping-brand-categories.mdx new file mode 100644 index 0000000..89dd698 --- /dev/null +++ b/api-reference/endpoint/naver/shopping-brand-categories.mdx @@ -0,0 +1,89 @@ +--- +title: "Shopping Brand Categories" +api: "GET https://scrapebadger.com/v1/naver/shopping/brand-categories" +description: "One level of the Naver Shopping brand-ranking category tree — DIV1 roots or the DIV2 children of a parent id." +--- + +Walk the **brand-ranking category tree** that scopes [`/shopping/brand-rank`](/api-reference/endpoint/naver/shopping-brand-rank). With no `parent_id` it returns the DIV1 roots; pass an 8-digit `parent_id` to return its DIV2 children. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Query Parameters + + + An 8-digit DIV1 category id to list its DIV2 children. Omit for the roots. + + +## Response + +`DIV1` or `DIV2`. +Echo of the requested parent, or `null` for roots. + + + Categories at this level. + + + + + + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/shopping/brand-categories?parent_id=50000000" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/shopping/brand-categories?" + + new URLSearchParams({"parent_id": "50000000"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/shopping/brand-categories", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"parent_id": "50000000"}, +) +data = res.json() +``` + + + +```json Response +{ + "depth": "DIV2", + "parent_id": "50000000", + "result_count": 9, + "categories": [ + { + "category_id": "50000167", + "category_name": "여성의류", + "image_url": "https://shopping-phinf.example.net/brandcat/50000167.jpg" + } + ] +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/shopping-brand-rank.mdx b/api-reference/endpoint/naver/shopping-brand-rank.mdx new file mode 100644 index 0000000..3f64fe6 --- /dev/null +++ b/api-reference/endpoint/naver/shopping-brand-rank.mdx @@ -0,0 +1,127 @@ +--- +title: "Shopping Brand Rankings" +api: "GET https://scrapebadger.com/v1/naver/shopping/brand-rank" +description: "Naver Shopping brand ranking — the top 20 brands for a category, age bracket and period." +--- + +Fetch Naver Shopping's **brand ranking** — the top 20 brands for a category, scoped by age bracket, sort metric and period. Each entry carries the brand's rank, name, logo, storefront URL and movement status. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Query Parameters + + + `A` for the overall chart, or an 8-digit brand-ranking category id. + + + + Age bracket, e.g. `ALL`, `MEN_20`, `WOMEN_30`. + + + + `BRAND_POPULAR` or `BRAND_ISSUE`. + + + + `WEEKLY` or `MONTHLY`. + + +## Response + + + + + +Brands returned (20). + + Ranked brands. + + + + + + Movement status versus the previous period. + + + + + + + + + Absolute sync timestamp (ISO 8601). + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/shopping/brand-rank?category_id=A&period_type=WEEKLY" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/shopping/brand-rank?" + + new URLSearchParams({"category_id": "A", "period_type": "WEEKLY"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/shopping/brand-rank", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"category_id": "A", "period_type": "WEEKLY"}, +) +data = res.json() +``` + + + +```json Response +{ + "category_id": "A", + "age_type": "ALL", + "sort_type": "BRAND_POPULAR", + "period_type": "WEEKLY", + "result_count": 20, + "brands": [ + { + "rank": 1, + "rank_id": "b1", + "title": "나이키", + "status": "STABLE", + "chart_type": "POPULAR", + "tags": [ + "스포츠" + ], + "brand_seq": "12345", + "brand_channel_seq": "67890", + "brand_name": "나이키", + "brand_logo_url": "https://shopping-phinf.example.net/brand/12345.png", + "brand_url": "https://brand.naver.com/nike", + "sync_date": "2026-08-07", + "synced_at": "2026-08-07T00:00:00+00:00" + } + ] +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/shopping-categories.mdx b/api-reference/endpoint/naver/shopping-categories.mdx new file mode 100644 index 0000000..dc1720b --- /dev/null +++ b/api-reference/endpoint/naver/shopping-categories.mdx @@ -0,0 +1,80 @@ +--- +title: "Shopping Categories" +api: "GET https://scrapebadger.com/v1/naver/shopping/categories" +description: "The static top-level Naver Shopping category taxonomy — 11 root category ids and names. Free." +--- + +Return the **top-level Naver Shopping taxonomy** — the 11 root categories with their ids and names. Use the ids to scope the ranking, keyword and search endpoints. This is static reference data and is served free. + +**Credits:** 0 + + + This endpoint is free (**0 credits**) — static public taxonomy, no upstream fetch. + + +## Authorization + + + Your ScrapeBadger API key. + + +## Response + +Number of root categories (11). + + Root categories. + + + + + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/shopping/categories" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/shopping/categories", + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/shopping/categories", + headers={"X-API-Key": "YOUR_API_KEY"}, +) +data = res.json() +``` + + + +```json Response +{ + "result_count": 11, + "categories": [ + { + "category_id": "50000000", + "name": "패션의류" + }, + { + "category_id": "50000001", + "name": "패션잡화" + }, + { + "category_id": "50000002", + "name": "화장품/미용" + } + ] +} +``` diff --git a/api-reference/endpoint/naver/shopping-category-tree.mdx b/api-reference/endpoint/naver/shopping-category-tree.mdx new file mode 100644 index 0000000..e680aa0 --- /dev/null +++ b/api-reference/endpoint/naver/shopping-category-tree.mdx @@ -0,0 +1,95 @@ +--- +title: "Shopping Category Tree" +api: "GET https://scrapebadger.com/v1/naver/shopping/category-tree" +description: "One level of the Naver Shopping ranking category tree — DIV1 roots, or the DIV2 children of a parent id." +--- + +Walk the **Naver Shopping ranking category tree** one level at a time. With no `parent_id` it returns the DIV1 root categories; pass a `parent_id` to return that node's DIV2 children. Each node carries its full ancestor id/name chain. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Query Parameters + + + A DIV1 category id to list its DIV2 children. Omit for the roots. + + +## Response + +Echo of the requested parent, or `null` for roots. +The depth returned, e.g. `DIV1` or `DIV2`. + + + Categories at this level. + + + + + + Ancestor category ids, root to leaf. + Ancestor category names, root to leaf. + + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/shopping/category-tree?parent_id=50000000" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/shopping/category-tree?" + + new URLSearchParams({"parent_id": "50000000"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/shopping/category-tree", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"parent_id": "50000000"}, +) +data = res.json() +``` + + + +```json Response +{ + "parent_id": "50000000", + "level": "DIV2", + "result_count": 12, + "categories": [ + { + "type": "DIV2", + "category_id": "50000167", + "category_name": "원피스", + "cat_id_1": "50000000", + "cat_nm_1": "패션의류", + "image_url": "https://shopping-phinf.example.net/cat/50000167.jpg" + } + ] +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/shopping-deals.mdx b/api-reference/endpoint/naver/shopping-deals.mdx new file mode 100644 index 0000000..8676a91 --- /dev/null +++ b/api-reference/endpoint/naver/shopping-deals.mdx @@ -0,0 +1,114 @@ +--- +title: "Shopping Deals" +api: "GET https://scrapebadger.com/v1/naver/shopping/deals" +description: "Curated Naver Shopping deal products, gender-scoped — a fixed 12-item best-deal card list." +--- + +Fetch Naver Shopping's **curated deal products** (the `bestdeal` vertical). The list is gender-scoped and returns a fixed set of 12 deal cards, each with its rank, catalogue id, title, price, discount and labels. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Query Parameters + + + `M` or `F`. A blank gender returns an empty list upstream. + + +## Response + +Echo of the requested gender. +Products returned (12). + + Curated deal products. + + + + Naver Shopping catalogue id. + + + + + + List price in KRW. + + Discounted price in KRW. + + + + + Whether the item is a “찜” (wishlist) favourite. + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/shopping/deals?gender=F" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/shopping/deals?" + + new URLSearchParams({"gender": "F"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/shopping/deals", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"gender": "F"}, +) +data = res.json() +``` + + + +```json Response +{ + "gender": "F", + "result_count": 12, + "products": [ + { + "rank": 1, + "nv_mid": "82613579214", + "product_id": "5123456789", + "channel_product_id": "7001234567", + "title": "여성 여름 린넨 원피스", + "image_url": "https://shopping-phinf.example.net/82613579214.jpg", + "link_url": "https://shopping.naver.com/catalog/82613579214", + "price": 39000, + "price_value": 39000, + "discount_price": 29900, + "discount_rate": 23, + "delivery_fee": 0, + "labels": [ + "무료배송", + "오늘출발" + ], + "is_ad": false, + "is_zzim": false + } + ] +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/shopping-insight.mdx b/api-reference/endpoint/naver/shopping-insight.mdx new file mode 100644 index 0000000..540a97f --- /dev/null +++ b/api-reference/endpoint/naver/shopping-insight.mdx @@ -0,0 +1,114 @@ +--- +title: "Shopping Insight" +api: "GET https://scrapebadger.com/v1/naver/shopping/insight" +description: "Naver Shopping keyword insight — the ranked top search keywords for a category over a date range." +--- + +Fetch Naver Shopping's keyword insight ranking — the top search keywords for a +category over a date range. Use it to see what shoppers in a category are +actually searching for. + +**Credits:** 5 + + + This endpoint returns Naver Shopping's **ranking data only**. General product + search and SmartStore storefront listings are not offered. + + +## Authorization + + + Your ScrapeBadger API key. + + +## Query Parameters + + + Naver Shopping category id to rank keywords within. + + + + Start of the date range, `YYYY-MM-DD`. + + + + End of the date range, `YYYY-MM-DD`. + + + + Aggregation unit, e.g. `date`, `week`, `month`. + + + + Number of keywords to return. + + +## Response + +Echo of the requested category. +The date range the ranking covers. +Keywords returned. + + Ranked keywords. + + + 1-based rank. + The search keyword. + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/shopping/insight?category_id=50000000&start_date=2026-08-01&end_date=2026-08-07&time_unit=date&count=20" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/shopping/insight?" + + new URLSearchParams({ + category_id: "50000000", + start_date: "2026-08-01", + end_date: "2026-08-07", + time_unit: "date", + count: "20", + }), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/shopping/insight", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={ + "category_id": "50000000", + "start_date": "2026-08-01", + "end_date": "2026-08-07", + "time_unit": "date", + "count": 20, + }, +) +data = res.json() +``` + + + +```json Response +{ + "category_id": "50000000", + "date_range": "2026-08-01 ~ 2026-08-07", + "result_count": 20, + "keywords": [ + { "rank": 1, "keyword": "반팔티" }, + { "rank": 2, "keyword": "린넨 셔츠" }, + { "rank": 3, "keyword": "샌들" } + ] +} +``` diff --git a/api-reference/endpoint/naver/shopping-it-items.mdx b/api-reference/endpoint/naver/shopping-it-items.mdx new file mode 100644 index 0000000..460c310 --- /dev/null +++ b/api-reference/endpoint/naver/shopping-it-items.mdx @@ -0,0 +1,107 @@ +--- +title: "Shopping IT Items" +api: "GET https://scrapebadger.com/v1/naver/shopping/it-items" +description: "Curated Naver Shopping “IT item” editorial cards — themed card lists each carrying a product set." +--- + +Fetch Naver Shopping's **“IT item” editorial cards** — themed, curated card lists (e.g. trend and best-of round-ups). Each card carries its metadata and an embedded product set. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Response + +Cards returned. + + Editorial cards. + + + + + + Card metadata. + + + + + + + + + + + + + + + Products featured on the card. + + +The subset of cards flagged as best-of. + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/shopping/it-items" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/shopping/it-items", + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/shopping/it-items", + headers={"X-API-Key": "YOUR_API_KEY"}, +) +data = res.json() +``` + + + +```json Response +{ + "result_count": 8, + "cards": [ + { + "card_id": "it_001", + "card_seq": 1, + "card": { + "gender": "F", + "aggregate_type": "TREND", + "text": "지금 뜨는", + "title": "여름 홈웨어 베스트", + "title_best": "여름 홈웨어", + "exposure_rank": 1, + "exposure_type": "MAIN", + "img_url": "https://shopping-phinf.example.net/card/it_001.jpg", + "active_start_ymd": "20260801", + "sync_date": "2026-08-07T00:00:00+00:00" + }, + "products": [] + } + ], + "best_cards": [] +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/shopping-keyword-periods.mdx b/api-reference/endpoint/naver/shopping-keyword-periods.mdx new file mode 100644 index 0000000..d7d65a0 --- /dev/null +++ b/api-reference/endpoint/naver/shopping-keyword-periods.mdx @@ -0,0 +1,113 @@ +--- +title: "Shopping Keyword Periods" +api: "GET https://scrapebadger.com/v1/naver/shopping/keyword-periods" +description: "The list of available periods for the Naver Shopping keyword ranking, for a category and age bracket." +--- + +List the **available periods** for the Naver Shopping keyword ranking — the weeks or months you can request from [`/shopping/keywords`](/api-reference/endpoint/naver/shopping-keywords) for a given category and age bracket. The complete period list is returned in one response. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Query Parameters + + + `A`, or an 8-digit category id. + + + + Age bracket, e.g. `ALL`, `MEN_20`. + + + + Fixed at `KEYWORD_NEW`. + + + + `WEEKLY` or `MONTHLY`. + + +## Response + + + + + + + + Available periods. + + + Period start date, `YYYYMMDD`. + Period end date. + + + + + + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/shopping/keyword-periods?category_id=A&period_type=WEEKLY" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/shopping/keyword-periods?" + + new URLSearchParams({"category_id": "A", "period_type": "WEEKLY"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/shopping/keyword-periods", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"category_id": "A", "period_type": "WEEKLY"}, +) +data = res.json() +``` + + + +```json Response +{ + "category_id": "A", + "age_type": "ALL", + "sort_type": "KEYWORD_NEW", + "period_type": "WEEKLY", + "result_count": 12, + "periods": [ + { + "ymd": "20260804", + "ended_at": "20260810", + "month": 8, + "week": 1, + "period_type": "WEEKLY", + "has_next": false, + "has_prev": true + } + ] +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/shopping-keywords.mdx b/api-reference/endpoint/naver/shopping-keywords.mdx new file mode 100644 index 0000000..db9574a --- /dev/null +++ b/api-reference/endpoint/naver/shopping-keywords.mdx @@ -0,0 +1,125 @@ +--- +title: "Shopping Keyword Rankings" +api: "GET https://scrapebadger.com/v1/naver/shopping/keywords" +description: "Trending Naver Shopping keyword rankings for a category, with rise/fall status and rank movement." +--- + +Fetch Naver Shopping's **trending keyword ranking** for a category — the keywords shoppers are searching most, each with its rank, a sub-title, tags, a rise/fall status and the rank movement versus the previous period. + +**Credits:** 5 + + + `category_id` is required and must be a real Naver Shopping category id — `ALL` returns an empty ranking. Take an id from [`/shopping/categories`](/api-reference/endpoint/naver/shopping-categories). + + +## Authorization + + + Your ScrapeBadger API key. + + +## Query Parameters + + + Category to rank within. A real category id — `ALL` returns empty. + + + + Age bracket to rank for. + + + + The metric the ranking is sorted by. + + + + `DAILY` or `WEEKLY`. + + +## Response + +Echo of the requested category. + + + + + + Ranked keywords. + + + + + + + `RISE`, `FALL`, `STABLE`, `NEW`, `UP` or `DOWN`. + Rank change versus the previous period. + + + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/shopping/keywords?category_id=50000000&period_type=WEEKLY" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/shopping/keywords?" + + new URLSearchParams({"category_id": "50000000", "period_type": "WEEKLY"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/shopping/keywords", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"category_id": "50000000", "period_type": "WEEKLY"}, +) +data = res.json() +``` + + + +```json Response +{ + "category_id": "50000000", + "age_type": "ALL", + "sort_type": "KEYWORD_POPULAR", + "period_type": "WEEKLY", + "result_count": 100, + "keywords": [ + { + "rank": 1, + "keyword": "여름 원피스", + "sub_title": "", + "tags": [ + "여성의류" + ], + "status": "RISE", + "rank_fluctuation": 3, + "category_id": "50000167", + "category_path": [ + "패션의류", + "여성의류", + "원피스" + ] + } + ] +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/shopping-live-broadcast-counts.mdx b/api-reference/endpoint/naver/shopping-live-broadcast-counts.mdx new file mode 100644 index 0000000..3d44d8b --- /dev/null +++ b/api-reference/endpoint/naver/shopping-live-broadcast-counts.mdx @@ -0,0 +1,82 @@ +--- +title: "Get Live Broadcast Counts" +api: "GET https://scrapebadger.com/v1/naver/shopping/live/broadcasts/{broadcast_id}/counts" +description: "Viewer, like and comment counts for a Naver Shopping Live broadcast." +--- + +Fetch the **engagement counts** for a Shopping Live broadcast — the viewer, like and comment totals. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Path Parameters + + + Shopping Live broadcast id. + + +## Response + + + + Engagement counts. + + + + + + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/shopping/live/broadcasts/1234567/counts" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/shopping/live/broadcasts/1234567/counts", + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/shopping/live/broadcasts/1234567/counts", + headers={"X-API-Key": "YOUR_API_KEY"}, +) +data = res.json() +``` + + + +```json Response +{ + "broadcast_id": "1234567", + "counts": { + "viewerCount": 48213, + "likeCount": 120345, + "commentCount": 2841 + } +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `404` | The requested resource does not exist or has been removed. | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/shopping-live-broadcast-product-categories.mdx b/api-reference/endpoint/naver/shopping-live-broadcast-product-categories.mdx new file mode 100644 index 0000000..9e0974c --- /dev/null +++ b/api-reference/endpoint/naver/shopping-live-broadcast-product-categories.mdx @@ -0,0 +1,94 @@ +--- +title: "List Live Broadcast Product Categories" +api: "GET https://scrapebadger.com/v1/naver/shopping/live/broadcasts/{broadcast_id}/product-categories" +description: "The product categories featured in a Naver Shopping Live broadcast." +--- + +List the **product categories present in a Shopping Live broadcast** — the category chips shoppers can filter the broadcast's products by. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Path Parameters + + + Shopping Live broadcast id. + + +## Query Parameters + + + `MAIN` or `SUB`. + + +## Response + + + + + Product categories. + + + + + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/shopping/live/broadcasts/1234567/product-categories" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/shopping/live/broadcasts/1234567/product-categories", + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/shopping/live/broadcasts/1234567/product-categories", + headers={"X-API-Key": "YOUR_API_KEY"}, +) +data = res.json() +``` + + + +```json Response +{ + "broadcast_id": "1234567", + "result_count": 3, + "categories": [ + { + "id": "c1", + "name": "침구" + }, + { + "id": "c2", + "name": "생활용품" + } + ] +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `404` | The requested resource does not exist or has been removed. | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/shopping-live-broadcast-products.mdx b/api-reference/endpoint/naver/shopping-live-broadcast-products.mdx new file mode 100644 index 0000000..3804c67 --- /dev/null +++ b/api-reference/endpoint/naver/shopping-live-broadcast-products.mdx @@ -0,0 +1,114 @@ +--- +title: "List Live Broadcast Products" +api: "GET https://scrapebadger.com/v1/naver/shopping/live/broadcasts/{broadcast_id}/products" +description: "Paginated product list for a single Naver Shopping Live broadcast." +--- + +List the **products featured in a Shopping Live broadcast**, paginated. Each product carries its live price, discount and link. + +**Credits:** 5 + + + `page` is 0-based. Omit it for the first page — `page=1` returns an empty list. + + +## Authorization + + + Your ScrapeBadger API key. + + +## Path Parameters + + + Shopping Live broadcast id. + + +## Query Parameters + + + 0-based page. Omit for the first page. + + + + Products per page (1–200). Omit for the upstream default. + + +## Response + + + + + + + + Live products. + + + + + + + + + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/shopping/live/broadcasts/1234567/products?size=20" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/shopping/live/broadcasts/1234567/products?" + + new URLSearchParams({"size": "20"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/shopping/live/broadcasts/1234567/products", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"size": "20"}, +) +data = res.json() +``` + + + +```json Response +{ + "broadcast_id": "1234567", + "page": 0, + "total_count": 5, + "total_page": 1, + "result_count": 5, + "products": [ + { + "key": "p1", + "name": "시원한 여름 이불", + "salePrice": 59000, + "discountedSalePrice": 39000, + "productUrl": "https://shopping.naver.com/catalog/82614111000", + "imageUrl": "https://shop-phinf.example.net/p1.jpg" + } + ] +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `404` | The requested resource does not exist or has been removed. | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/shopping-live-broadcast.mdx b/api-reference/endpoint/naver/shopping-live-broadcast.mdx new file mode 100644 index 0000000..824c576 --- /dev/null +++ b/api-reference/endpoint/naver/shopping-live-broadcast.mdx @@ -0,0 +1,98 @@ +--- +title: "Get Live Broadcast" +api: "GET https://scrapebadger.com/v1/naver/shopping/live/broadcasts/{broadcast_id}" +description: "Naver Shopping Live broadcast detail by id, including the embedded featured products." +--- + +Fetch **Shopping Live broadcast detail** by id — the title, status and schedule, plus the featured products embedded in the broadcast. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Path Parameters + + + Shopping Live broadcast id. + + +## Response + + +Featured products on the broadcast. + + + Broadcast detail. + + + + e.g. `ONAIR`, `END`, `STANDBY`. + Scheduled start (KST). + Scheduled start (UTC). + Featured products. + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/shopping/live/broadcasts/1234567" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/shopping/live/broadcasts/1234567", + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/shopping/live/broadcasts/1234567", + headers={"X-API-Key": "YOUR_API_KEY"}, +) +data = res.json() +``` + + + +```json Response +{ + "broadcast_id": "1234567", + "item_count": 5, + "source_url": "https://shoppinglive.naver.com/replays/1234567", + "broadcast": { + "title": "여름 침구 특가 라이브", + "status": "END", + "expectedStartDate": "2026-08-01T20:00:00+09:00", + "expected_start_at": "2026-08-01T20:00:00+09:00", + "expected_start_utc": "2026-08-01T11:00:00Z", + "shoppingProducts": [ + { + "key": "p1", + "name": "시원한 여름 이불", + "salePrice": 59000, + "discountedSalePrice": 39000 + } + ] + } +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `404` | The requested resource does not exist or has been removed. | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/shopping-live-channel-broadcasts.mdx b/api-reference/endpoint/naver/shopping-live-channel-broadcasts.mdx new file mode 100644 index 0000000..16bfa2e --- /dev/null +++ b/api-reference/endpoint/naver/shopping-live-channel-broadcasts.mdx @@ -0,0 +1,92 @@ +--- +title: "List Live Channel Broadcasts" +api: "GET https://scrapebadger.com/v1/naver/shopping/live/channels/{channel_id}/broadcasts" +description: "Broadcast list for a Naver Shopping Live channel, including upcoming standby schedule cards." +--- + +List a **Shopping Live channel's broadcasts** — past, live and upcoming — including the STANDBY schedule cards for broadcasts not yet started. Cursor-paginated. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Path Parameters + + + Shopping Live channel id. + + +## Response + + + +Cursor for the next page, or `null` at the end. + + + Broadcast cards. + + + + + e.g. `ONAIR`, `END`, `STANDBY`. + + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/shopping/live/channels/abcde/broadcasts" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/shopping/live/channels/abcde/broadcasts", + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/shopping/live/channels/abcde/broadcasts", + headers={"X-API-Key": "YOUR_API_KEY"}, +) +data = res.json() +``` + + + +```json Response +{ + "channel_id": "abcde", + "count": 42, + "next": "20", + "result_count": 20, + "broadcasts": [ + { + "id": "1234567", + "title": "여름 침구 특가 라이브", + "status": "END", + "expectedStartDate": "2026-08-01T20:00:00+09:00" + } + ] +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `404` | The requested resource does not exist or has been removed. | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/shopping-live-channel-products.mdx b/api-reference/endpoint/naver/shopping-live-channel-products.mdx new file mode 100644 index 0000000..2e9051b --- /dev/null +++ b/api-reference/endpoint/naver/shopping-live-channel-products.mdx @@ -0,0 +1,94 @@ +--- +title: "List Live Channel Products" +api: "GET https://scrapebadger.com/v1/naver/shopping/live/channels/{channel_id}/products" +description: "Product list for a Naver Shopping Live channel, cursor-paginated." +--- + +List the **products a Shopping Live channel features** across its broadcasts, cursor-paginated. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Path Parameters + + + Shopping Live channel id. + + +## Query Parameters + + + Pagination cursor from a prior page. + + + + Products per page (1–100). Omit for the upstream default (10). + + +## Response + + + +Cursor for the next page, or `null` at the end. + +Channel products. + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/shopping/live/channels/abcde/products?size=20" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/shopping/live/channels/abcde/products?" + + new URLSearchParams({"size": "20"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/shopping/live/channels/abcde/products", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"size": "20"}, +) +data = res.json() +``` + + + +```json Response +{ + "channel_id": "abcde", + "count": 120, + "next": "20", + "result_count": 20, + "products": [ + { + "key": "p1", + "name": "시원한 여름 이불", + "salePrice": 59000 + } + ] +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `404` | The requested resource does not exist or has been removed. | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/shopping-live-channel-shortclips.mdx b/api-reference/endpoint/naver/shopping-live-channel-shortclips.mdx new file mode 100644 index 0000000..4d8cf2e --- /dev/null +++ b/api-reference/endpoint/naver/shopping-live-channel-shortclips.mdx @@ -0,0 +1,108 @@ +--- +title: "List Live Channel Shortclips" +api: "GET https://scrapebadger.com/v1/naver/shopping/live/channels/{channel_id}/shortclips" +description: "Shorts / clips list for a Naver Shopping Live channel, with sort control and cursor pagination." +--- + +List a **Shopping Live channel's shortclips** — its short-form shopping clips — with sort control and cursor pagination. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Path Parameters + + + Shopping Live channel id. + + +## Query Parameters + + + `LATEST`, `VIEW` or `RECOMMEND`. Omit for the upstream default. + + + + Pagination cursor from a prior page. + + + + Clips per page (1–100). Omit for the upstream default (10). + + +## Response + + + +Cursor for the next page, or `null` at the end. + + + Shortclip cards. + + + + + + + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/shopping/live/channels/abcde/shortclips?sort_type=VIEW&size=20" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/shopping/live/channels/abcde/shortclips?" + + new URLSearchParams({"sort_type": "VIEW", "size": "20"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/shopping/live/channels/abcde/shortclips", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"sort_type": "VIEW", "size": "20"}, +) +data = res.json() +``` + + + +```json Response +{ + "channel_id": "abcde", + "count": 60, + "next": "20", + "result_count": 20, + "shortclips": [ + { + "id": "sc100", + "title": "1분 침구 꿀팁", + "thumbnailUrl": "https://shop-phinf.example.net/sc100.jpg", + "viewCount": 88213 + } + ] +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `404` | The requested resource does not exist or has been removed. | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/shopping-live-channel.mdx b/api-reference/endpoint/naver/shopping-live-channel.mdx new file mode 100644 index 0000000..4a281e3 --- /dev/null +++ b/api-reference/endpoint/naver/shopping-live-channel.mdx @@ -0,0 +1,82 @@ +--- +title: "Get Live Channel" +api: "GET https://scrapebadger.com/v1/naver/shopping/live/channels/{channel_id}" +description: "Naver Shopping Live channel / store profile — nickname, on-air status and scheduled broadcasts." +--- + +Fetch a **Shopping Live channel (store) profile** — the channel nickname, current on-air status and any scheduled upcoming broadcast. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Path Parameters + + + Shopping Live channel id. + + +## Response + + + + Channel profile. + + + + Whether the channel is live now. + Next scheduled broadcast start, when any. + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/shopping/live/channels/abcde" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/shopping/live/channels/abcde", + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/shopping/live/channels/abcde", + headers={"X-API-Key": "YOUR_API_KEY"}, +) +data = res.json() +``` + + + +```json Response +{ + "channel_id": "abcde", + "profile": { + "nickname": "리빙하우스", + "onair": false, + "broadcastExpectedStartDate": "2026-08-10T20:00:00+09:00" + } +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `404` | The requested resource does not exist or has been removed. | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/shopping-live-replay-products.mdx b/api-reference/endpoint/naver/shopping-live-replay-products.mdx new file mode 100644 index 0000000..4243ce8 --- /dev/null +++ b/api-reference/endpoint/naver/shopping-live-replay-products.mdx @@ -0,0 +1,108 @@ +--- +title: "List Live Replay Products" +api: "GET https://scrapebadger.com/v1/naver/shopping/live/broadcasts/{broadcast_id}/replay-products" +description: "The replay product timeline of an ended Naver Shopping Live broadcast — products with their on-air offsets." +--- + +Fetch the **replay product timeline** of an ended Shopping Live broadcast — the products as they were featured over the broadcast, each entry carrying its on-air offset so you can align products to the replay video. Cursor-paginated. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Path Parameters + + + Shopping Live broadcast id. + + +## Query Parameters + + + Include products shown before the broadcast started. + + + + Pagination cursor; `0` starts from the beginning. + + +## Response + + +Cursor for the next page, or `null` at the end. +Timeline entries in this page. +Distinct products across the timeline. + + Timeline entries. + + + Entry timestamp (epoch ms). + Offset into the replay, in seconds. + Products featured at this offset. + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/shopping/live/broadcasts/1234567/replay-products?next=0" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/shopping/live/broadcasts/1234567/replay-products?" + + new URLSearchParams({"next": "0"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/shopping/live/broadcasts/1234567/replay-products", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"next": "0"}, +) +data = res.json() +``` + + + +```json Response +{ + "broadcast_id": "1234567", + "next": "20", + "result_count": 1, + "product_count": 5, + "entries": [ + { + "createdAtMilli": 1754044800000, + "offset_seconds": 120, + "products": [ + { + "key": "p1", + "name": "시원한 여름 이불", + "salePrice": 59000 + } + ] + } + ] +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `404` | The requested resource does not exist or has been removed. | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/shopping-live-search-keywords.mdx b/api-reference/endpoint/naver/shopping-live-search-keywords.mdx new file mode 100644 index 0000000..940b9e6 --- /dev/null +++ b/api-reference/endpoint/naver/shopping-live-search-keywords.mdx @@ -0,0 +1,94 @@ +--- +title: "Shopping Live Keyword Rankings" +api: "GET https://scrapebadger.com/v1/naver/shopping/live/search/keywords" +description: "Naver Shopping Live standby search keyword ranking — the keywords trending on the Shopping Live search screen." +--- + +Fetch the **Shopping Live standby keyword ranking** — the trending keywords shown on the Shopping Live search screen, each with its rank movement, plus the recent-keyword list. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Response + + + The keyword ranking block. + + + + Ranked keywords. + + + + Rank change. + + + Absolute update timestamp (ISO 8601). + + + + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/shopping/live/search/keywords" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/shopping/live/search/keywords", + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/shopping/live/search/keywords", + headers={"X-API-Key": "YOUR_API_KEY"}, +) +data = res.json() +``` + + + +```json Response +{ + "keyword_ranking": { + "keywordRankings": [ + { + "keyword": "여름 이불", + "variation": 2 + } + ], + "updatedAt": "2026-08-07T10:00:00+09:00", + "updated_at": "2026-08-07T01:00:00+00:00", + "updated_utc": "2026-08-07T01:00:00Z" + }, + "recent_keywords": [ + "캠핑", + "원피스" + ], + "result_count": 20, + "source_url": "https://shoppinglive.naver.com/search" +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/shopping-live-shortclip-products.mdx b/api-reference/endpoint/naver/shopping-live-shortclip-products.mdx new file mode 100644 index 0000000..b0f5d73 --- /dev/null +++ b/api-reference/endpoint/naver/shopping-live-shortclip-products.mdx @@ -0,0 +1,109 @@ +--- +title: "List Live Shortclip Products" +api: "GET https://scrapebadger.com/v1/naver/shopping/live/shortclips/{shortclip_id}/products" +description: "Paginated product list for a Naver Shopping Live shortclip, with attachment-type and sort control." +--- + +List the **products featured in a Shopping Live shortclip**, paginated, with attachment-type and sort control. + +**Credits:** 5 + + + `page` is 0-based. + + +## Authorization + + + Your ScrapeBadger API key. + + +## Path Parameters + + + Shopping Live shortclip id. + + +## Query Parameters + + + `MAIN` or `SUB`. + + + + 0-based page. + + + + Products per page (1–100). + + + + `RECOMMEND` or `POPULAR`. + + +## Response + + + + + + +Clip products. + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/shopping/live/shortclips/sc100/products?sort=POPULAR&size=20" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/shopping/live/shortclips/sc100/products?" + + new URLSearchParams({"sort": "POPULAR", "size": "20"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/shopping/live/shortclips/sc100/products", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"sort": "POPULAR", "size": "20"}, +) +data = res.json() +``` + + + +```json Response +{ + "shortclip_id": "sc100", + "page": 0, + "total_count": 2, + "total_page": 1, + "result_count": 2, + "products": [ + { + "key": "p1", + "name": "시원한 여름 이불", + "salePrice": 59000, + "discountedSalePrice": 39000 + } + ] +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `404` | The requested resource does not exist or has been removed. | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/shopping-live-shortclip.mdx b/api-reference/endpoint/naver/shopping-live-shortclip.mdx new file mode 100644 index 0000000..0b875a7 --- /dev/null +++ b/api-reference/endpoint/naver/shopping-live-shortclip.mdx @@ -0,0 +1,100 @@ +--- +title: "Get Live Shortclip" +api: "GET https://scrapebadger.com/v1/naver/shopping/live/shortclips/{shortclip_id}" +description: "Naver Shopping Live shortclip detail with embedded products and categories." +--- + +Fetch **Shopping Live shortclip detail** — the clip's channel, video id, product categories and the products embedded in the clip. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Path Parameters + + + Shopping Live shortclip id. + + +## Response + + +Products embedded in the clip. + + Shortclip detail. + + + The owning channel. + Video id. + Product categories in the clip. + Embedded products. + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/shopping/live/shortclips/sc100" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/shopping/live/shortclips/sc100", + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/shopping/live/shortclips/sc100", + headers={"X-API-Key": "YOUR_API_KEY"}, +) +data = res.json() +``` + + + +```json Response +{ + "shortclip_id": "sc100", + "item_count": 2, + "shortclip": { + "channel": { + "id": "abcde", + "nickname": "리빙하우스" + }, + "vid": "V_ab12cd34", + "categories": [ + { + "id": "c1", + "name": "침구" + } + ], + "products": [ + { + "key": "p1", + "name": "시원한 여름 이불", + "salePrice": 59000 + } + ] + } +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `404` | The requested resource does not exist or has been removed. | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/shopping-price-compare.mdx b/api-reference/endpoint/naver/shopping-price-compare.mdx new file mode 100644 index 0000000..277286a --- /dev/null +++ b/api-reference/endpoint/naver/shopping-price-compare.mdx @@ -0,0 +1,117 @@ +--- +title: "Shopping Price Compare" +api: "GET https://scrapebadger.com/v1/naver/shopping/price-compare" +description: "Seller offers per catalog product from Naver's 가격비교 (price-comparison) page — the lowest-price mall rows for each catalog match." +--- + +Fetch **seller offers per catalog product** from Naver's 가격비교 (price-comparison) page. For each catalog entry matching the query you get the catalog identity, the total offer count and the first few lowest-price seller rows. + +**Credits:** 5 + + + Clears Naver's shopping captcha in a live browser session. One page of offers is served per call, and each catalog entry exposes its first 5 lowest-price rows. + + +## Authorization + + + Your ScrapeBadger API key. + + +## Query Parameters + + + Search keywords (1–200 chars). + + +## Response + + + + Catalog entries matching the query. + + + + + Total seller offers for this catalog entry. + Lowest price across sellers, in KRW. + + The first 5 lowest-price seller rows. + + + + That mall's price in KRW. + + + + Whether the mall supports Naver Pay. + + + Raw upstream `lowPriceByMallNo` string for the same 5 malls. + + +A note describing the offer-row coverage. + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/shopping/price-compare?query=다이슨+에어랩" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/shopping/price-compare?" + + new URLSearchParams({"query": "다이슨 에어랩"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/shopping/price-compare", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"query": "다이슨 에어랩"}, +) +data = res.json() +``` + + + +```json Response +{ + "query": "다이슨 에어랩", + "entries": [ + { + "catalog_id": "82614000777", + "catalog_name": "다이슨 에어랩 컴플리트 롱", + "offer_count": 214, + "best_price": 529000, + "offers": [ + { + "mall_name": "다이슨 공식스토어", + "price": 529000, + "nv_mid": "82614000777", + "product_id": "7008888001", + "mall_seq": "41021", + "naver_pay": true + } + ], + "price_by_mall": "82614000777/41021/7008888001/529000/1/..." + } + ], + "offers_note": "First 5 low-price rows per catalog entry." +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/shopping-search-catalog.mdx b/api-reference/endpoint/naver/shopping-search-catalog.mdx new file mode 100644 index 0000000..e44e4be --- /dev/null +++ b/api-reference/endpoint/naver/shopping-search-catalog.mdx @@ -0,0 +1,165 @@ +--- +title: "Shopping Catalog Search" +api: "GET https://scrapebadger.com/v1/naver/shopping/search-catalog" +description: "Full-catalog Naver Shopping search — deep, paginated product results (pages 1–5) with sort control." +--- + +Run a **full-catalog Naver Shopping search** against `search.shopping.naver.com`. Unlike the finder preview, this is the deep catalog feed with sort control and pagination through pages 1–5. Each product carries its catalogue identity, price, review stats, delivery fee and category path. + +**Credits:** 5 + + + This endpoint clears Naver's shopping captcha in a live browser session, so it is the heaviest Naver call and a page can take up to ~90 seconds. Pages are capped at 5; sorted lists are capped upstream at ~120 items. Sponsored rows stay in `products` flagged `is_ad`. + + +## Authorization + + + Your ScrapeBadger API key. + + +## Query Parameters + + + Search keywords (1–200 chars). + + + + `RECOMMEND`, `LOW_PRICE`, `HIGH_PRICE`, `PURCHASE`, `REVIEW` or `RECENT`. + + + + 1-based page, `1`–`5`. Page 1 is the SSR page; pages 2+ use the catalog XHR. + + +## Response + + + + + +Total catalog matches, when Naver reports it. +Cursor for the next page, when present. +Whether another page is available (within the 5-page cap). + +Always `false` — this is the full catalog feed. + + Catalog products. + + + + Naver Shopping catalogue id. + + + + + + + + + + + + + + + + + + + + Per-page summary, including the overlap count with earlier pages. + + + + + Items on this page already seen on an earlier page. + + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/shopping/search-catalog?query=로봇청소기&sort=LOW_PRICE&page=1" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/shopping/search-catalog?" + + new URLSearchParams({"query": "로봇청소기", "sort": "LOW_PRICE", "page": "1"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/shopping/search-catalog", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"query": "로봇청소기", "sort": "LOW_PRICE", "page": "1"}, +) +data = res.json() +``` + + + +```json Response +{ + "query": "로봇청소기", + "sort": "LOW_PRICE", + "page": 1, + "page_size": 40, + "total": 1200, + "cursor": 41, + "has_more": true, + "result_count": 40, + "preview_only": false, + "products": [ + { + "rank": 1, + "nv_mid": "82613999001", + "title": "로보락 S8 로봇청소기", + "price": 899000, + "discounted_price": 799000, + "discount_rate": 11, + "image_url": "https://shopping-phinf.example.net/82613999001.jpg", + "product_url": "https://shopping.naver.com/catalog/82613999001", + "channel_product_id": "7009999001", + "mall_name": "로보락 공식스토어", + "mall_id": "roborock", + "mall_seq": "55123", + "review_score": 4.7, + "review_count": 8842, + "delivery_fee": 0, + "category_path": [ + "디지털/가전", + "생활가전", + "청소기" + ], + "leaf_category_id": "50002100", + "is_ad": false + } + ], + "pages": [ + { + "page": 1, + "result_count": 40, + "repeated_count": 0 + } + ], + "source_url": "https://search.shopping.naver.com/ns/search?query=로봇청소기" +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/shopping-search-filtered.mdx b/api-reference/endpoint/naver/shopping-search-filtered.mdx new file mode 100644 index 0000000..eeef132 --- /dev/null +++ b/api-reference/endpoint/naver/shopping-search-filtered.mdx @@ -0,0 +1,108 @@ +--- +title: "Shopping Filtered Search" +api: "GET https://scrapebadger.com/v1/naver/shopping/search-filtered" +description: "Filtered Naver Shopping product search — narrow a finder query by a brand id and/or attribute id." +--- + +Run a **filtered Naver Shopping product search** — the same finder feed as [`/shopping/search-products`](/api-reference/endpoint/naver/shopping-search-products), narrowed by a brand id and/or attribute id taken from [`/shopping/search-filters`](/api-reference/endpoint/naver/shopping-search-filters). Returns the finite finder set (up to 10 pages of 8 slots). + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Query Parameters + + + Search keywords. + + + + A brand value id from `/shopping/search-filters` (`BRAND` facet). + + + + An attribute value id from `/shopping/search-filters` (`ATTRIBUTE` facet). + + +## Response + + +The brand ids applied. +The attribute ids applied. +Always `true`. + +Finder pages folded in (≤ 10). + +Total matches reported by Naver, when available. +How the filter was applied: `click` or `rewrite`. +Filtered products — same shape as a [`/shopping/search-products`](/api-reference/endpoint/naver/shopping-search-products) product. + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/shopping/search-filtered?query=무선+이어폰&brand_id=12345" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/shopping/search-filtered?" + + new URLSearchParams({"query": "무선 이어폰", "brand_id": "12345"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/shopping/search-filtered", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"query": "무선 이어폰", "brand_id": "12345"}, +) +data = res.json() +``` + + + +```json Response +{ + "query": "무선 이어폰", + "brand_ids": [ + "12345" + ], + "attribute_ids": [], + "preview_only": true, + "result_count": 40, + "page_count": 5, + "page_size": 8, + "total_count": 40, + "filters_applied_by": "click", + "products": [ + { + "rank": 1, + "nv_mid": "82613579214", + "product_name": "삼성전자 갤럭시 버즈3 프로", + "product_url": "https://shopping.naver.com/catalog/82613579214", + "sale_price": 279000, + "discounted_sale_price": 229000, + "mall_name": "삼성전자 공식스토어", + "is_ad": false + } + ] +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/shopping-search-filters.mdx b/api-reference/endpoint/naver/shopping-search-filters.mdx new file mode 100644 index 0000000..b809489 --- /dev/null +++ b/api-reference/endpoint/naver/shopping-search-filters.mdx @@ -0,0 +1,111 @@ +--- +title: "Shopping Search Filters" +api: "GET https://scrapebadger.com/v1/naver/shopping/search-filters" +description: "Query-dependent filter facets (brand, attribute) for a Naver Shopping product search." +--- + +Return the **filter facets** Naver offers for a product-search query — the brand and attribute filters, each with its selectable values and ids. Feed a value id into [`/shopping/search-filtered`](/api-reference/endpoint/naver/shopping-search-filtered) to narrow a search. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Query Parameters + + + Search keywords. + + +## Response + + +Filter facets returned. + + Filter facets. + + + + + + `BRAND`, `ATTRIBUTE`, … + + + Selectable values. + + + + + + + + +The dominant category for this query, when Naver resolves one. + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/shopping/search-filters?query=무선+이어폰" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/shopping/search-filters?" + + new URLSearchParams({"query": "무선 이어폰"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/shopping/search-filters", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"query": "무선 이어폰"}, +) +data = res.json() +``` + + + +```json Response +{ + "query": "무선 이어폰", + "result_count": 2, + "filters": [ + { + "id": "brand", + "name": "브랜드", + "filter_name": "brand", + "type": "BRAND", + "source_type": "FINDER", + "values": [ + { + "id": "12345", + "name": "삼성전자" + }, + { + "id": "23456", + "name": "애플" + } + ] + } + ], + "category_id": "50000151" +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/shopping-search-products.mdx b/api-reference/endpoint/naver/shopping-search-products.mdx new file mode 100644 index 0000000..22306b6 --- /dev/null +++ b/api-reference/endpoint/naver/shopping-search-products.mdx @@ -0,0 +1,145 @@ +--- +title: "Shopping Product Search" +api: "GET https://scrapebadger.com/v1/naver/shopping/search-products" +description: "Product search across Naver Shopping via the mobile integrated-search finder preview — every preview page in one response." +--- + +Search products across Naver Shopping using the **mobile integrated-search shopping finder**. One call returns the complete finder preview (all preview pages at once), each product carrying its catalogue id, mall, price, discount, review score and category path. + +**Credits:** 5 + + + This is the **finder preview** — one response holds every preview page. Deep full-catalog pagination is served by [`/shopping/search-catalog`](/api-reference/endpoint/naver/shopping-search-catalog). + + +## Authorization + + + Your ScrapeBadger API key. + + +## Query Parameters + + + Search keywords. + + + + Finder tab: `m_view` or `m_shop`. + + +## Response + + + +Always `true` — see the note above. + +Preview pages folded into this response. + + Finder product cards. + + + + Naver Shopping catalogue id. + + + + + + + + List price in KRW. + + + + + + + + Wishlist (“찜”) count. + + `AD` or `SAS`. + Large category id. + Medium category id. + Small category id. + + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/shopping/search-products?query=무선+이어폰&tab=m_view" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/shopping/search-products?" + + new URLSearchParams({"query": "무선 이어폰", "tab": "m_view"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/shopping/search-products", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"query": "무선 이어폰", "tab": "m_view"}, +) +data = res.json() +``` + + + +```json Response +{ + "query": "무선 이어폰", + "tab": "m_view", + "preview_only": true, + "result_count": 80, + "total_pages": 10, + "products": [ + { + "rank": 1, + "nv_mid": "82613579214", + "product_id": "5123456789", + "channel_product_id": "7001234567", + "mall_id": "samsung", + "mall_name": "삼성전자 공식스토어", + "mall_url": "https://brand.naver.com/samsung", + "product_name": "삼성전자 갤럭시 버즈3 프로", + "product_url": "https://shopping.naver.com/catalog/82613579214", + "sale_price": 279000, + "discounted_sale_price": 229000, + "discounted_ratio": 18, + "price_currency": "KRW", + "images": [ + "https://shopping-phinf.example.net/82613579214.jpg" + ], + "average_review_score": 4.8, + "total_review_count": 12043, + "purchase_count": 5321, + "keep_count": 8820, + "is_ad": false, + "source_type": "SAS", + "l_cat_id": "50000003", + "m_cat_id": "50000151", + "s_cat_id": "50000806", + "leaf_category_id": "50002345" + } + ] +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/shopping-vertical.mdx b/api-reference/endpoint/naver/shopping-vertical.mdx new file mode 100644 index 0000000..1015d34 --- /dev/null +++ b/api-reference/endpoint/naver/shopping-vertical.mdx @@ -0,0 +1,102 @@ +--- +title: "Shopping Vertical" +api: "GET https://scrapebadger.com/v1/naver/shopping/verticals/{vertical}" +description: "Curated Naver Shopping products for a named snxbest vertical such as fashiontown, shoppinglive or logistics." +--- + +Fetch the **curated product list for a named Naver Shopping vertical** — the editorial feeds behind the `fashiontown`, `shoppinglive` and `logistics` sections. Returns a fixed set of 12 curated products. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Path Parameters + + + One of `fashiontown`, `shoppinglive` or `logistics`. + + +## Response + +Echo of the requested vertical. +Products returned (12). + + Curated products — same shape as a [`/shopping/deals`](/api-reference/endpoint/naver/shopping-deals) product. + + + + + + + + + + + + + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/shopping/verticals/fashiontown" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/shopping/verticals/fashiontown", + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/shopping/verticals/fashiontown", + headers={"X-API-Key": "YOUR_API_KEY"}, +) +data = res.json() +``` + + + +```json Response +{ + "vertical": "fashiontown", + "result_count": 12, + "products": [ + { + "rank": 1, + "nv_mid": "82613579300", + "title": "남성 오버핏 셔츠", + "image_url": "https://shopping-phinf.example.net/82613579300.jpg", + "link_url": "https://shopping.naver.com/catalog/82613579300", + "price": 49000, + "discount_price": 34300, + "discount_rate": 30, + "labels": [ + "무료배송" + ], + "is_ad": false + } + ] +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `404` | The requested resource does not exist or has been removed. | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/store-bestsellers.mdx b/api-reference/endpoint/naver/store-bestsellers.mdx new file mode 100644 index 0000000..c4f4811 --- /dev/null +++ b/api-reference/endpoint/naver/store-bestsellers.mdx @@ -0,0 +1,95 @@ +--- +title: "Get Store Bestsellers" +api: "GET https://scrapebadger.com/v1/naver/stores/{store_url}/bestsellers" +description: "Bestselling products within a single Naver SmartStore / Brand Store, by period." +--- + +List the **bestselling products within one storefront**, scoped by period. Each product is the same storefront listing card returned by [`/stores/{store_url}/products`](/api-reference/endpoint/naver/store-products). + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Path Parameters + + + Storefront slug. + + +## Query Parameters + + + Storefront host: `smartstore` or `brand`. + + + + `REALTIME`, `DAILY`, `WEEKLY` or `MONTHLY`. + + +## Response + + + + + +Bestselling storefront listing cards — same shape as [`/stores/{store_url}/products`](/api-reference/endpoint/naver/store-products). + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/stores/plusink/bestsellers?host=smartstore&period=DAILY" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/stores/plusink/bestsellers?" + + new URLSearchParams({"host": "smartstore", "period": "DAILY"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/stores/plusink/bestsellers", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"host": "smartstore", "period": "DAILY"}, +) +data = res.json() +``` + + + +```json Response +{ + "store_url": "plusink", + "host": "smartstore", + "period": "DAILY", + "result_count": 20, + "products": [ + { + "id": "7001234567", + "name": "정품 HP 잉크 카트리지 세트", + "sale_price": 48000, + "representative_image_url": "https://shop-phinf.example.net/7001234567.jpg" + } + ] +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `404` | The requested resource does not exist or has been removed. | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/store-categories.mdx b/api-reference/endpoint/naver/store-categories.mdx new file mode 100644 index 0000000..56ee81b --- /dev/null +++ b/api-reference/endpoint/naver/store-categories.mdx @@ -0,0 +1,106 @@ +--- +title: "Get Store Categories" +api: "GET https://scrapebadger.com/v1/naver/stores/{store_url}/categories" +description: "The display-category tree of a Naver SmartStore / Brand Store storefront." +--- + +Fetch the **display-category tree** of a storefront — the seller-defined categories shoppers browse the store by, returned recursively with level and sort order. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Path Parameters + + + Storefront slug. + + +## Query Parameters + + + Storefront host: `smartstore` or `brand`. + + +## Response + + + + + + Display categories. + + + + + + + + Whether this is the catch-all “전체상품” node. + + + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/stores/plusink/categories?host=smartstore" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/stores/plusink/categories?" + + new URLSearchParams({"host": "smartstore"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/stores/plusink/categories", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"host": "smartstore"}, +) +data = res.json() +``` + + + +```json Response +{ + "store_url": "plusink", + "host": "smartstore", + "result_count": 4, + "categories": [ + { + "category_id": "1000000001", + "parent_category_id": null, + "name": "전체상품", + "level": 1, + "sort_order": 0, + "all_product_category": true, + "exposure": true, + "type": "MANUAL" + } + ] +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `404` | The requested resource does not exist or has been removed. | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/store-products.mdx b/api-reference/endpoint/naver/store-products.mdx new file mode 100644 index 0000000..eba22c1 --- /dev/null +++ b/api-reference/endpoint/naver/store-products.mdx @@ -0,0 +1,190 @@ +--- +title: "Get Store Products" +api: "GET https://scrapebadger.com/v1/naver/stores/{store_url}/products" +description: "Paginated product listing for a Naver SmartStore / Brand Store, optionally scoped to a display category." +--- + +List the **products in a storefront**, optionally scoped to one of its display categories. Each product is the storefront listing card — name, price, discount, stock status, review summary and representative image. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Path Parameters + + + Storefront slug. + + +## Query Parameters + + + Storefront host: `smartstore` or `brand`. + + + + Scope to a display category id from [`/stores/{store_url}/categories`](/api-reference/endpoint/naver/store-categories). + + + + 1-based page. + + + + Products per page. + + + + Sort order, e.g. `POPULARITY`. + + + + Storefront channel uid. Optional — resolved from the slug when omitted. + + +## Response + + + +Total products in scope. + + + + + Storefront listing cards. + + + Channel product number. + + + + + + e.g. `SALE`, `SOLDOUT`. + + + + + + + + + + + + + + + + + + + Discount view. + + + + + + + + + + + + + + + + Whether same-day (“오늘출발”) delivery is offered. + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/stores/plusink/products?host=smartstore&page=1&size=20" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/stores/plusink/products?" + + new URLSearchParams({"host": "smartstore", "page": "1", "size": "20"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/stores/plusink/products", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"host": "smartstore", "page": "1", "size": "20"}, +) +data = res.json() +``` + + + +```json Response +{ + "store_url": "plusink", + "host": "smartstore", + "total_count": 312, + "page": 1, + "page_size": 20, + "sort": "POPULARITY", + "products": [ + { + "id": "7001234567", + "product_no": "5123456789", + "name": "정품 HP 잉크 카트리지 세트", + "disp_name": "정품 HP 잉크 세트", + "sale_price": 48000, + "disp_sale_price": 48000, + "product_status_type": "SALE", + "stock_quantity": 820, + "category": { + "category_id": "50006543", + "category_name": "잉크/토너", + "whole_category_id": "50000003>50006543", + "whole_category_name": "디지털/가전>잉크/토너" + }, + "channel": { + "channel_no": "10012345", + "account_no": "90012345", + "channel_uid": "2sV!abc123", + "channel_name": "플러스잉크" + }, + "benefits_view": { + "discounted_sale_price": 42000, + "discounted_ratio": 13 + }, + "review_amount": { + "total_review_count": 2841, + "average_review_score": 4.9, + "product_satisfaction_percent": 98 + }, + "representative_image_url": "https://shop-phinf.example.net/7001234567.jpg", + "is_free_delivery": true, + "today_delivery": true + } + ] +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `404` | The requested resource does not exist or has been removed. | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/store-profile.mdx b/api-reference/endpoint/naver/store-profile.mdx new file mode 100644 index 0000000..a5374de --- /dev/null +++ b/api-reference/endpoint/naver/store-profile.mdx @@ -0,0 +1,108 @@ +--- +title: "Get Store Profile" +api: "GET https://scrapebadger.com/v1/naver/stores/{store_url}" +description: "Naver SmartStore / Brand Store seller profile — channel name, description, logo, follower and sale counts, seller grade." +--- + +Fetch a **Naver SmartStore or Brand Store seller profile** by its storefront slug. Returns the channel name and description, logo, SNS links, follower and sale counts, seller grade, CS response ratio and business type. + +**Credits:** 5 + + + Personal identity fields (names, phone numbers, addresses, emails) are masked and omitted from the response. + + +## Authorization + + + Your ScrapeBadger API key. + + +## Path Parameters + + + Storefront slug, e.g. `plusink` or `drbrian`. + + +## Query Parameters + + + Storefront host: `smartstore` or `brand`. + + +## Response + + + + + + + + +Social links the store publishes. + + + + + + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/stores/plusink?host=smartstore" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/stores/plusink?" + + new URLSearchParams({"host": "smartstore"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/stores/plusink", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"host": "smartstore"}, +) +data = res.json() +``` + + + +```json Response +{ + "store_url": "plusink", + "host": "smartstore", + "channel_uid": "2sV!abc123", + "channel_no": "10012345", + "channel_name": "플러스잉크", + "description": "정품 프린터 잉크 전문 스토어", + "logo_url": "https://shop-phinf.example.net/logo/plusink.jpg", + "sns": {}, + "follower_count": 48213, + "seller_grade": "빅파워", + "sale_count": 152043, + "cs_response_ratio": "98%", + "business_type": "법인", + "represent_type": "SmartStore", + "channel_service_type": "STOREFARM" +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `404` | The requested resource does not exist or has been removed. | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/api-reference/endpoint/naver/video.mdx b/api-reference/endpoint/naver/video.mdx new file mode 100644 index 0000000..83f0c22 --- /dev/null +++ b/api-reference/endpoint/naver/video.mdx @@ -0,0 +1,110 @@ +--- +title: "Video Search" +api: "GET https://scrapebadger.com/v1/naver/video" +description: "Search the Naver video vertical — 48 videos per page with duration, channel, view count and thumbnail." +--- + +Search the **Naver video** vertical, which aggregates videos across YouTube, Naver TV and other sources. Each result carries the title and URL, duration, channel name and URL, view count, source and an absolute publish timestamp. Returns 48 videos per page. + +**Credits:** 5 + +## Authorization + + + Your ScrapeBadger API key. + + +## Query Parameters + + + Search keywords. + + + + 1-based result page. Each page returns up to 48 videos. + + +## Response + + + + + + Videos. + + + + + Video URL. + Runtime as displayed, e.g. `12:04`. + + + + Platform, e.g. `YouTube`, `네이버TV`. + + + + Absolute publish timestamp (ISO 8601). + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/naver/video?query=제주도+브이로그&page=1" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/naver/video?" + + new URLSearchParams({"query": "제주도 브이로그", "page": "1"}), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/naver/video", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"query": "제주도 브이로그", "page": "1"}, +) +data = res.json() +``` + + + +```json Response +{ + "query": "제주도 브이로그", + "page": 1, + "result_count": 48, + "results": [ + { + "position": 1, + "title": "제주도 3박4일 브이로그", + "url": "https://tv.naver.com/v/12345", + "duration": "12:04", + "channel": "여행하는쩡", + "channel_url": "https://tv.naver.com/jjeong", + "source": "네이버TV", + "view_count": 48213, + "thumbnail_url": "https://video-phinf.example.net/12345.jpg", + "published": "2026.06.01.", + "published_at": "2026-06-01T00:00:00+09:00" + } + ] +} +``` + +## Errors + +| Status | Meaning | +| ------ | ------- | +| `422` | Naver served a challenge instead of content — **not billed**. Retry; it succeeds. | +| `502` | Unexpected upstream failure — **not billed**. | diff --git a/docs.json b/docs.json index 1c88c72..b86ebb8 100644 --- a/docs.json +++ b/docs.json @@ -349,6 +349,107 @@ } ] }, + { + "tab": "Naver", + "groups": [ + { + "group": "Overview", + "pages": [ + "naver/overview" + ] + }, + { + "group": "Search", + "pages": [ + "api-reference/endpoint/naver/search", + "api-reference/endpoint/naver/search-web", + "api-reference/endpoint/naver/news", + "api-reference/endpoint/naver/blog", + "api-reference/endpoint/naver/cafe", + "api-reference/endpoint/naver/kin", + "api-reference/endpoint/naver/autocomplete", + "api-reference/endpoint/naver/image", + "api-reference/endpoint/naver/video", + "api-reference/endpoint/naver/clip" + ] + }, + { + "group": "Place", + "pages": [ + "api-reference/endpoint/naver/local", + "api-reference/endpoint/naver/place", + "api-reference/endpoint/naver/place-reviews", + "api-reference/endpoint/naver/place-photos" + ] + }, + { + "group": "Shopping Intelligence", + "pages": [ + "api-reference/endpoint/naver/shopping-bestsellers", + "api-reference/endpoint/naver/shopping-keywords", + "api-reference/endpoint/naver/shopping-insight", + "api-reference/endpoint/naver/shopping-categories", + "api-reference/endpoint/naver/shopping-category-tree", + "api-reference/endpoint/naver/shopping-deals", + "api-reference/endpoint/naver/shopping-vertical", + "api-reference/endpoint/naver/shopping-it-items", + "api-reference/endpoint/naver/shopping-brand-rank", + "api-reference/endpoint/naver/shopping-brand-categories", + "api-reference/endpoint/naver/shopping-keyword-periods" + ] + }, + { + "group": "Shopping Search & Catalog", + "pages": [ + "api-reference/endpoint/naver/shopping-search-products", + "api-reference/endpoint/naver/shopping-search-filters", + "api-reference/endpoint/naver/shopping-search-filtered", + "api-reference/endpoint/naver/shopping-search-catalog", + "api-reference/endpoint/naver/shopping-price-compare" + ] + }, + { + "group": "SmartStore & Stores", + "pages": [ + "api-reference/endpoint/naver/store-profile", + "api-reference/endpoint/naver/store-categories", + "api-reference/endpoint/naver/store-products", + "api-reference/endpoint/naver/store-bestsellers" + ] + }, + { + "group": "Products & Reviews", + "pages": [ + "api-reference/endpoint/naver/product-detail", + "api-reference/endpoint/naver/product-group", + "api-reference/endpoint/naver/product-review-summary", + "api-reference/endpoint/naver/product-reviews-list", + "api-reference/endpoint/naver/product-qna-list", + "api-reference/endpoint/naver/group-review-summary", + "api-reference/endpoint/naver/review-detail", + "api-reference/endpoint/naver/review-ssr-queries", + "api-reference/endpoint/naver/review-video-inkey" + ] + }, + { + "group": "Shopping Live", + "pages": [ + "api-reference/endpoint/naver/shopping-live-search-keywords", + "api-reference/endpoint/naver/shopping-live-broadcast", + "api-reference/endpoint/naver/shopping-live-broadcast-products", + "api-reference/endpoint/naver/shopping-live-broadcast-counts", + "api-reference/endpoint/naver/shopping-live-replay-products", + "api-reference/endpoint/naver/shopping-live-broadcast-product-categories", + "api-reference/endpoint/naver/shopping-live-channel", + "api-reference/endpoint/naver/shopping-live-channel-products", + "api-reference/endpoint/naver/shopping-live-channel-broadcasts", + "api-reference/endpoint/naver/shopping-live-channel-shortclips", + "api-reference/endpoint/naver/shopping-live-shortclip", + "api-reference/endpoint/naver/shopping-live-shortclip-products" + ] + } + ] + }, { "tab": "Reddit", "groups": [ diff --git a/naver/overview.mdx b/naver/overview.mdx new file mode 100644 index 0000000..726d47f --- /dev/null +++ b/naver/overview.mdx @@ -0,0 +1,154 @@ +--- +title: "Naver API Overview" +description: "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. + + + 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`](/api-reference/endpoint/naver/search) SERP plus the dedicated + [`/search/web`](/api-reference/endpoint/naver/search-web), + [`/news`](/api-reference/endpoint/naver/news), + [`/blog`](/api-reference/endpoint/naver/blog), + [`/cafe`](/api-reference/endpoint/naver/cafe), + [`/kin`](/api-reference/endpoint/naver/kin) (Knowledge iN), + [`/image`](/api-reference/endpoint/naver/image), + [`/video`](/api-reference/endpoint/naver/video) and + [`/clip`](/api-reference/endpoint/naver/clip) feeds, each with resolved + destination URLs and absolute publish times. +- **Autocomplete** — Naver's search-box suggestions for 1 credit. +- **Naver Place** — local business search, full place detail, reviews and the + place [photo viewer](/api-reference/endpoint/naver/place-photos). +- **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 | +| -------- | ---- | ------- | +| Autocomplete | `GET /v1/naver/autocomplete` | 1 | +| Shopping categories | `GET /v1/naver/shopping/categories` | 0 (free reference) | +| Place detail | `GET /v1/naver/place/{place_id}` | 8 (browser-rendered) | +| Everything else | `GET /v1/naver/*` | 5 | + + + The catalog and price-comparison searches + ([`/shopping/search-catalog`](/api-reference/endpoint/naver/shopping-search-catalog) + and + [`/shopping/price-compare`](/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 +curl "https://scrapebadger.com/v1/naver/search?query=제주도+맛집" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +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 +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`](/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**. | + + + Start from [`/autocomplete`](/api-reference/endpoint/naver/autocomplete) + (1 credit) to expand a seed term into real Naver queries, then run + [`/search`](/api-reference/endpoint/naver/search) on each suggestion. +