Naver

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

Base URL: /v1/naver/...

Quickstart

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

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

Search the Korean web

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

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

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

Two corpora differ, both because Naver made them differ:

• local caps display at 5 and defaults it to 1, so omitting display returns a single place. It ignores start entirely, which is why it is the one corpus with no pagination. A display above 5 is silently clamped by Naver rather than rejected.
• image additionally takes filter (all, large, medium, small) to restrict results to a size band.

Reach for kin when you want the questions Korean users ask about a topic in their own words, which is a different and often better input to content planning than what marketers wrote about it. Many cafes are members-only, so a cafearticle result may link to a teaser rather than the full post. The title and snippet are still yours.

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

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

kin and webkr rows also carry post and computed, beside the raw title, link and description, as blog, cafe and news rows do: post.ext.title and post.content.text without Naver's <b> highlight tags, post.url, and computed.language. KnowledgeiN rows name their question and answer in post.ext.question_id and post.ext.answer_no.

Naver returns one KnowledgeiN row per answer, so one question can fill several rows of a page. Send group=question to keep one row per question, with answers_on_page and answer_nos saying how many of its answers the page held. Paging and the price are unchanged.

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

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

For news outside Korea use /v1/google_news/search. For Google's version of a Korean place, use /v1/google/business/info.

Clean up Korean input

errata returns an empty string when the query was already correct. This matters more in Korean than in English: Korean mistypes usually come from hitting the wrong jamo key, which produces a syllable that looks nothing like the intended one, so edit-distance correction misses them entirely. Run user-supplied queries through it before searching.

adult returns the string "1" or "0", not a boolean, a detail worth encoding once rather than debugging twice. Use it to moderate user-supplied search input, or to filter a keyword list before publishing it.

One call across the Korean internet

corpora takes a CSV subset when you do not want all five, display sets items per corpus (1-100, default 20), and cursor is the preferred way to page. Prefer it over start.

Read trend data

All three return a time series under data.results[].data[] as {period, ratio} pairs, and all three share the same four optional dimensions: time_unit (date, week, month, default month), device (pc or mo), gender (f or m), and ages. Omit a dimension and you get the total. group_name on search-trend labels the series in the response and defaults to the first keyword.

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

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

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

Four gotchas worth knowing

Only some endpoints compare, and the rest combine

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

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

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

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

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

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

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

The two Data Lab APIs start at different dates

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

ages uses different codes on different endpoints

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

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

Shopping Insight needs a category id

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

Deeper subcategory ids are visible in the URL when you browse a category on Naver Shopping. Pass up to 3 comma-separated ids to compare them, or one id plus breakdown to split it by device, gender, or age.

Retired corpora

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

If you were using them:

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

brief rejects corpora=shop for the same reason.

All endpoints

14 endpoints available.

Platform notes

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

Next steps