# 1688 Product Search Scraper | Wholesale Prices & Suppliers (`genial_candlestand/1688-product-search-scraper`) Actor

Get 1688.com wholesale product cards by keyword or category: title, CNY price, quantity price tiers, MOQ, units sold, supplier name, location and service scores, category ids and an ad flag. Price, province and city filters, sort by sales or price, exclude ads. No login.

- **URL**: https://apify.com/genial_candlestand/1688-product-search-scraper.md
- **Developed by:** [Flowo](https://apify.com/genial_candlestand) (community)
- **Categories:** E-commerce, Lead generation
- **Features:** Limited permissions
- **Stats:** 5 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.76 / 1,000 products

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

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

## 1688 Product Search Scraper | Wholesale Prices & Suppliers

![1688 Product Search Scraper | Wholesale Prices & Suppliers](https://api.apify.com/v2/key-value-stores/Ll7RrWtDkZYOrBvfE/records/1688-com-product-search-category-listings-banner-162715e8.png)

Search 1688.com, China's wholesale marketplace, by keyword or list a category, and get one row per product card: the title, unit price in CNY, quantity price tiers, minimum order quantity, units sold, the supplier's name, province and city, its trade-service scores, the category ids and a sponsored-ad flag. Filter by price, supplier province and city, sort by sales or price, and skip ads. No login needed.

### What does 1688 Product Search Scraper do?

You give it keywords (Chinese or English) or numeric 1688 category ids. It runs each one as a separate 1688 search and returns the product cards of the result list in 1688's order, up to 2,000 products per search. It is built for sourcing agents, importers, dropshippers and Amazon or Shopify sellers looking for suppliers and wholesale prices, and for market researchers who track what sells on 1688 and at what price. It reads the search results only and does not open product pages, so SKUs and specs are not included; pass the `url`s you choose to a product-details tool for that.

### How to scrape 1688 products by keyword or category

![How 1688 Product Search Scraper works: Calls the 1688 search API behind s.1688.com, 100 products per page; Pages each keyword or category up to your cap or the 2000-product limit; Retries blocked page](https://api.apify.com/v2/key-value-stores/Ll7RrWtDkZYOrBvfE/records/1688-com-product-search-category-listings-how-4b3942a8.png)

1. Open the actor in Apify Console.
2. Enter one or more **Search keywords**, e.g. 蓝牙耳机 or phone case, or one or more **Category IDs**, e.g. 1031910.
3. Optionally set **Max products per keyword or category**, **Sort by**, a CNY price range, a supplier province or city, and **Exclude ads**.
4. Click **Start** and wait for the run to finish.
5. Download the results as JSON, CSV or Excel, or read them through the API.

### How much does it cost to scrape 1688?

Price per event by Apify plan:

| Event | Free | Bronze | Silver | Gold and above |
|---|---|---|---|---|
| Product | $0.90 per 1,000 | $0.855 per 1,000 | $0.81 per 1,000 | $0.765 per 1,000 |
| Actor start | $0.00005 | $0.00005 | $0.00005 | $0.00005 |

A test run with the API example input below returned 200 rows in 10 s.

You pay for each product row saved to the dataset (the `product` event) plus a small start fee per run (the `apify-actor-start` event, charged per GB of memory; the default memory is 256 MB).

Not charged: the "recommended for you" items 1688 shows when a keyword has no real matches, ads skipped with **Exclude ads**, cards whose price or supplier location falls outside your filters, and repeats of the same product inside one search. The same product found by two different searches is two rows and two events.

Costs on the Free plan ($0.0009 per product, start fee included):

| Scenario | Product events | Cost |
|---|---|---|
| 20 cheapest offers for one keyword (`maxItems: 20`) | 20 | about $0.02 |
| 2 keywords × 100 products (the default input) | 200 | about $0.18 |
| 5 keywords × 200 products | 1,000 | about $0.90 |
| 5 keywords × 2,000 products (the 1688 maximum per search) | 10,000 | about $9.00 |

### Input

![1688 Product Search Scraper input example: Search keywords, Max products per keyword or category, Sort by, Exclude ads](https://api.apify.com/v2/key-value-stores/Ll7RrWtDkZYOrBvfE/records/1688-com-product-search-category-listings-input-bc9c3c10.png)

Give `queries`, `categoryIds` or both; an empty input is an input error.

- **Search keywords** (`queries`) — one search per keyword. Chinese keywords match best; English ones return Chinese offers.
- **Category IDs** (`categoryIds`) — numeric 1688 category ids listed without a keyword, e.g. 7 (apparel), 10166 (women's clothing), 1031910 (dresses). 1688 lists only some ids (most top-level ones); an unsupported id gives a warning and no rows. Categories are never combined with a keyword: each is its own search. A non-numeric id is an input error.
- **Max products per keyword or category** (`maxItemsPerQuery`) — 1 to 2,000, default 100. Pages past the first 400 products are slower.
- **Max products in total** (`maxItems`) — optional cap for the whole run.
- **Sort by** (`sort`) — `relevance` (default), `sales` (best selling, 30 days), `priceAsc` or `priceDesc`. Applies to keyword searches only; category listings always use relevance, with a warning.
- **Min price / Max price (CNY)** (`priceMin`, `priceMax`) — unit price range in yuan, decimals allowed; either one alone works. Min above max is an input error. Works with keywords and categories.
- **Supplier province** (`province`) — Chinese short form as 1688 shows it, e.g. 浙江, 广东. Suffixes 省/市/自治区 are removed automatically; Latin names (Zhejiang) are an input error.
- **Supplier city** (`city`) — Chinese with 市 or 县 exactly as 1688 shows it, e.g. 义乌市, 金华市; works with or without a province. Latin names are an input error.
- **Exclude ads** (`excludeAds`) — skip sponsored (P4P) cards; off by default, when ads are kept with `isAd: true`.
- **Proxy** (`proxyConfiguration`) — Apify datacenter proxy by default.

Example input:

```json
{
  "queries": ["保温杯"],
  "sort": "sales",
  "priceMin": 5,
  "priceMax": 20,
  "province": "浙江",
  "maxItemsPerQuery": 400,
  "excludeAds": true
}
```

### What data can you extract from 1688?

![1688 Product Search Scraper output example: Image, Title, Price (CNY), MOQ, Sold](https://api.apify.com/v2/key-value-stores/Ll7RrWtDkZYOrBvfE/records/1688-com-product-search-category-listings-output-a21f6aea.png)

| Field | What it is |
|---|---|
| `offerId`, `url`, `title`, `imageUrl` | 1688 offer id, product page, title as shown (usually Chinese), main image |
| `price`, `currency`, `priceType`, `priceLabel` | unit price on the card in CNY, always `CNY`, the price kind (e.g. NORMAL, UMP, TTTM), the label next to a promotion price (e.g. 限时价) |
| `priceTiers`, `minOrderQuantity`, `unit` | quantity tiers (`minQuantity`, `maxQuantity`, `price`), MOQ from the first tier, quantity unit (e.g. 个, 条, 套) |
| `soldText`, `soldCount`, `orderCount` | sales text as shown, units sold as a number (lower bound, 万 = 10,000), orders reported by 1688 |
| `repurchaseRatePercent`, `shopRepeatRatePercent` | offer repurchase rate and the shop's repeat-buyer rate (回头率), in percent |
| `sellerName`, `sellerLoginId`, `sellerMemberId`, `sellerUrl`, `sellerMobileUrl`, `sellerYears`, `businessType` | supplier name (usually the registered company), member login and id, shop links, years as a paid member, business type (e.g. 生产加工, 经销批发) |
| `province`, `city`, `location` | supplier location; `location` joins province and city |
| `isFactoryInspected`, `isBusinessInspected`, `isSuperFactory` | 1688 verification flags |
| `compositeScore`, `goodsScore`, `logisticsScore`, `disputeScore`, `consultationScore`, `returnScore` | supplier trade-service scores, 0–5 |
| `serviceTags`, `promotionTags`, `tags` | badges and all tags on the card |
| `categoryId`, `topCategoryId`, `categoryPathIds`, `similarItemsUrl` | leaf and top-level category ids, the id path from top to leaf, the 1688 page with similar products |
| `isAd` | sponsored (P4P) card |
| `query`, `searchCategoryId`, `page`, `position`, `totalFound` | the keyword or category id of the search, result page (100 per page), rank in the result list, products 1688 reports for the search (at most 2,000) |
| `scrapedAt` | when the row was extracted |

A real row (keyword 蓝牙耳机):

```json
{
  "offerId": "1040939180354",
  "url": "https://detail.1688.com/offer/1040939180354.html",
  "title": "跨境热卖pro6蓝牙耳机超长续航运动风入耳式J6无线耳机蓝牙工厂",
  "price": 7.43,
  "currency": "CNY",
  "priceType": "UMP",
  "priceLabel": "限时价",
  "priceTiers": [{ "minQuantity": 1, "maxQuantity": null, "price": 6.5 }],
  "minOrderQuantity": 1,
  "unit": "套",
  "soldText": "已售4100+件",
  "soldCount": 4100,
  "orderCount": 202,
  "repurchaseRatePercent": 27,
  "shopRepeatRatePercent": 50,
  "imageUrl": "https://cbu01.alicdn.com/img/ibank/O1CN01C8J2HW1JnU6ub6lCp_!!2219119701073-0-cib.jpg",
  "sellerName": "东莞市茶山戈音电子厂",
  "sellerLoginId": "东莞市茶山戈音电子厂",
  "sellerMemberId": "b2b-2219119701073038bc",
  "sellerUrl": "http://geyinshop168.1688.com",
  "sellerMobileUrl": "https://m.1688.com/winport/b2b-2219119701073038bc.html",
  "sellerYears": 2,
  "businessType": "生产加工",
  "province": "广东",
  "city": "东莞市",
  "location": "广东 东莞市",
  "isFactoryInspected": false,
  "isBusinessInspected": false,
  "isSuperFactory": false,
  "serviceTags": [],
  "promotionTags": [],
  "tags": ["退货包运费", "先采后付", "回头率50%"],
  "compositeScore": 4.5,
  "goodsScore": 2.33,
  "logisticsScore": 3.86,
  "disputeScore": 5,
  "consultationScore": 4,
  "returnScore": 4.33,
  "categoryId": "1048186",
  "topCategoryId": "7",
  "categoryPathIds": ["7", "50911", "1048186"],
  "similarItemsUrl": "https://s.1688.com/selloffer/similar_search.html?offerIds=1040939180354&…",
  "isAd": false,
  "query": "蓝牙耳机",
  "searchCategoryId": null,
  "page": 1,
  "position": 6,
  "totalFound": 2000,
  "scrapedAt": "2026-11-12T21:31:14.506Z"
}
```

### Use cases

- **Find suppliers for a product**: search 蓝牙耳机 or phone case and compare price tiers, MOQ, units sold and supplier scores.
- **Best sellers in a price band**: sort 保温杯 by sales with a 5–20 CNY range to see what sells at that price.
- **Suppliers from a sourcing hub**: limit 连衣裙 to 浙江 / 义乌市 and skip ads to get only Yiwu suppliers.
- **Browse a category**: list category 1031910 (dresses) or 7 (apparel) without a keyword.
- **Quick price check**: the 20 cheapest 螺丝 (screw) offers with `sort: priceAsc` and `maxItems: 20`.

### Limitations

- 1688 returns at most 2,000 products per search. For more, run several price ranges yourself.
- Only search-card data: no SKU variants, specs, stock, shipping or certificates. Titles stay in Chinese (no translation), and prices are in CNY only (no USD conversion).
- Categories come as ids only (`categoryId`, `topCategoryId`, `categoryPathIds`), not names.
- Only some category ids can be listed (most top-level ones), and category listings cannot be sorted.
- Pages past the first 400 products are slower: 1688 often asks for a login there, and the actor retries. If a page still fails, the rows already saved are kept and that search stops with a warning.
- 1688 filters prices on its own basis; cards whose shown price is still outside your range are dropped, so a search can return fewer rows than your cap.
- Fields that can be `null`: `price`, `priceType`, `priceLabel`, `minOrderQuantity`, `unit`, `soldText`, `soldCount`, `orderCount`, `repurchaseRatePercent`, `shopRepeatRatePercent`, `imageUrl`, all `seller…` fields, `businessType`, `province`, `city`, `location`, the six score fields, `categoryId`, `topCategoryId`, `similarItemsUrl`, `query` (for a category), `searchCategoryId` (for a keyword) and `totalFound`. `priceTiers`, `categoryPathIds`, `serviceTags` and `promotionTags` can be empty lists.

### Tips and troubleshooting

- **0 rows for a keyword**: 1688 had no real matches and showed only recommendations, which the actor skips with a warning. Try a Chinese keyword.
- **0 rows for a location**: use the exact Chinese name 1688 shows, with 市 for cities (义乌市, not 义乌). A city outside the given province returns nothing.
- **0 rows for a category**: 1688 does not list that id; the run log names it. Try a top-level id such as 7.
- **Fewer rows than the cap**: excluded ads, cards outside your price range and the 2,000-per-search limit all reduce the count.
- **Many searches in one run**: put keywords and category ids together; each is a separate search, and `maxItems` caps the whole run.
- **Proxy**: the default datacenter proxy is enough; blocked requests are retried on new IPs and then once via residential proxy automatically.

### API, MCP and integrations

Run the actor from your code with the same JSON input as in Console. Your API token is in [Console → Settings → API & Integrations](https://console.apify.com/settings/integrations).

**Python** (`pip install apify-client`):

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("genial_candlestand/1688-product-search-scraper").call(run_input={"queries": ["蓝牙耳机", "phone case"], "maxItemsPerQuery": 100})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)
```

**Node.js** (`npm install apify-client`):

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

const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' });
const run = await client.actor('genial_candlestand/1688-product-search-scraper').call({"queries": ["蓝牙耳机", "phone case"], "maxItemsPerQuery": 100});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

**HTTP** — one request runs the actor and returns the results (runs up to 5 minutes; longer ones: [run asynchronously](https://docs.apify.com/api/v2/act-runs-post)):

```bash
curl -X POST "https://api.apify.com/v2/acts/genial_candlestand~1688-product-search-scraper/run-sync-get-dataset-items?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"queries":["蓝牙耳机","phone case"],"maxItemsPerQuery":100}'
```

**AI agents (MCP).** Add the actor as a tool of the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp). Claude Code:

```bash
claude mcp add --transport http apify "https://mcp.apify.com?tools=genial_candlestand/1688-product-search-scraper"
```

Claude Desktop, Cursor or VS Code: `{"mcpServers": {"apify": {"url": "https://mcp.apify.com?tools=genial_candlestand/1688-product-search-scraper"}}}`. Then ask, for example:

- "Find 1688 suppliers of 蓝牙耳机 with price tiers, MOQ and supplier scores"
- "List best-selling 保温杯 on 1688 priced 5 to 20 CNY from suppliers in 浙江"
- "Get the 20 cheapest 螺丝 offers on 1688 without ads"

**Integrations.** Run it on a schedule with [Apify Schedules](https://docs.apify.com/platform/schedules) and send the results to Google Sheets, Slack, Zapier, Make, n8n or your webhook — see [Apify integrations](https://docs.apify.com/platform/integrations).

### FAQ

**Is it legal to scrape 1688.com?**<br>
The actor collects only product and supplier data that 1688 shows publicly in its search results, without logging in. You are responsible for how you use the data and for following the laws and terms that apply to you.

**Can I search in English?**<br>
Yes. English keywords return Chinese offers that match them, but Chinese keywords match best. Titles are returned as 1688 shows them, usually in Chinese.

**Why is the same product in my data twice?**<br>
When two of your searches find the same product, each search gives its own row with its own `query` or `searchCategoryId`. Repeats inside one search are removed and not charged.

**How do I find category ids?**<br>
Every row has `categoryId`, `topCategoryId` and `categoryPathIds`. Run a keyword search first and reuse the ids you see, e.g. 7 for apparel.

**How is it different from other 1688 actors?**<br>
It costs $0.90 per 1,000 products on the Free plan, against $4.99 for the most used 1688 actor, and works with the datacenter proxy. It also lists categories without a keyword, marks ads with `isAd` and can skip them for free, gives the supplier scores as numbers and the category id path, and does not charge for recommendations or cards outside your filters.

### Also useful

- [AliExpress Product Scraper](https://apify.com/genial_candlestand/aliexpress-product-details-scraper) — compare retail prices of the same goods: SKU variants, shipping cost and sold count
- [Amazon Best Sellers Scraper](https://apify.com/genial_candlestand/amazon-best-sellers-scraper) — find products that sell on Amazon before sourcing them: rank, price and reviews
- [eBay Search Scraper](https://apify.com/genial_candlestand/ebay-search-scraper-listings-prices) — check resale prices on eBay: listing price, condition, shipping and sold count
- [Etsy Search Scraper](https://apify.com/genial_candlestand/etsy-search-scraper) — see what similar products cost on Etsy: price, shop rating and bestseller badges

# Actor input Schema

## `queries` (type: `array`):

Keywords to search on 1688.com, one per line, e.g. 蓝牙耳机 or phone case. Chinese keywords match best; English ones return Chinese offers. Each keyword is a separate search. Give queries, categoryIds or both.

## `categoryIds` (type: `array`):

Numeric 1688 category ids to list without a keyword, e.g. 7 (apparel), 10166 (women's clothing), 1031910 (dresses). 1688 lists only some ids (most top-level ones): an unsupported id gives a warning and no rows; a non-numeric id is an input error. Category listings always use relevance order. Each id is its own search, never combined with a keyword.

## `maxItemsPerQuery` (type: `integer`):

Stop each search after this many products (1–2000). 1688 returns at most 2000 products per search; pages past the first 400 products are slower (1688 often asks for a login there and the actor retries).

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

Optional cap on products for the whole run, over all keywords and categories. Empty = no total cap.

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

Order of the results: relevance (default), best selling in 30 days, price low to high or high to low. Applies to keyword searches; category listings always use relevance (with a warning).

## `priceMin` (type: `number`):

Only products from this unit price in yuan (CNY), decimals allowed, e.g. 5. Works with keywords and categories. Cards whose shown price is still below it are dropped and not charged.

## `priceMax` (type: `number`):

Only products up to this unit price in yuan (CNY), e.g. 20. Must not be lower than Min price (input error). Cards whose shown price is still above it are dropped and not charged.

## `province` (type: `string`):

Only suppliers from this province, in Chinese short form as 1688 shows it: 浙江, 广东, 北京, 广西. Suffixes 省/市/自治区 are removed automatically. Latin names (Zhejiang) are an input error. Works with keywords and categories.

## `city` (type: `string`):

Only suppliers from this city, in Chinese exactly as 1688 shows it, with 市 or 县: 金华市, 义乌市, 广州市. Works with or without a province. Latin names (Yiwu) are an input error. A value 1688 does not know (or a city outside the province) gives a warning and no rows for that search.

## `excludeAds` (type: `boolean`):

Skip sponsored (P4P) cards. Skipped ads are not charged. Off: ads are kept and marked with isAd = true.

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

Apify datacenter proxy is enough for 1688 search; blocked requests are retried on new IPs and then once via residential proxy automatically.

## Actor input object example

```json
{
  "queries": [
    "蓝牙耳机",
    "phone case"
  ],
  "maxItemsPerQuery": 100,
  "sort": "relevance",
  "excludeAds": false,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `results` (type: `string`):

Dataset with one row per product card

## `overview` (type: `string`):

Products in the overview table view

# 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 = {
    "queries": [
        "蓝牙耳机",
        "phone case"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("genial_candlestand/1688-product-search-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 = { "queries": [
        "蓝牙耳机",
        "phone case",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("genial_candlestand/1688-product-search-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 '{
  "queries": [
    "蓝牙耳机",
    "phone case"
  ]
}' |
apify call genial_candlestand/1688-product-search-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,genial_candlestand/1688-product-search-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/FnNR5CVRCqNUPnw25/builds/OkF9ifPKBiO3kj7iY/openapi.json
