# Naver Shopping Product Search (`skcho/naver-shopping-product-insight`) Actor

Collect Naver Shopping product results by keyword with prices, sellers, brands, categories, ranks, URLs, and diagnostics in a clean Apify dataset.

- **URL**: https://apify.com/skcho/naver-shopping-product-insight.md
- **Developed by:** [seungkyu cho](https://apify.com/skcho) (community)
- **Categories:** Automation, Developer tools, E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## Naver Shopping Product Insight

Apify Actor for collecting enriched Naver Shopping product rows with a simple commercial input surface.

The default user flow is intentionally small: enter product keywords, optionally choose the number of products per keyword, and run. The Actor owner configures Naver OpenAPI credentials as Apify environment secrets, so end users do not need to understand sources, proxies, browser fallback, page sizes, or diagnostics.

### What It Collects

- Product name, ID, page URL, and image URL
- Seller name, discounted price, keyword, rank, page, and crawl timestamp
- OpenAPI metadata when available: brand, maker, category path, and product type
- Enhanced diagnostics: source type, source URL, crawl status, and missing-field signals
- Compatible legacy fields when `outputMode=compatible` is used through advanced JSON input

### Simple Input

Most users only need this:

```json
{
  "keywords": ["running shoes"]
}
````

The default collects 100 products per keyword. To request a different count:

```json
{
  "keywords": ["running shoes", "wireless earbuds"],
  "itemsPerKeyword": 250
}
```

Optional sort:

```json
{
  "keywords": ["running shoes"],
  "itemsPerKeyword": 100,
  "sort": "review"
}
```

The Apify form intentionally exposes only:

- `keywords`
- `itemsPerKeyword`
- `sort`

All commercial defaults are supplied automatically:

- `sourceMode=openapi`
- `outputMode=enhanced`
- `openApiDisplaySize=100`
- `maxCrawlPages=ceil(itemsPerKeyword / 100)`
- `maxItems=keywords.length * itemsPerKeyword`
- `failIfBelowMaxItems=true`
- `maxConcurrency=1`
- `requestDelayMs=100`
- Apify run options: 1024 MB memory, 600 second timeout
- browser fallback disabled
- raw product payload disabled

This keeps the first run easy while preserving strict failure behavior when the requested count cannot be collected.

### 1000 Result Run

Use `examples/openapi-1000-input.json`:

```json
{
  "keywords": ["running shoes"],
  "itemsPerKeyword": 1000
}
```

Commercial release note, 2026-07-06: Apify Cloud source probes on build `1.0.15` still showed Naver Shopping web/API sources blocked through both default Apify Proxy and Residential KR. Do not market the pure-web path as a reliable 1000-result product until a source probe shows Shopping sources with `blocked=false` and `uniqueProductCount>0` on pages 1-3.

Verified commercial path: `sourceMode=openapi` with Actor-owned Naver OpenAPI credentials.

OpenAPI commercial proof: build `1.0.18`, run `h2GIa87P2xr5yfFcV`, dataset `2dbh2E5EPZwGc2HdX`, wrote 1000/1000 rows with `RUN-SUMMARY.status=passed`.

OpenAPI output quality proof: the same dataset has 100% coverage for product name, ID, page URL, image URL, seller name, discounted price, keyword, rank, page, source URL, source type, category path, product type, crawl status, and crawl timestamp. Brand coverage is 99.7% and maker coverage is 85.6%. OpenAPI does not provide web-only fields such as seller ID, shipping fee, reviews, stock, and product flags, so `outputMode=enhanced` omits unsupported null-only fields.

### Advanced Operator Inputs

The runtime still accepts advanced JSON inputs for troubleshooting and controlled experiments. These fields are intentionally hidden from the default Apify form:

- `runMode`
- `sourceMode`
- `maxCrawlPages`
- `probeMaxPages`
- `openApiDisplaySize`
- `maxItems`
- `failIfBelowMaxItems`
- `maxConcurrency`
- `requestDelayMs`
- `useBrowserFallback`
- `browserFallbackMaxPages`
- `browserSessionReuse`
- `browserWarmupEnabled`
- `browserMaxBlockedPagesBeforeReset`
- `integratedFallbackMaxPages`
- `stopAfterEmptyPages`
- `stopAfterBlockedPages`
- `saveDebugArtifacts`
- `includeRaw`
- `externalHttpProxyUrl`
- `externalBrowserProxyUrl`
- `proxyConfiguration`
- `outputMode`

Keep these options in examples and API inputs for operator use, not as the default end-user experience.

### Web And Proxy Diagnostics

Pure web scraping remains diagnostic only. If Naver Shopping web pages return `NAVER_SHOPPING_ACCESS_RESTRICTED`, the Actor fails fast after repeated blocked pages and writes useful counters instead of spending indefinitely.

Before investing in web scraping or proxy experiments, run:

- `examples/source-probe-input.json`
- `examples/residential-source-probe-input.json`
- `examples/external-proxy-source-probe-input.json`

Probe mode writes one diagnostic row per source/page candidate:

- `shopping-search-page`
- `shopping-api-search-all`
- `shopping-api-products`
- `mshopping-api-search-all`
- `integrated-nexearch`
- `integrated-where-shopping`

Each row reports `statusCode`, `blocked`, `productCount`, `uniqueProductCount`, `sampleProductIds`, `sampleProductNames`, and `durationMs`. A web source is only worth using for scale-up if it returns unblocked pages with meaningfully changing unique products across pages.

For external proxy scale-up, use the staged examples only after a passing source probe:

- `examples/web-100-external-proxy-input.json`
- `examples/web-500-external-proxy-input.json`
- `examples/web-1000-external-proxy-input.json`

Do not combine `useApifyProxy`, `groups`, or `countryCode` with `proxyUrls` in the same `proxyConfiguration`.

### Output Compatibility

Enhanced mode is the default and omits unsupported null-only fields. Compatible mode can still be requested by advanced JSON input when a legacy integration needs the broader field set.

Compatible records include fields such as:

```json
{
  "isAd": "Not Ad",
  "productName": "Sample product",
  "productId": "11152911412",
  "productPageUrl": "https://smartstore.naver.com/main/products/11152911412",
  "productImageUrl": "https://shopping-phinf.pstatic.net/main_8869742/88697421733.1.jpg",
  "sellerName": "Sample seller",
  "sellerPageUrl": null,
  "sellerId": "ncp_1nrc1k_01",
  "discountedPrice": 169900,
  "searchKeyword": "running shoes",
  "crawledAt": "2026-07-04 17:00:00"
}
```

See `docs/OUTPUT_SCHEMA.md` for the full dataset contract.

### Reliability Strategy

The commercial path uses Naver OpenAPI first to reduce Apify compute cost and avoid the known Cloud web-blocking path. Records with missing fields are not silently discarded; enhanced mode exposes `crawlStatus` and `missingFields` so schema drift is easier to debug.

Run logs include `openApiPages`, `httpPages`, `integratedSearchPages`, `browserPages`, `blockedPages`, `emptyPages`, `foundProducts`, `writtenProducts`, `dedupedProducts`, and `durationMs`.

Every scrape run writes `RUN-SUMMARY` to the default key-value store. Inspect it before raw debug artifacts. It includes:

- `status`: `passed`, `attention`, or `failed`
- `shouldFail`: true when the strict item target was missed
- `issues`: concrete failure or quality signals
- `recommendations`: next operational step for Cloud validation
- `counters`: final run counters

### Local Development

```bash
npm install
npm run check
npm test
npm run build
```

Run locally with Apify storage:

```bash
npm run build
apify run
```

### Release Checklist

1. Run `npm run build:release`.
2. Run `git diff --check`.
3. Build on Apify Cloud.
4. Verify commercial OpenAPI collection with `examples/openapi-1000-input.json`.
5. Inspect the default dataset and `RUN-SUMMARY` before calling a run successful.
6. Only run source probes or pure-web scale-up when specifically validating web/proxy strategy.

Release builds validate every JSON file under `examples/`. To run that check directly:

```bash
npm run validate:examples
```

# Actor input Schema

## `keywords` (type: `array`):

Add one or more Naver Shopping product keywords. The Actor uses the commercial OpenAPI path and enriched output defaults automatically.

## `itemsPerKeyword` (type: `integer`):

How many products to collect for each keyword. The Actor automatically chooses the required OpenAPI pages and fails clearly if the requested count cannot be collected.

## `sort` (type: `string`):

Product ordering for the Naver Shopping search.

## Actor input object example

```json
{
  "keywords": [
    "running shoes"
  ],
  "itemsPerKeyword": 100,
  "sort": "rel"
}
```

# Actor output Schema

## `productResults` (type: `string`):

Clean Naver Shopping product rows collected from the default dataset. Each row includes product, seller, category, rank, source, and crawl status fields when available.

## `runSummary` (type: `string`):

Run-level status, counters, issues, recommendations, and strict target information stored in the default key-value store.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "keywords": [
        "running shoes"
    ],
    "itemsPerKeyword": 100,
    "sort": "rel"
};

// Run the Actor and wait for it to finish
const run = await client.actor("skcho/naver-shopping-product-insight").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "keywords": ["running shoes"],
    "itemsPerKeyword": 100,
    "sort": "rel",
}

# Run the Actor and wait for it to finish
run = client.actor("skcho/naver-shopping-product-insight").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "keywords": [
    "running shoes"
  ],
  "itemsPerKeyword": 100,
  "sort": "rel"
}' |
apify call skcho/naver-shopping-product-insight --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=skcho/naver-shopping-product-insight",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Naver Shopping Product Search",
        "description": "Collect Naver Shopping product results by keyword with prices, sellers, brands, categories, ranks, URLs, and diagnostics in a clean Apify dataset.",
        "version": "1.0",
        "x-build-id": "6VKExsB1p7pBsFZ6M"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/skcho~naver-shopping-product-insight/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-skcho-naver-shopping-product-insight",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/skcho~naver-shopping-product-insight/runs": {
            "post": {
                "operationId": "runs-sync-skcho-naver-shopping-product-insight",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/skcho~naver-shopping-product-insight/run-sync": {
            "post": {
                "operationId": "run-sync-skcho-naver-shopping-product-insight",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "keywords"
                ],
                "properties": {
                    "keywords": {
                        "title": "Search Keywords",
                        "type": "array",
                        "description": "Add one or more Naver Shopping product keywords. The Actor uses the commercial OpenAPI path and enriched output defaults automatically.",
                        "default": [
                            "running shoes"
                        ],
                        "items": {
                            "type": "string"
                        }
                    },
                    "itemsPerKeyword": {
                        "title": "Products Per Keyword",
                        "minimum": 1,
                        "maximum": 1000,
                        "type": "integer",
                        "description": "How many products to collect for each keyword. The Actor automatically chooses the required OpenAPI pages and fails clearly if the requested count cannot be collected.",
                        "default": 100
                    },
                    "sort": {
                        "title": "Sort",
                        "enum": [
                            "rel",
                            "date",
                            "price_asc",
                            "price_dsc",
                            "review",
                            "sale"
                        ],
                        "type": "string",
                        "description": "Product ordering for the Naver Shopping search.",
                        "default": "rel"
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```