# Yiwugo Listings Scraper (`piotrv1001/yiwugo-listings-scraper`) Actor

The Yiwugo Listings Scraper extracts products and supplier profiles from yiwugo.com (Yiwu Small-Commodity City) — capturing titles, prices, sales counts, supplier mobile/WeChat/email, factory addresses, and physical booth coordinates — ideal for B2B wholesale sourcing and dropshipping.

- **URL**: https://apify.com/piotrv1001/yiwugo-listings-scraper.md
- **Developed by:** [FalconScrape](https://apify.com/piotrv1001) (community)
- **Categories:** E-commerce, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 product listings

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

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

### 🚀 Yiwugo Listings Scraper

Easily extract product listings and supplier data from **Yiwugo** — the online storefront of Yiwu Small-Commodity City, the world's largest wholesale market. The **Yiwugo Listings Scraper** lets you pull structured product data, supplier contacts, and physical booth coordinates without dealing with the Vue SSR frontend or the CSRF handshake.

### ✨ Features

-   🏷️ **Comprehensive Product Data** – Titles, images, tiered prices, sales counts, MOQs, variants, fulfilment flags, and per-shop reputation.
-   📞 **Direct Supplier Contacts** – Mobile, WeChat, email, factory address, and shop credit for every listing (when details are enabled). This is the data that sourcing agents actually pay for.
-   🏪 **Physical Booth Coordinates** – Yiwugo's unique B2B angle: every shop's booth ID, market door, and street inside the Yiwu trade-city building. Walk straight to the booth on a sourcing trip.
-   🔍 **Keyword and Direct-ID Modes** – Search by free-text keyword (Chinese or English) or fetch specific product IDs you already know.
-   ⚡ **Fast & Cheap** – Plain JSON API + Cheerio crawler. No browser, no proxy needed by default, no anti-bot fees.

### 🛠️ How It Works

1. **Enter search keywords** (or product IDs) – Free-text keywords work in any language Yiwugo's search supports.
2. **Pick a depth** – Listing-only for cheap price-tracking, or **Include product details** for full supplier contact + booth data.
3. **Run the scraper** – Structured JSON output streams into the dataset in seconds.

### 🧾 Input

| Field | Type | Description | Default |
| --- | --- | --- | --- |
| `keywords` | `string[]` | Free-text keywords to search on Yiwugo. Chinese or English both work (e.g. `"phone case"` or `"手机壳"`). | `[]` |
| `productIds` | `string[]` | List of Yiwugo product IDs to fetch directly, skipping the search step. Useful when you already know what you want. | `[]` |
| `maxItems` | `integer` | Global hard cap on the total number of products scraped across all keywords and product IDs. Yiwugo's API caps any single keyword at ~5,000 items. | `50` |
| `includeDetails` | `boolean` | When enabled, fetches the full product detail JSON (supplier phone, WeChat, email, factory address, booth coordinates, attributes) for every listing. Switches billing to the higher-priced `item-detail` event. | `false` |
| `proxyConfiguration` | `object` | Proxy settings. Yiwugo doesn't require a proxy in validation; Apify Proxy is opt-in for scale. | `{ "useApifyProxy": false }` |

### 📊 Sample Output Data

Each item is a flat JSON record with nulls and empty fields stripped. Listing-only mode (`includeDetails: false`) returns the core product fields:

```json
{
    "id": 970407473,
    "productUrl": "https://www.yiwugo.com/product/970407473.html",
    "title": "适用苹果17pro手机壳磁吸16promax防摔硬壳磨砂撞色亚克力保护套",
    "images": ["http://ywgimg.yiwugo.com/product/shop_285318/normal/0/20260418/kVASQ5pjUIe2bukj.jpg"],
    "sellPrice": 275,
    "priceType": "1",
    "metric": "个",
    "startNum": 1,
    "saleNumber": 3719415,
    "dealQuantity": 64,
    "deliveryPromise": 2,
    "onlineOrderFlag": 1,
    "marketInfo": "国际商贸城",
    "shopId": 775063,
    "shopName": "云想百货",
    "contacter": "多多",
    "mobile": "15669663507"
}
````

With `includeDetails: true`, the record is enriched with the supplier contact dump and physical booth coordinates:

```json
{
    "id": 970407473,
    "productUrl": "https://www.yiwugo.com/product/970407473.html",
    "title": "适用苹果17pro手机壳磁吸16promax防摔硬壳磨砂撞色亚克力保护套",
    "sellPrice": 275,
    "unitprice": "3.13",
    "totalprice": "3.13",
    "metric": "个",
    "defaultfreight": "5.00",
    "saleNumber": 3719415,
    "dealQuantitys": "64",
    "propertyList": [
        { "pvalue": "颜色", "cvalueList": ["马卡龙磁吸-粉色", "马卡龙磁吸-黑色", "..."] }
    ],
    "shopId": 775063,
    "shopName": "云想百货",
    "years": 3,
    "shopCredit": 2,
    "shopIntegrityFraction": 7774,
    "contacter": "多多",
    "mobile": "15669663507",
    "safeMobile": "13335913818",
    "weixin": "15669663507",
    "email": "Lucy@gotoyiwu.com",
    "factoryAddress": "浙江省金华市义乌市江东街道",
    "marketCode": 14,
    "boothId": 761113,
    "boothOwners": "许海明"
}
```

### 💰 Pricing

Yiwugo Listings Scraper uses **pay-per-event** billing — you only pay for the products you successfully receive. No platform compute or proxy charges on top.

| Event | When it fires | Price (USD) | Per 1,000 items |
| --- | --- | --- | --- |
| `product-listing` | Each product pushed to the dataset when `includeDetails` is **off** (default) | $0.001 | **$1** |
| `item-detail` | Each product pushed to the dataset when `includeDetails` is **on** (full supplier contacts + booth) | $0.005 | **$5** |

Get started sourcing from Yiwu in minutes with **Yiwugo Listings Scraper**. 🚀

# Actor input Schema

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

Free-text keywords to search on Yiwugo. Chinese or English both work (e.g. "phone case" or "手机壳"). One keyword per array item.

## `productIds` (type: `array`):

List of Yiwugo product IDs to fetch directly (skips the search step). Use these when you already know which products you want.

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

Global hard cap on the total number of products scraped across all keywords and product IDs. Yiwugo's API caps any single keyword at ~5,000 items (50 per page × 100 pages).

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

When enabled, the actor fetches the full product detail JSON for every listing (supplier phone, WeChat, email, factory address, physical booth coordinates, attributes). Doubles request volume and switches billing to the higher-priced 'item-detail' event.

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

Proxy settings. Yiwugo does not require a proxy in validation; Apify Proxy is opt-in for scale.

## Actor input object example

```json
{
  "keywords": [
    "手机壳"
  ],
  "productIds": [],
  "maxItems": 50,
  "includeDetails": false,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `results` (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 = {
    "keywords": [
        "手机壳"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("piotrv1001/yiwugo-listings-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 = { "keywords": ["手机壳"] }

# Run the Actor and wait for it to finish
run = client.actor("piotrv1001/yiwugo-listings-scraper").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": [
    "手机壳"
  ]
}' |
apify call piotrv1001/yiwugo-listings-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=piotrv1001/yiwugo-listings-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Yiwugo Listings Scraper",
        "description": "The Yiwugo Listings Scraper extracts products and supplier profiles from yiwugo.com (Yiwu Small-Commodity City) — capturing titles, prices, sales counts, supplier mobile/WeChat/email, factory addresses, and physical booth coordinates — ideal for B2B wholesale sourcing and dropshipping.",
        "version": "0.0",
        "x-build-id": "Avp65ucxkXYPb815W"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/piotrv1001~yiwugo-listings-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-piotrv1001-yiwugo-listings-scraper",
                "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/piotrv1001~yiwugo-listings-scraper/runs": {
            "post": {
                "operationId": "runs-sync-piotrv1001-yiwugo-listings-scraper",
                "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/piotrv1001~yiwugo-listings-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-piotrv1001-yiwugo-listings-scraper",
                "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",
                "properties": {
                    "keywords": {
                        "title": "Search keywords",
                        "type": "array",
                        "description": "Free-text keywords to search on Yiwugo. Chinese or English both work (e.g. \"phone case\" or \"手机壳\"). One keyword per array item.",
                        "default": [],
                        "items": {
                            "type": "string"
                        }
                    },
                    "productIds": {
                        "title": "Product IDs",
                        "type": "array",
                        "description": "List of Yiwugo product IDs to fetch directly (skips the search step). Use these when you already know which products you want.",
                        "default": [],
                        "items": {
                            "type": "string"
                        }
                    },
                    "maxItems": {
                        "title": "Max items",
                        "minimum": 1,
                        "maximum": 50000,
                        "type": "integer",
                        "description": "Global hard cap on the total number of products scraped across all keywords and product IDs. Yiwugo's API caps any single keyword at ~5,000 items (50 per page × 100 pages).",
                        "default": 50
                    },
                    "includeDetails": {
                        "title": "Include product details",
                        "type": "boolean",
                        "description": "When enabled, the actor fetches the full product detail JSON for every listing (supplier phone, WeChat, email, factory address, physical booth coordinates, attributes). Doubles request volume and switches billing to the higher-priced 'item-detail' event.",
                        "default": false
                    },
                    "proxyConfiguration": {
                        "title": "Proxy configuration",
                        "type": "object",
                        "description": "Proxy settings. Yiwugo does not require a proxy in validation; Apify Proxy is opt-in for scale.",
                        "default": {
                            "useApifyProxy": false
                        }
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```