# Shopee Scraper (`khadinakbar/shopee-scraper`) Actor

Scrape Shopee product search results and product detail pages across Singapore, Malaysia, Philippines, Thailand, Vietnam, Indonesia, Brazil, Mexico, and Taiwan. Returns flat MCP-ready product records with price, sales, ratings, stock, seller, and product URLs.

- **URL**: https://apify.com/khadinakbar/shopee-scraper.md
- **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community)
- **Categories:** E-commerce, MCP servers, AI
- **Stats:** 180 total users, 23 monthly users, 90.7% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 product scrapeds

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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

## Shopee Scraper

Shopee Scraper is an Apify Actor for product search results and product detail pages across Singapore, Malaysia, Philippines, Thailand, Vietnam, Indonesia, Brazil, Mexico, and Taiwan. It accepts keyword queries, Shopee URLs, or direct item and shop ID pairs, and returns one flat record per product with fields such as price, ratings, sold counts, stock, seller data, image URL, category breadcrumbs, and source metadata.

Each dataset record represents one Shopee product. That makes it useful when you need a single, MCP-ready row per item for pricing analysis, assortment research, seller review, or downstream AI workflows that prefer structured product records over nested pages.

### Best fit and connected workflows

This Actor fits workflows that start from a Shopee marketplace view and end with normalized product records. Common routes include:

- Keyword research into product monitoring, using `searchQueries` and `maxSearchPages`.
- Known product URL processing into detail records, using `startUrls`.
- Batch product lookup from known `item_id` and `shop_id` pairs, using `shopItemIds`.
- Marketplace comparison across supported Shopee country domains by switching `country`.
- LLM or agent pipelines that need compact, flat output through Apify MCP.

If your workflow begins with Shopee search intent, category browsing, or direct product references, this Actor gives you a single product-level dataset with consistent field names.

### Practical scenario

A marketplace analyst starts with a list of Shopee Singapore keywords for wireless accessories. They set `searchQueries` to those terms, keep `includeDetails` on, and limit the run with `maxProducts`.

The returned records include `title`, `price`, `rating`, `sold`, `stock`, `shopName`, and `productUrl`. From that output, the analyst can compare item prices and seller signals, then open the strongest candidates in Shopee using the canonical URLs for manual review or a follow-up dashboard.

### Input fields

| Field | Type | Purpose |
| --- | --- | --- |
| `providerMode` | string | Chooses the extraction backend: `auto`, `owned`, or `scrapeless` |
| `country` | string | Selects the Shopee marketplace domain and currency context |
| `searchQueries` | array of string | Builds Shopee search URLs from keywords |
| `startUrls` | array of request sources | Uses already known Shopee product, search, category, or shop search URLs |
| `shopItemIds` | array of objects | Resolves direct `{ item_id, shop_id }` pairs to product details |
| `maxProducts` | integer | Caps returned and charged product records |
| `maxSearchPages` | integer | Limits pagination for generated keyword, category, or shop listing pages |
| `includeDetails` | boolean | Includes detail-page fields such as description, stock, variants, and richer seller data |
| `sortBy` | string | Orders keyword search results by `relevance`, `latest`, or `top_sales` |
| `includeRawData` | boolean | Adds trimmed raw Shopee payload data for debugging and parser work |
| `proxyConfiguration` | object | Uses Apify Proxy settings, with residential defaults |

#### Focused JSON input example

```json
{
  "providerMode": "scrapeless",
  "country": "SG",
  "searchQueries": [
    "wireless earbuds",
    "mechanical keyboard"
  ],
  "maxProducts": 100,
  "maxSearchPages": 3,
  "includeDetails": true,
  "sortBy": "relevance",
  "includeRawData": false
}
```

### Output fields

| Field | Type | Purpose |
| --- | --- | --- |
| `productId` | string or null | Shopee item identifier when available |
| `shopId` | string or null | Shopee shop identifier when available |
| `productUrl` | string or null | Canonical Shopee product URL |
| `title` | string or null | Product title shown by Shopee |
| `price` | number or null | Current product price |
| `priceMin` | number or null | Minimum variant price when a range is present |
| `priceMax` | number or null | Maximum variant price when a range is present |
| `priceBeforeDiscount` | number or null | Original price before discount when available |
| `currency` | string | Marketplace currency code |
| `discount` | string or null | Discount label returned by Shopee |
| `rating` | number or null | Average product rating |
| `ratingCount` | integer or null | Count of ratings or reviews |
| `sold` | integer or null | Recent or displayed sold count |
| `historicalSold` | integer or null | Historical sold count when exposed |
| `stock` | integer or null | Available stock count when present |
| `shopName` | string or null | Seller or shop display name |
| `shopLocation` | string or null | Seller location shown by Shopee |
| `isOfficialShop` | boolean or null | public shop marker |
| `isShopeeMall` | boolean or null | Shopee Mall marker |
| `imageUrl` | string or null | Main product image URL |
| `description` | string or null | Product description when detail extraction is enabled |
| `categories` | array of string | Category breadcrumbs when available |
| `sourceType` | string | Discovery path such as `search`, `url`, `api`, or `fallback` |
| `sourceUrl` | string | Input or generated Shopee URL that produced the record |
| `scrapedAt` | string | ISO 8601 timestamp for the record |

#### Illustrative output record

```json
{
  "productId": "131564786",
  "shopId": "22739277",
  "productUrl": "https://shopee.sg/product/22739277/131564786",
  "title": "Wireless Bluetooth Earbuds",
  "price": 19.9,
  "priceMin": 15.9,
  "priceMax": 24.9,
  "priceBeforeDiscount": 29.9,
  "currency": "SGD",
  "discount": "20%",
  "rating": 4.8,
  "ratingCount": 1240,
  "sold": 5000,
  "historicalSold": 15000,
  "stock": 98,
  "shopName": "Shopee Mall Store",
  "shopLocation": "Singapore",
  "isOfficialShop": true,
  "isShopeeMall": false,
  "imageUrl": "https://down-sg.img.susercontent.com/file/example",
  "description": "Bluetooth 5.3 earbuds with charging case.",
  "categories": [
    "Mobile & Gadgets",
    "Audio"
  ],
  "sourceType": "search",
  "sourceUrl": "https://shopee.sg/search?keyword=wireless%20earbuds",
  "scrapedAt": "2026-06-12T08:00:00.000Z"
}
```

### How it works

This Actor uses a Playwright-based crawler and supports three Shopee extraction backends through `providerMode`:

- `auto` uses `SCRAPELESS_API_KEY` when configured, then falls back to owned browser scraping.
- `owned` uses browser scraping.
- `scrapeless` uses the Scrapeless provider path and is the recommended production route in the supplied contract.

It can start from generated search URLs, direct Shopee URLs, or direct `item_id` and `shop_id` pairs. The dataset is intentionally flat so each record is easy to consume in Apify datasets, SQL-style pipelines, and Apify MCP tool workflows.

### Pricing

Shopee Scraper uses Pay per event plus Apify platform usage.

- Actor start: charged per run start event.
- Product scraped: charged for each product record successfully returned to the dataset.

For example, a run that returns one hundred product records is charged for one hundred product events, plus the start event, plus Apify platform usage. To see the live pricing tab for the current run cost details, open the Actor's Pricing tab in Apify.

### Use with AI agents (MCP)

This Actor is available as an Apify Actor usable through Apify MCP. The tool is designed to fetch Shopee product records with stable field names that are easy for agents to parse and pass downstream.

**Actor identity:** `khadinakbar/shopee-scraper`

Tool description: run Shopee keyword, URL, or batch item lookup jobs and read flat product records from the dataset output. The dataset contains product-level provenance such as `sourceType`, `sourceUrl`, and `scrapedAt`, which helps an agent explain where each record came from.

> Search Shopee Singapore for wireless earbuds, return up to 20 products, and keep the output focused on price, sold count, rating, seller, and product URL.

Output interpretation:

- `productUrl` points to the canonical Shopee product page.
- `sourceUrl` shows the input or generated Shopee URL behind the record.
- `sourceType` tells you whether the record came from search, URL, API, or fallback discovery.
- `scrapedAt` records when the item was produced.

Provenance and scope:

- The Actor covers the Shopee country domains listed in the contract: SG, MY, PH, TH, VN, ID, BR, MX, and TW.
- The dataset schema is product-focused and MCP-ready, with one record per product.
- `includeRawData` can add trimmed raw payloads for debugging schema changes.

Pagination and cost guidance:

- `maxSearchPages` applies to generated keyword, category, or shop listing pages.
- `maxProducts` caps the number of product records returned and charged.
- For agent workflows, start with a smaller cap, inspect the first records, and expand only when the source coverage looks right.

### Apify API example

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

const client = new ApifyClient({
  token: process.env.APIFY_TOKEN,
});

const input = {
  providerMode: 'scrapeless',
  country: 'SG',
  searchQueries: ['wireless earbuds'],
  maxProducts: 10,
  maxSearchPages: 1,
  includeDetails: true,
};

const run = await client.actor('khadinakbar/shopee-scraper').call(input);

const { items } = await client.dataset(run.defaultDatasetId).listItems({ clean: true });

console.log(items);
```

### Best results and outcome guidance

Use `country` that matches the Shopee marketplace you want to inspect, since it controls the marketplace domain and currency context. When you already have product references, `shopItemIds` gives direct batch lookup. When you are starting from discovery, `searchQueries` and `startUrls` are the most direct routes.

A practical setup is:

- `providerMode: "scrapeless"` for production runs when `SCRAPELESS_API_KEY` is configured.
- `includeDetails: true` when you want seller and stock fields from detail pages.
- `includeRawData: false` for compact, stable output.
- `maxProducts` sized to the smallest useful set for your workflow.

### Continue the workflow

- Then use [🛍️ Shopify Scraper — Products, Collections, Reviews & Emails](https://apify.com/khadinakbar/shopify-all-in-one-scraper) to extend Shopee Scraper with a neighboring commerce research source when the brief calls for Shopify data.
- Then use [Shein Product Scraper — Prices, Variants, Reviews API](https://apify.com/khadinakbar/shein-product-scraper) to extend Shopee Scraper with a neighboring commerce research source when the brief calls for Shein data.

### Design note

I found that `categories`, `sourceType`, `sourceUrl`, and `scrapedAt` are required output fields in the dataset contract, which is a clear sign that the Actor is meant to produce provenance-aware product records rather than only price fields.

### FAQ

#### Can I use this Actor for Shopee search pages and product pages?

Yes. It accepts keyword searches, direct Shopee URLs, and direct batch item lookup through `shopItemIds`.

#### Does this Actor work across multiple Shopee country domains?

Yes. The contract includes SG, MY, PH, TH, VN, ID, BR, MX, and TW.

#### When should I use `shopItemIds` instead of `searchQueries`?

Use `shopItemIds` when you already know the `item_id` and `shop_id` values and want direct product detail lookup. Use `searchQueries` when you want Shopee to generate the product set from keywords.

#### What is the role of `includeDetails`?

It adds detail-page fields such as `description`, `stock`, variants, and richer seller data when those fields are available.

#### How does `maxSearchPages` interact with `maxProducts`?

`maxSearchPages` limits how many generated pages are visited, while `maxProducts` caps the returned and charged product records.

### Responsible use

Use this Actor for publicly accessible Shopee product information and for workflows that respect applicable laws, Shopee terms, privacy rules, and marketplace policies. Keep your runs focused on product research, catalog monitoring, and agent consumption, and apply the results in ways that fit your organization or project's compliance requirements.

# Actor input Schema

## `providerMode` (type: `string`):

Use this when choosing the Shopee extraction backend. auto uses SCRAPELESS\_API\_KEY when configured, then owned browser scraping; scrapeless requires that actor secret and is the recommended production path. Defaults to auto for safer setup. This is not a Shopee login mode.

## `country` (type: `string`):

Use this when selecting the Shopee marketplace domain to scrape. Accepted values include SG, MY, PH, TH, VN, ID, BR, MX, and TW. Defaults to SG and controls currency, locale, and generated search URLs. This is not a shipping destination filter inside Shopee.

## `searchQueries` (type: `array`):

Use this when you want Shopee search result products from keywords such as wireless earbuds or korean sunscreen. Enter one query per line; the actor builds Shopee search URLs for the selected country. Defaults to an empty list and works together with Start URLs. This is not for seller IDs or review scraping.

## `startUrls` (type: `array`):

Use this when you already have Shopee product, search, category, or shop search URLs. Accepted format is a Shopee URL such as https://shopee.sg/search?keyword=keyboard or https://shopee.sg/product/22739277/131564786. Defaults to an empty list and can be combined with Search queries. This is not for non-Shopee marketplace URLs.

## `shopItemIds` (type: `array`):

Use this for direct batch product lookup when you already have Shopee item and shop IDs. Accepted format is a list of objects like {"item\_id": 27041370670, "shop\_id": 88201679}; each pair is resolved to full product detail (price, sales, stock, rating, seller). Defaults to an empty list and pairs with the selected Shopee country. This is not a keyword search or a shop URL.

## `maxProducts` (type: `integer`):

Use this to cap the number of product records returned and charged. Accepted range is 1 to 5000 products; default is 50, or the number of Shop item IDs supplied so a batch is never truncated. The actor stops charging once this cap is reached. This is not a page count.

## `maxSearchPages` (type: `integer`):

Use this when scraping keyword, category, or shop listing pages that need pagination. Accepted range is 1 to 20 pages, with 3 as the default. Higher values may take longer because Shopee rate limits aggressively. This does not increase results beyond Maximum products.

## `includeDetails` (type: `boolean`):

Use this when you want detail-page fields such as description, stock, variants, and richer seller data. Defaults to true and visits product detail URLs when search data is incomplete. Turn it off for faster listing-only monitoring. This is not review extraction.

## `sortBy` (type: `string`):

Use this when Shopee search results should be ordered by relevance, latest, or top sales. Accepted values are relevance, latest, and top\_sales; default is relevance. This applies only to generated keyword search URLs. This is not a filter for price or rating.

## `includeRawData` (type: `boolean`):

Use this for debugging Shopee schema changes or building custom downstream parsers. Defaults to false to keep MCP output compact and stable. When true, each record may include a trimmed rawData object from Shopee responses. This is not needed for normal product exports.

## `proxyConfiguration` (type: `object`):

Use this only when you need custom Apify Proxy groups or a country-specific proxy setup. Defaults to Apify residential proxy settings because Shopee blocks many datacenter sessions. Leave unchanged for normal runs. This is not a Shopee account or cookie setting.

## Actor input object example

```json
{
  "providerMode": "auto",
  "country": "SG",
  "searchQueries": [
    "wireless earbuds"
  ],
  "startUrls": [],
  "shopItemIds": [],
  "maxProducts": 1,
  "maxSearchPages": 1,
  "includeDetails": true,
  "sortBy": "relevance",
  "includeRawData": false,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

## `summary` (type: `string`):

No description

# 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 = {
    "searchQueries": [
        "wireless earbuds"
    ],
    "startUrls": [],
    "maxProducts": 1,
    "maxSearchPages": 1,
    "includeDetails": false
};

// Run the Actor and wait for it to finish
const run = await client.actor("khadinakbar/shopee-scraper").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 = {
    "searchQueries": ["wireless earbuds"],
    "startUrls": [],
    "maxProducts": 1,
    "maxSearchPages": 1,
    "includeDetails": False,
}

# Run the Actor and wait for it to finish
run = client.actor("khadinakbar/shopee-scraper").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "searchQueries": [
    "wireless earbuds"
  ],
  "startUrls": [],
  "maxProducts": 1,
  "maxSearchPages": 1,
  "includeDetails": false
}' |
apify call khadinakbar/shopee-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,khadinakbar/shopee-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/h1S7pt2RJ2CLxjgWd/builds/FabTW2V96pq7o5Ksc/openapi.json