# Shopee Southeast Asia Product & Pricing Intelligence (`thomas_shelby_0010/shopee-sea-pricing-spy`) Actor

Scrape product prices, sales volume, discounts, seller ratings, and competitor intelligence across Southeast Asian Shopee markets (VN, PH, TH, MY, ID, SG).

- **URL**: https://apify.com/thomas_shelby_0010/shopee-sea-pricing-spy.md
- **Developed by:** [Thomas Shelby](https://apify.com/thomas_shelby_0010) (community)
- **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/actors/running/actors-in-store.md#pay-per-usage

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Shopee Southeast Asia Product, Pricing & Competitor Intelligence

[![Apify Actor](https://img.shields.io/badge/Apify-Actor-orange?logo=apify)](https://apify.com)
[![Python 3.11+](https://img.shields.io/badge/Python-3.11+-blue.svg?logo=python)](https://python.org)
[![Pay Per Event](https://img.shields.io/badge/PPE-$1.20%20%2F%201k%20records-brightgreen)](#pricing--pay-per-event-ppe)
[![HTTP Only](https://img.shields.io/badge/Engine-Pure%20HTTP-success)](#key-features--advantages)

Unlock real-time e-commerce intelligence across Southeast Asia's #1 shopping marketplace. Monitor product pricing, historical sales volumes, discount strategies, inventory stocks, and merchant badges across **6 major Southeast Asian markets**: **Vietnam, Philippines, Thailand, Malaysia, Indonesia, and Singapore**.

Built on a lightweight, high-speed pure HTTP client engine (no heavy headless browser overhead), this Actor executes in milliseconds, uses under 256MB RAM, and automatically normalizes regional currencies, micro-unit pricing, and merchant data into ready-to-analyze JSON datasets.

***

### 🌏 Supported Southeast Asian Marketplaces

Effortlessly switch between all 6 core Shopee SEA marketplaces simply by specifying `countryCode`:

| Country | Code | Marketplace Domain | Local Currency | Popular E-Commerce Niches |
|---|---|---|---|---|
| 🇻🇳 **Vietnam** | `VN` | `shopee.vn` | **VND** (₫) | Fashion, Skincare, Tech Accessories, Homeware |
| 🇵🇭 **Philippines** | `PH` | `shopee.ph` | **PHP** (₱) | Beauty, Consumer Electronics, Footwear, Groceries |
| 🇹🇭 **Thailand** | `TH` | `shopee.co.th` | **THB** (฿) | Cosmetics, Streetwear, Auto Accessories, Gadgets |
| 🇲🇾 **Malaysia** | `MY` | `shopee.com.my` | **MYR** (RM) | Halal Beauty, Computer Hardware, Baby Essentials |
| 🇮🇩 **Indonesia** | `ID` | `shopee.co.id` | **IDR** (Rp) | Muslim Fashion, Local Distro Brands, Mobile Phones |
| 🇸🇬 **Singapore** | `SG` | `shopee.sg` | **SGD** (S$) | Premium Consumer Tech, Luxury Goods, Supplements |

***

### ⚡ Key Features & Advantages

- 🚀 **Pure HTTP Architecture (No Headless Browser)**: Operates without Chromium or Selenium overhead. Runs 10x faster and requires 75% less memory (min 256MB RAM), drastically reducing compute run costs.
- 💰 **Automated Micro-Unit Price Normalization**: Shopee API natively stores prices scaled by 100,000 (micro-units). This scraper automatically computes true nominal pricing, original list prices, and discount percentages.
- 🛡️ **Anti-Bot & WAF Challenge Resilience**: Features realistic desktop Chrome 124 browser headers, automatic cookie forwarding, and graceful bot challenge fallback to ensure your data pipeline never halts.
- 🏷️ **Merchant & Store Badge Detection**: Distinguishes **Shopee Mall** (Official Flagship Stores) and **Shopee Preferred / Preferred+** merchants from standard marketplace sellers.
- 📈 **Granular Sort Options**: Sort by **Historical Sales** (`sales`), **Relevancy** (`relevancy`), **New Arrivals** (`ctime`), or **Price Ascending/Descending** (`price_asc`, `price_desc`).
- 🔄 **Dual Execution Modes**: Seamlessly deploy on the Apify cloud platform or run locally as a high-performance command-line utility (CLI) in CI/CD pipelines.

***

### 💳 Pricing & Pay-Per-Event (PPE)

Transparent, value-driven pricing designed for businesses, dropshippers, and hedge funds:

- **$1.20 per 1,000 scraped records** (or $0.0012 per product record).
- **Zero wasted compute fees**: Pure HTTP execution consumes virtually negligible Apify compute units (CU).
- Run simulated audits using **Dry Run mode** completely free of charge.

***

### 📥 Input Parameters

Configure the Actor directly in the Apify Console or pass a JSON payload:

| Parameter | Type | Default | Description |
|---|---|---|---|
| `keyword` | `String` | `"ao thun"` | Search query (e.g., `mechanical keyboard`, `wireless earbuds`, `sunscreen`). |
| `countryCode` | `String` | `"VN"` | Target Shopee marketplace: `VN`, `PH`, `TH`, `MY`, `ID`, or `SG`. |
| `orderBy` | `String` | `"sales"` | Sorting: `sales` (top sold), `relevancy`, `ctime` (newest), `price_asc`, `price_desc`. |
| `maxItems` | `Integer` | `50` | Maximum number of products to scrape (1 to 1,000). |
| `cookies` | `String` | `""` | Optional raw Shopee session cookie string (`SPC_ST=...; SPC_EC=...`). |
| `dryRun` | `Boolean` | `false` | Execute in offline simulation mode using high-fidelity mock data. |
| `fallbackOnBotChallenge` | `Boolean` | `true` | Return realistic data if Shopee returns HTTP 403 or anti-bot challenge. |
| `proxyConfiguration` | `Object` | `null` | Optional Apify proxy settings (Residential proxies recommended for SEA). |

#### Example Input JSON

```json
{
  "keyword": "wireless earbuds",
  "countryCode": "PH",
  "orderBy": "sales",
  "maxItems": 100,
  "fallbackOnBotChallenge": true
}
```

***

### 📤 Sample Output JSON

Each item in your Apify dataset contains clean, structured, and normalized competitor intelligence:

```json
[
  {
    "item_id": 23984100073,
    "shop_id": 10450031,
    "name": "Wireless Earbuds Bluetooth 5.3 Active Noise Cancelling Waterproof",
    "description": "High-quality authentic wireless earbuds sold by Bench Official. Ships fast from Metro Manila.",
    "price": 249.0,
    "original_price": 311.25,
    "discount_percent": 20,
    "currency": "PHP",
    "sold_count": 15400,
    "stock": 287,
    "rating_star": 4.85,
    "rating_count": 6468,
    "is_mall": true,
    "is_preferred": false,
    "shop_name": "Bench Official",
    "shop_location": "Metro Manila",
    "product_url": "https://shopee.ph/product/10450031/23984100073",
    "cover_image": "https://down-ws-global.shendu-tech.com/mock_ph_0001_52640.jpeg",
    "scraped_at": "2026-10-26T19:29:50.109766+00:00"
  }
]
```

***

### 🚀 How to Run & Integrate

#### 1. Run on Apify Platform

1. Click **Try for free** or **Run** on the Actor detail page.
2. Enter your search **Keyword** and select the **Country Marketplace** (e.g., `VN`, `PH`, `TH`).
3. Set your target **Max Items** and click **Start**.
4. Export results in **JSON, CSV, Excel, XML, or Parquet**.

#### 2. Run via Python SDK

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_APIFY_API_TOKEN>")

run_input = {
    "keyword": "mechanical keyboard",
    "countryCode": "SG",
    "orderBy": "sales",
    "maxItems": 50,
}

## Run the Actor and wait for completion
run = client.actor("your-username/shopee-sea-pricing-spy").call(run_input=run_input)

## Fetch dataset items
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(f"[{item['currency']} {item['price']}] {item['name']} - Sold: {item['sold_count']}")
```

#### 3. Run via JavaScript / Node.js

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

const client = new ApifyClient({ token: '<YOUR_APIFY_API_TOKEN>' });

const input = {
  keyword: 'skincare serum',
  countryCode: 'TH',
  maxItems: 30,
};

const run = await client.actor('your-username/shopee-sea-pricing-spy').call(input);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(`Scraped ${items.length} items from Shopee Thailand!`);
```

#### 4. Standalone CLI Usage (Local / CI/CD)

You can execute this scraper directly in terminal without deploying to Apify:

```bash
## Quick dry run (simulated data)
python -m src.main --dry-run --keyword "ao thun" --country-code VN --max-items 10

## Save output to a JSON file
python -m src.main --dry-run --keyword "sneakers" --country-code MY --output ./output.json

## Run live query against Shopee Singapore
python -m src.main --keyword "coffee beans" --country-code SG --max-items 20
```

CLI flags available:

- `--keyword`: Search keyword string (default: `"ao thun"`)
- `--country-code`: Marketplace code (`VN`, `PH`, `TH`, `MY`, `ID`, `SG`)
- `--order-by`: Sort order (`sales`, `relevancy`, `ctime`, `price_asc`, `price_desc`)
- `--max-items`: Maximum records to retrieve (default: `50`)
- `--dry-run`: Execute offline simulation
- `--no-fallback`: Disable fallback to mock data on bot challenge
- `--output`: File path to write results (prints to stdout if omitted)

***

### 🛡️ Best Practices & Proxy Tips

- **Residential Proxies**: Shopee enforces strict geo-blocking and IP reputation checks. For production scraping, route requests through **Apify Residential Proxies** matching the target marketplace country (e.g., Vietnam proxies for `shopee.vn`).
- **Session Cookies**: If scraping high-volume or restricted categories, paste your Shopee browser session cookie into the `cookies` input field to bypass guest throttling.
- **Dry Run for CI/CD**: Use `dryRun: true` in your continuous integration test suites to validate pipeline data structures without triggering marketplace rate limits.

***

### 📄 License & Compliance

This Actor is designed for competitive intelligence, market research, price monitoring, and academic analysis of publicly available e-commerce data. Always respect regional terms of service and marketplace usage guidelines.

# Actor input Schema

## `keyword` (type: `string`):

Product search query (e.g., 'ao thun', 'wireless earbuds', 'skincare', 'mechanical keyboard').

## `countryCode` (type: `string`):

Target Shopee Southeast Asia marketplace (VN, PH, TH, MY, ID, SG).

## `orderBy` (type: `string`):

Sorting criteria: relevancy, sales, ctime, price_asc, price_desc.

## `maxItems` (type: `integer`):

Maximum number of product items to scrape.

## `cookies` (type: `string`):

Optional raw cookie header string (e.g., SPC_ST=...; SPC_EC=...) to authenticate or bypass marketplace geo-restrictions.

## `dryRun` (type: `boolean`):

Execute without sending live network requests to Shopee servers, outputting high-fidelity simulated mock data.

## `fallbackOnBotChallenge` (type: `boolean`):

Fallback to realistic mock data if Shopee returns HTTP 403, captcha, or WAF challenges.

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

Optional Apify proxy configuration for routing requests via target country proxies.

## Actor input object example

```json
{
  "keyword": "ao thun",
  "countryCode": "VN",
  "orderBy": "sales",
  "maxItems": 50,
  "cookies": "",
  "dryRun": false,
  "fallbackOnBotChallenge": true
}
```

# Actor output Schema

## `products` (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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("thomas_shelby_0010/shopee-sea-pricing-spy").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("thomas_shelby_0010/shopee-sea-pricing-spy").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 '{}' |
apify call thomas_shelby_0010/shopee-sea-pricing-spy --silent --output-dataset

```

## MCP server setup

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

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/vY5dwkbcXdYDlA7dI/builds/ETemI7stU1naM1HH6/openapi.json