Naver Images Scraper

Collect rich image-search results from Naver for one query or a fair multi-query batch. The Actor uses Naver's public structured image response, validates that every continuation belongs to the requested query and offset, and maps only documented output fields. If that response format changes, it can fall back to the public image payload embedded in Naver's search page.

Version 3 is designed for speed and data quality. It uses plain HTTP instead of launching a browser, normally retrieves 100 source candidates per request, and stops when the requested limit is satisfied. A representative 30-record local run required one request and completed in roughly six seconds of crawler time during validation.

Input modes

Use query for one search or queries for up to ten unique searches. If both are supplied, they are combined and deduplicated. Multi-query output is selected in round-robin order, so one popular query does not consume the entire global maxItems limit.

{
  "queries": ["벚꽃", "서울 야경"],
  "maxItems": 20,
  "maxPages": 2,
  "maxConcurrency": 2,
  "proxyConfiguration": { "useApifyProxy": false }
}

Set maxItems to 1 to retrieve the first current result. maxPages controls how many 100-item response batches may be inspected per query. Naver can include non-image helper cards, so the number of usable images in a batch can be slightly below 100.

Filters and sorting

All filters operate on fields that Naver returned for the inspected candidates:

• minimum and maximum original width or height;
• minimum megapixels;
• file type: JPG, PNG, GIF, WebP, BMP, TIFF, SVG, or AVIF;
• confirmed static or confirmed animated images;
• Naver source sections such as blog or cafe;
• source domains, including subdomain matching;
• visible publication-date range.

Sort by Naver relevance, original width, original height, megapixels, or visible publication date. Filters and non-relevance sorting inspect every allowed batch before selecting records. Increase maxPages when a restrictive filter needs a larger candidate pool.

Naver Images currently targets the Korean ko-KR market. The legacy market value remains accepted only when it is ko-KR; unsupported locales fail clearly instead of being silently ignored. Arbitrary startUrls are no longer accepted because the Actor now performs and validates the public search workflow from user-friendly query inputs.

Dataset fields

Every record contains a stable query-aware ID, global and per-query positions, Naver source position, query context, title, original image URL, real original width and height, aspect ratio, megapixels, source page URL and domain, provider, retrieval method, Korean locale metadata, public search URL, and ISO scrape timestamp.

When Naver provides them, records also include:

• multiple public thumbnail sizes and thumbnail dimensions;
• image extension and MIME type derived from the original URL;
• Naver's explicit GIF flag;
• dominant color;
• publisher/source name and section;
• creator label and public avatar;
• visible publication date;
• numeric Creative Commons code;
• public tags and related-query labels.

Missing optional values are omitted. The Actor never inserts null, blank strings, empty arrays, zero dimensions, guessed file sizes, Google favicon URLs, fabricated ad flags, or placeholder records. Internal image IDs, request signatures, report objects, cookies, and other opaque transport data are not stored.

Pagination, retries, and no results

The Actor validates HTTP status, content type, JSONP syntax, payload types, query attribution, and the next 100-item offset before using a response. Temporary network failures, rate limits, and server errors use bounded retries. Authentication, malformed inputs, explicit challenges, and permanent workflow errors fail clearly. Records are buffered until all requested work succeeds, so a terminal error cannot leave a partial dataset.

A real no-results response completes successfully with an empty dataset. Selector or payload drift is not mistaken for no results: the Actor attempts its DOM fallback and fails safely if neither structured source is recognizable.

Proxies

Direct access is the default and was verified locally. Standard Apify Proxy and custom proxy URLs are supported when normal regional routing requires them. GOOGLE_SERP is intentionally rejected because it supports Google Search and Shopping, not Naver. Proxy credentials, cookies, authorization headers, signed URLs, and sensitive response bodies are never logged or written to the dataset. The Actor does not solve or bypass CAPTCHAs or other access controls.

Local development

npm ci
npm test
apify validate-schema
apify run --purge --input-file INPUT.json
npm run audit:dataset

The audit verifies required fields, types, duplicates, null and empty values, URLs, signed URL parameters, dates, dimensions, source-domain consistency, position order, challenge text, opaque fields, and fabricated favicons. Results can be exported from Apify as JSON, JSONL, CSV, Excel, XML, and other supported dataset formats.

Use the data in accordance with Naver's terms, publisher rights, robots guidance, and applicable law. Original images remain the property of their respective owners.