# 1688.com Wholesale Scraper: Products & Suppliers (`theshark/china-1688-scraper`) Actor

Scrape 1688.com, China's largest wholesale marketplace, without a login. Search by keyword, link, category or photo, find cheaper look-alikes, look up suppliers and track price changes. Get tiered prices, MOQ, stock, sales, images, SKU variants, reviews and factory data. Pay only for results.

- **URL**: https://apify.com/theshark/china-1688-scraper.md
- **Developed by:** [TheShark](https://apify.com/theshark) (community)
- **Categories:** E-commerce, Automation
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.99 / 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.

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 Scraper: Wholesale Products, Prices and Suppliers from 1688.com

Scrape product data from [1688.com](https://www.1688.com) (Alibaba 1688), China's largest wholesale marketplace. Search by keyword, search link, category or photo, find cheaper look-alikes of a product, look up suppliers, or give a list of product IDs, and get a full product card for each item: tiered prices, minimum order quantity (MOQ), stock, sales, images, attributes, supplier profile and shipping. Optional add-ons bring SKU variants, buyer reviews, detailed factory data and the same item from other sellers. A fast cards-only mode and change monitoring are built in.

No 1688 account, login, cookies or proxies of your own are needed. You pay only for products that were collected successfully.

### What can you do with 1688 Scraper?

- **Source products:** find wholesale suppliers and compare factory prices for a product or a whole category.
- **Find cheaper sellers:** search by photo, or find look-alikes of a 1688 offer, sorted from the cheapest.
- **Check suppliers:** company registration, founding year, factory profile, shop ratings, certificates and customization services.
- **Collect a supplier's products:** give a shop link, shop ID or company name.
- **Track prices:** run the same input on a schedule and see which prices, stock levels and sales changed since the last run.
- **Build catalogs:** product images, videos, attributes, variants and descriptions for dropshipping and e-commerce work.
- **Use it as a 1688 API:** start runs and get results from your own code through the Apify API.

### What data can you get from 1688.com?

| Data | Fields |
|---|---|
| Product | offer ID, link, title, category, attributes, package size and weight |
| Price and ordering | price range, quantity price tiers, MOQ, unit, stock, mixed wholesale, single-piece retail |
| Sales and popularity | sold count, favorites, badges, review summary (good rate, grade, buyer impression tags) |
| Media | images, main images, video, description images, description HTML (optional) |
| Variants (optional) | every SKU with its options, price, stock and sales |
| Reviews (optional) | review text, rating, date, variant, quantity, buyer city |
| Supplier | company name, shop link, seller chat link, location, service score, repeat buyer rate, supplier type, company registration, founding year, factory profile, shop metrics |
| Supplier intelligence (optional) | factory card (videos, rankings, equipment, production lines, OEM minimums, capacity, address), product certificates (CE, FCC, RoHS and more), customization services and prices, lead times, dropshipping metrics, product ranking |
| Shipping and services | ships from, shipping cost, delivery promise, services, coupons, sales channels |
| Same items (optional) | up to 8 offers of the same item from other sellers |
| Monitoring | NEW, CHANGED (with before and after values), UNCHANGED or GONE for every product |

### How to scrape 1688.com

1. Open the actor and fill in at least one source: keywords, product IDs, search links, a category, photos, look-alike offers or suppliers.
2. Set the number of results and, if you like, filters such as price, MOQ, region or supplier type.
3. Choose the extra data you need: variants, reviews, supplier intelligence, same items.
4. Click **Start**. Products appear in the dataset while the run goes on.
5. Download the results as JSON, CSV, Excel or HTML, or get them through the API.

If you start the actor with an empty input, it runs a small example search (20 products), so you can see what the data looks like.

### Input

The input form has four sections: **What to scrape**, **Search filters**, **Data to include** and **Monitoring**. Every source you fill in is processed, in this order: offer IDs, then keywords, search links and category, then photos, then look-alikes, then suppliers.

#### What to scrape

| Field | Type | Default | What it does |
|---|---|---|---|
| `keywords` | list of strings | empty | Search keywords, Chinese or English, for example `["手机壳", "phone case"]`. Each keyword is searched separately, one after another. |
| `offerIds` | list of strings | empty | 1688 product IDs or product links (`detail.1688.com/offer/<id>.html`). These products are scraped first, always from their product pages. |
| `searchUrls` | list of strings | empty | Links to 1688 search results. The keyword and filters of the link are used and win over the filters of the form. |
| `categoryId` | string | none | 1688 category ID of level 1 or 2 (for example `1813` for toys). Alone it is a search by itself; next to keywords or links it is a filter. |
| `imageUrls` | list of strings | empty | Photos to search by (search by photo). Each photo is searched separately. |
| `similarToOfferIds` | list of strings | empty | 1688 product IDs or links. For each one, the products that look the same or very close are found and scraped. |
| `maxSimilarityScore` | number | `0.2` | Only for `similarToOfferIds`: products with a higher `similarityScore` are skipped. |
| `suppliers` | list of strings | empty | Shop links, shop IDs (`b2b-...`) or exact company names. One profile row per supplier. |
| `maxProductsPerSupplier` | integer, 0 to 1000 | `0` | How many products to scrape for each supplier. `0` means only the profile. |
| `maxResults` | integer, 1 to 5000 | `100` | Maximum number of products per keyword, link, category, photo or look-alike offer. |
| `scrapeProductPages` | boolean | `true` | `false` is the fast cards-only mode (see the examples). |

#### Search filters

| Field | Type | Default | What it does |
|---|---|---|---|
| `sortBy` | `relevance`, `bestSelling`, `priceAsc`, `priceDesc` | `relevance` | Order of search results. |
| `priceMin`, `priceMax` | number (CNY) | none | Only products priced at or above, or at or below, this value. |
| `minOrderQuantityFrom`, `minOrderQuantity` | integer | none | Only products whose minimum order quantity (MOQ) is at least, or at most, this value. |
| `merchantType` | `any`, `verifiedMerchant` | `any` | `verifiedMerchant`: only verified merchants (实力商家). |
| `province`, `city` | string | none | Supplier province and city in Chinese characters, for example `广东`, `深圳`. Several provinces can be separated by commas, for example `江苏,浙江`. |
| `dropshipping`, `freeShipping`, `dropshipFreeShipping`, `sevenDayReturn`, `fastInvoice`, `officialLogistics`, `verifiedFactory`, `bigBrandOem` | boolean | `false` | Yes/no filters that 1688 applies on its side. Some pairs cannot be combined on 1688 (for example `verifiedFactory` and `bigBrandOem`): the first one is used and a warning says so. |
| `excludeKeywords` | list of strings | empty | Skip products whose title contains any of these words. |

#### Data to include

| Field | Type | Default | What it does |
|---|---|---|---|
| `includeSkuDetails` | boolean | `false` | Add the full variant matrix: each variant with its options, price, stock and sales. |
| `includeDescriptionHtml` | boolean | `false` | Add the full product description as HTML. Description text and images are always included. |
| `includeReviews` | integer, 0 to 100 | `0` | How many latest reviews to attach to each product. Charged per review delivered. |
| `includeSupplierIntelligence` | boolean | `false` | Add a `supplierIntelligence` block with detailed factory, certificate, customization, dropshipping and ranking data. Charged as an extra event. |
| `includeSameItems` | boolean | `false` | Add a `sameItems` list: up to 8 offers of the same item from other sellers. Charged as an extra event only when the list is not empty. Needs product pages. |

#### Monitoring

| Field | Type | Default | What it does |
|---|---|---|---|
| `monitorName` | string | none | Turns on change monitoring (free), see below. |

### Examples

Keyword search (full product cards):

```json
{
  "keywords": ["保温杯", "thermos cup"],
  "maxResults": 50,
  "sortBy": "bestSelling",
  "priceMax": 30,
  "includeReviews": 10
}
```

Specific products:

```json
{ "offerIds": ["735353578254", "https://detail.1688.com/offer/634155097789.html"] }
```

Search link and category (the filters of the link win over the form):

```json
{
  "searchUrls": ["https://s.1688.com/selloffer/offer_search.htm?keywords=%CA%D6%BB%FA%BF%C7&priceStart=5"],
  "maxResults": 200
}
```

```json
{ "categoryId": "1813", "maxResults": 100, "sortBy": "bestSelling" }
```

Cards-only mode: products are taken straight from the search results, which is much faster and cheaper (event `product-card`). Rows have the search-card fields: title, price tiers, image, seller, sales and trade scores. Reviews, supplier intelligence and same items are not collected in this mode:

```json
{ "keywords": ["手机壳"], "maxResults": 600, "scrapeProductPages": false }
```

Search by photo. Links on alicdn.com (1688 product images) are used directly; any other image is downloaded, resized and uploaded to 1688 (JPEG, PNG, GIF and WEBP work). Every row has `similarityScore`: smaller is closer (below 0.1 is almost the same photo):

```json
{
  "imageUrls": ["https://cbu01.alicdn.com/img/ibank/O1CN01lAdPke1OFCTM0qUJK_!!3872131675-0-cib.jpg"],
  "maxResults": 100
}
```

Look-alikes of a product: the main image of the offer is used to find the same or very close products from other sellers, cheapest first. The offer itself is not included.

```json
{ "similarToOfferIds": ["735353578254"], "maxResults": 50, "maxSimilarityScore": 0.2 }
```

Suppliers, with their products:

```json
{
  "suppliers": ["https://shop1388209852876.1688.com/", "b2b-2207252800234f4b31", "深圳市亿佳合兴科技有限公司"],
  "maxProductsPerSupplier": 50
}
```

Monitoring: run the same input again later with the same `monitorName`:

```json
{ "offerIds": ["735353578254", "634155097789"], "monitorName": "my-cases" }
```

### How it works

**Queries one by one.** Keywords, search links, categories, photos, look-alike offers and suppliers are handled one after another: the actor searches the first one, scrapes its products, then moves on to the next. Products appear in the dataset from the start. A product found by two queries appears once, with the first query in `source` (and in `sourceKeyword` for keywords).

**Filters and `maxResults`.** Price, minimum order quantity, region and `excludeKeywords` are checked on the search results, and `maxResults` counts products that passed them. `verifiedMerchant` (and the exact price and MOQ) can only be checked on the product page, so with these filters a keyword can give fewer rows than `maxResults`. The yes/no filters (`dropshipping` and the others), `minOrderQuantityFrom` and `categoryId` are filters of the 1688 search itself: they do not apply to photo searches, look-alikes and supplier products found without a search card, and the run warns when you combine them. In cards-only mode `verifiedMerchant` is only 1688's own search filter, because product pages are not opened.

**Suppliers.** A supplier row (`rowType` is `supplier`) has the company name, registration, shop header and ratings, the factory card for factories, shop metrics and the IDs of the shop's hot offers. A shop link, a shop ID or an exact company name is accepted; a product link is not a supplier (put it in `offerIds`). With `maxProductsPerSupplier` above 0, the supplier's products are scraped as normal products (full card, billed as products) and carry the supplier in `source`. Products come from a search by the exact company name, the factory card list for factories and the shop's hot and new offers. In cards-only mode, the products from the company-name search come as cheaper search cards, while products from the factory card list and the hot and new offers are scraped from their product page and billed as `product`.

**Monitoring.** With `monitorName` the actor compares every product with the previous run and adds a `monitor` object to the row: `status` is `NEW` (not seen before), `CHANGED` (`changes` lists the price, stock, sold count, title or status that differ, with `before` and `after`), `UNCHANGED`, or `GONE` (a product from `offerIds` that was found last time is not found now), plus `previousScrapedAt`. The previous state of every product is kept in a named key-value store in your Apify account, `china-1688-monitor-<name>` (the name is lower-cased; use Latin letters and digits, other characters are dropped), in the record `SNAPSHOT`. The store is shared by all runs with the same name: use the same name to compare runs and different names for separate watch lists. Records older than 90 days are removed. A product with status `BLOCKED` or `ERROR` this time gets `monitor: null`, and its stored state is kept for the next run. Monitoring is free. The **Changes** dataset view shows the `monitor` column. Combine monitoring with an Apify schedule to watch prices every day or week.

### Output

One dataset row per product, plus one row per supplier when you use `suppliers` (`rowType` is `product` or `supplier`). Rows can be downloaded as JSON, CSV, Excel and more. Text fields (titles, attributes, supplier names, reviews) are in the original Chinese, prices are in CNY. The dataset has four views: **Products**, **Search cards** (cards-only rows), **Suppliers** and **Changes**. A dataset view shows all rows, so in the Suppliers view look at the rows that have a company name, and in the Changes view at the `monitor` column.

#### Field groups

- **Identity:** `offerId`, `detailUrl`, `title`, `categoryId`, `categoryName`, `sourceKeyword`, `scrapedAt`.
- **Price and ordering:** `price` (min, max, currency CNY), `quantityPrices` (price tiers), `minOrderQuantity`, `unit`, `stock`, `mixWholesale`, `supportsOnePieceRetail`.
- **Sales and popularity:** `soldCount`, `soldDisplay`, `soldPeriod`, `favoriteCount`, `badges`, `shopReviewSummary` (good rate, grade, buyer impression tags).
- **Review summary (always included, free):** `reviewSummary` with the product's good rate, grade, review counts by type, buyer impression tags and fulfilment metrics.
- **Media:** `images`, `mainImages`, `videoUrl`, `videoCoverUrl`, description images and `descriptionUrl`.
- **Specs:** `attributes` (name and value pairs), `packageDetails` (size and weight), `unitWeightKg`.
- **Supplier:** `supplier` with company name, shop link, seller chat link, location, service score, repeat buyer rate and supplier type flags, plus company registration, founding year, supplier profile (staff, area, equipment, verification) and shop metrics when available.
- **Shipping and services:** `shipping` (ships from, cost, delivery text), `services`, `coupons`, `distributionChannels`, `flags`, `compliance`.
- **Search card data** (products found by a search: keywords, links, categories, photos, look-alikes and the supplier's company-name search; not products from `offerIds`): `isPromoted`, `repurchaseRate`, and extra supplier fields such as `tradeScores` and inspection report links.
- **Photo search and look-alikes:** `similarityScore` (smaller is closer), `source` (which query found the row).
- **Cards-only rows:** `dataLevel` is `card` (rows with a product page have `full`).
- **Same items** (`includeSameItems`): `sameItems`.
- **Monitoring** (`monitorName`): `monitor`.
- **Status:** `status`, `statusMessage`, `warnings`.

Optional add-ons:

- `skuDetails` (`includeSkuDetails`): variant axes and every variant with price, stock and sales.
- `descriptionHtml` (`includeDescriptionHtml`): the full description HTML.
- `reviews` (`includeReviews`): latest reviews with text, rating, date, variant, quantity and buyer city. Buyer names, avatars and profiles are never collected, and phone numbers or WeChat/QQ contacts found in review text are removed. 1688 shows visitors without an account only part of a product's reviews (for example 45 of 102 in the review summary), so `reviews` can be shorter than `includeReviews` and `reviewSummary.counts.total`. If the reviews of a product could not be collected, `reviews` is `null`, `warnings` says so, and its reviews are not charged.
- `supplierIntelligence` (`includeSupplierIntelligence`): factory card for verified factories (videos, rankings, equipment list, production lines, OEM minimums, production capacity, factory address and coordinates), certificates of this product (for example CE, FCC, RoHS test reports), customization (services with prices, printing price list, lead times by quantity), dropshipping metrics and the product's ranking on 1688. Which parts are present depends on the supplier: many suppliers have no factory card or no certificates.

#### Example row (shortened)

Long lists are cut here for readability. Real rows contain full lists.

```json
{
  "offerId": "735353578254",
  "detailUrl": "https://detail.1688.com/offer/735353578254.html",
  "status": "OK",
  "statusMessage": "",
  "warnings": [],
  "title": "适用iphone18PRO大视窗磁吸手机壳15磨砂漏标苹果11秒变17保护套",
  "categoryName": "iPhone保护套",
  "unit": "个",
  "price": { "min": 9.0, "max": 9.0, "currency": "CNY", "basis": "quantity" },
  "quantityPrices": [
    { "minQuantity": 2, "price": 9.0 },
    { "minQuantity": 500, "price": 8.5 },
    { "minQuantity": 5000, "price": 7.5 }
  ],
  "minOrderQuantity": 2,
  "stock": 2692428,
  "mixWholesale": { "supported": true, "minQuantity": 2, "minAmount": 5 },
  "soldCount": 19793,
  "soldDisplay": "1.9万+",
  "soldPeriod": "一年内",
  "favoriteCount": 458,
  "images": [
    "https://cbu01.alicdn.com/img/ibank/O1CN01lAdPke1OFCTM0qUJK_!!3872131675-0-cib.jpg"
  ],
  "videoUrl": "https://cloud.video.taobao.com/play/u/3872131675/p/2/e/6/t/1/533538773043.mp4",
  "attributes": [
    { "name": "材质", "value": "PC" },
    { "name": "款式", "value": "防摔款" },
    { "name": "品牌", "value": "潮虹兔" }
  ],
  "unitWeightKg": 0.03,
  "shopReviewSummary": { "goodRate": 99.6, "grade": 5.0 },
  "badges": ["镇店之宝"],
  "supplier": {
    "companyName": "深圳市亿佳合兴科技有限公司",
    "shopUrl": "https://winport.m.1688.com/page/index.html?memberId=b2b-38721316754ec7c",
    "serviceScore": 4.0,
    "repeatBuyerRate3m": 56.5,
    "isTp": true,
    "location": "广东省深圳市"
  },
  "shipping": {
    "from": "广东省深圳市",
    "cost": 3.0,
    "text": "承诺48小时发货·常发韵达快递",
    "deliveryLimit": 2
  },
  "services": [{ "name": "晚发必赔" }],
  "distributionChannels": ["淘宝", "抖音", "快手", "微信", "Lazada", "Amazon", "Shopify", "Shopee"],
  "sourceKeyword": "手机壳",
  "scrapedAt": "2026-11-12T15:21:54+00:00"
}
```

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

The actor uses pay-per-event pricing: you pay a flat price per collected product and per add-on. The current prices are on the **Pricing** tab. Cards-only mode is the cheapest way to collect large volumes.

| Event | When it is charged |
|---|---|
| `product` | One product collected from its product page (status `OK`). |
| `product-card` | One product taken from the search results in cards-only mode (status `OK`). Cheaper than `product`. |
| `reviews` | One review attached to a product (`includeReviews` above 0): a product with 20 reviews is 20 events. |
| `same-items` | `sameItems` is not empty (`includeSameItems` on). |
| `supplier-intelligence` | At least part of the supplier intelligence data was found (`includeSupplierIntelligence` on). |
| `supplier` | One supplier profile found (`suppliers`, status `OK`). |

You pay only for what was delivered:

- Only rows with status `OK` are charged. Products skipped by your filters are free.
- An add-on is charged only when its data is in the row. A product without reviews, or a supplier without factory data, costs nothing extra.
- Set a maximum charge per run in Apify and the actor stops cleanly when it is reached. An add-on that no longer fits is left out of the row (`warnings` says so) and is not charged.
- A product is never charged twice in one run.

#### Row statuses

Every row has an explicit `status`, so you always know what each row is:

| Status | Meaning | Charged? |
|---|---|---|
| `OK` | The product (or the supplier profile) was collected. | Yes |
| `NOT_FOUND` | The product is no longer on 1688 or the ID is wrong, or a search or a supplier has no results. | No |
| `BLOCKED` | 1688 did not show this page this time. Try it again later. | No |
| `ERROR` | The row could not be collected, for example an invalid link or a page without prices. `statusMessage` says why. | No |

If the run reaches its time limit or your maximum charge before everything is done, it still finishes as succeeded and keeps all collected data. Products and queries it did not get to are listed as free rows whose `statusMessage` starts with `Not scraped:`, `Not searched:` or `Supplier products not collected:`, so you can run them again.

### Good to know

- **Up to 5,000 products per query.** One 1688 search gives up to 300 products. Deeper results come from extra searches split by price range and sort order, so they take longer and are less relevant. For the most relevant products, use more specific keywords or filters.
- **About 700 products per photo.** A search by photo, or look-alikes of an offer, returns up to about 700 products. `similarityScore`: smaller means closer.
- **Supplier products.** About 180 to 260 products per supplier can be found without a 1688 account; the full catalog is shown only to logged-in users.
- **Cards-only rows are lighter.** They have only the fields of the search card. Use full mode for variants, description, reviews and supplier intelligence.
- **Data is in Chinese.** Titles, attributes, supplier names and reviews come as 1688 shows them. Prices are in CNY.
- **No contacts and no buyer data.** The actor does not collect phone numbers, emails, WeChat or QQ, the names of company contact persons, or buyer names, avatars and profiles. The only supplier contact is the public seller chat link.
- **No login.** Only data visible without a 1688 account is collected. For example, the supplier company's own certificate list is not available (certificates of the product itself are).
- **Run settings.** Give the run a timeout of at least 5 minutes: the actor finishes saving products a few minutes before the timeout. The minimum memory is 1024 MB.

### Integrations and API

- **API:** start runs and download results with the [Apify API](https://docs.apify.com/api/v2) or the Apify clients for Python and JavaScript.
- **Schedules:** run the actor every day or week, for example with `monitorName` to track price changes.
- **Integrations:** send results to Google Sheets, Slack, Make, Zapier, webhooks and other tools supported by Apify.

### FAQ

**Do I need a 1688 account or proxies?**
No. The actor uses its own proxies in China and does not log in.

**Why are the results in Chinese?**
That is the language of 1688. Search with Chinese keywords for the best results; English keywords work too.

**How many products can I get for one keyword?**
Up to 5,000 per query.

**Can I scrape specific products?**
Yes. Put product IDs or links in `offerIds`. They are scraped first. If you only want them, leave the other sources empty.

**Can I find the same product from other sellers?**
Yes: give a photo in `imageUrls`, or an offer in `similarToOfferIds`. Or turn on `includeSameItems` to get up to 8 offers of the same item in each row.

**How do I see price changes between runs?**
Set the same `monitorName` on every run. Each product row gets a `monitor` status: `NEW`, `CHANGED`, `UNCHANGED` or `GONE`.

**Do I pay for products that were not collected?**
No. Only rows with status `OK` are charged. Every other row has a status and a message, and you can run those products again with `offerIds`.

**Do you collect supplier phone numbers or emails?**
No. Contact details, WeChat/QQ and contact person names are not collected. Free supplier data includes company registration, founding year, profile and shop metrics.

**Why does a product have fewer reviews than I asked for?**
1688 shows visitors without an account only part of a product's reviews, and some products have none. You pay only for the reviews you get.

**Is it legal to scrape 1688?**
The actor collects only publicly visible product information and no personal data. You are responsible for how you use the data and for following the laws and terms that apply to you.

### More 1688 scrapers

The same scraper is also available as focused actors with a short input form:

- [1688 Image Search Scraper](https://apify.com/TheShark/1688-image-search-scraper): find products and suppliers by photo.
- [1688 Search Results Scraper](https://apify.com/TheShark/1688-search-results-scraper): fast, low-cost product cards by keyword, link or category.
- [1688 Product Details Scraper](https://apify.com/TheShark/1688-product-details-scraper): full product pages by link or offer ID.
- [1688 Supplier Scraper](https://apify.com/TheShark/1688-supplier-scraper): supplier profiles and their products.
- [1688 Price Monitor](https://apify.com/TheShark/1688-price-monitor): track prices, stock and sales of your products.

# Actor input Schema

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

Search keywords, Chinese or English, for example 手机壳 or phone case. Each keyword is searched separately.

## `offerIds` (type: `array`):

1688 product IDs or product links (detail.1688.com/offer/<id>.html). These products are scraped first, with full product pages, and then the other sources are processed.

## `searchUrls` (type: `array`):

Links to 1688 search results (s.1688.com/selloffer/offer_search.htm?..., m.1688.com/offer_search/...). The keyword and the filters from the link are used; they win over the filters below. Each link is searched separately.

## `categoryId` (type: `string`):

1688 category ID of level 1 or 2 (for example 1813 for toys, 181309 for a sub-category). With keywords or links it works as a filter; alone it is searched by itself. Leaf categories need a keyword.

## `imageUrls` (type: `array`):

Links to photos to search by: 1688 finds visually similar products. Links on alicdn.com (1688 product images) are used directly; any other image is downloaded, resized and uploaded to 1688 (JPEG, PNG, GIF and WEBP work). Each image is searched separately, up to about 700 products per image. Every row has similarityScore: smaller is closer (for example, below 0.1 is almost the same photo).

## `similarToOfferIds` (type: `array`):

1688 product IDs or links. For each one, the scraper takes its main image and finds visually the same or very close products from other sellers, cheapest first (up to about 700 per offer), then scrapes them as normal products. The offer itself is not included. Every row has similarityScore: smaller is closer. Only products with similarityScore up to 0.2 are kept (about the same photo or the same kind of product); change this with Max similarityScore.

## `maxSimilarityScore` (type: `number`):

Only for 'Find look-alikes of offers'. Products with a higher similarityScore are skipped. Smaller means closer: up to 0.1 is almost the same photo, 0.1-0.2 is the same kind of product, above 0.3 are often different models. Leave empty for the default 0.2, which suits most goods; fashion and other visual categories may need a higher value (for example 0.3).

## `suppliers` (type: `array`):

Get a profile row for each supplier (rowType "supplier"): company name, registration, shop header and ratings, factory card, shop metrics and the IDs of the shop's hot offers. Accepted: a shop link (https://shop....1688.com/ or https://<name>.1688.com/, any page of the shop), m.1688.com/winport/b2b-....html, winport.m.1688.com/...?memberId=b2b-..., a shop ID (b2b-...) or the exact company name. A product link is not a supplier: put it in Offer IDs. One supplier profile found is billed as one supplier event; not found suppliers and errors are free. No contacts (phones, emails, WeChat, QQ, names) are collected. With 'Include supplier intelligence' the paid supplierIntelligence block is added when it has data.

## `maxProductsPerSupplier` (type: `integer`):

How many products to scrape for each supplier. 0 (default) means only the supplier profile. Products come from a search by the exact company name, the factory card list (factories only) and the shop's hot and new offers. This is not the full catalog: 1688 closes it, and about 180-260 products per seller can be found. Each product is scraped as a normal product (full card, billed as a product) and carries the supplier in source. With 'Open product pages' off, products found by the company-name search come as cheaper search cards, but products without a search card (factory card list, hot and new offers) are still scraped from their product page and billed as a product.

## `maxResults` (type: `integer`):

Maximum number of products per keyword, URL, category, photo or look-alike offer. One 1688 request gives about 300 products. Above that, extra requests are made (split by price range and sort order), so the run takes longer and the extra results are less relevant.

## `scrapeProductPages` (type: `boolean`):

On (default): every product is scraped from its own page, with the full set of fields. Off: products found by search are taken straight from the search results, which is much faster and cheaper (billed as the cheaper product-card event). Such rows have only the search-card fields (title, price tiers, image, seller, sales, trade scores). Products given in offerIds always use product pages, and so do supplier products that have no search card (factory card list, hot and new offers): they are billed as a product. Reviews, supplier intelligence and same items are not collected in this mode. A Verified merchant type is then only 1688's own search filter (products are not checked on their pages).

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

How search results are ordered.

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

Only products priced at or above this value, in yuan. Leave empty for no filter.

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

Only products priced at or below this value, in yuan. Leave empty for no filter.

## `minOrderQuantityFrom` (type: `integer`):

Only products whose minimum order quantity (MOQ) is at least this value. Leave empty for no filter.

## `minOrderQuantity` (type: `integer`):

Only products whose minimum order quantity (MOQ) is at most this value. Leave empty for no filter.

## `merchantType` (type: `string`):

Limit results to a type of supplier.

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

Filter by supplier province, in Chinese characters (for example 广东). Several provinces can be separated by commas (for example 江苏,浙江). Optional.

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

Filter by supplier city, in Chinese characters (for example 深圳). Optional.

## `dropshipping` (type: `boolean`):

Only suppliers that ship single items directly to your customer.

## `freeShipping` (type: `boolean`):

Only products with free shipping. Cannot be combined with 'Dropshipping with free shipping'; the first one is used.

## `dropshipFreeShipping` (type: `boolean`):

Only products that ship single items with free shipping.

## `sevenDayReturn` (type: `boolean`):

Only products with a 7-day no-reason return. Cannot be combined with 'Fast invoice'; the first one is used.

## `fastInvoice` (type: `boolean`):

Only suppliers that issue invoices quickly.

## `officialLogistics` (type: `boolean`):

Only products shipped with 1688 official logistics.

## `verifiedFactory` (type: `boolean`):

Only suppliers with a verified factory. Cannot be combined with 'Big brand OEM' or the 'Verified merchant' type; the first one is used.

## `bigBrandOem` (type: `boolean`):

Only suppliers that make products for big brands.

## `excludeKeywords` (type: `array`):

Skip products whose title contains any of these words.

## `includeSkuDetails` (type: `boolean`):

Add the full variant matrix: each variant with its options, price, stock and sales.

## `includeDescriptionHtml` (type: `boolean`):

Add the full product description as HTML. Description text and images are always included.

## `includeReviews` (type: `integer`):

How many latest reviews to attach to each product (0 to 100). 1688 shows anonymous visitors only part of a product's reviews, so some products get fewer. Buyer names, avatars and profiles are never collected. Charged per review delivered.

## `includeSupplierIntelligence` (type: `boolean`):

Add a supplierIntelligence block: factory card for verified factories (videos, rankings, equipment list, production lines, OEM minimums, production capacity, factory address and coordinates), product certificates (including CE/FCC/RoHS), customization (services with prices, printing price list, lead times by quantity), dropshipping metrics and the product's ranking on 1688. Up to 6 extra requests per product. Charged as an extra event only when at least part of this data is found. Always included for free: founding year, company registration with address, supplier profile (staff, area, equipment, verification), shop metrics (stars, quality and fulfilment rates, followers, years on 1688) and the seller chat link.

## `includeSameItems` (type: `boolean`):

Add a sameItems list to each product: up to 8 offers of the same item from other sellers (title, price, sales text, image and link; no seller details). Billed as a same-items event only when the list is not empty. Needs product pages, so it is off when scrapeProductPages is false.

## `monitorName` (type: `string`):

Turn on change monitoring (free). The name of your monitor: the previous state of every product is kept in your account's key-value store china-1688-monitor-<name> (the name is lower-cased; use Latin letters and digits, other characters are dropped and different names made only of them share one store). Every product row gets monitor.status: NEW (not seen before), CHANGED (monitor.changes lists price, stock, sold count, title or status that differ), UNCHANGED, or GONE (a product from offerIds that was OK last time is not found now). The stored state is updated at the end of the run. Leave empty to switch monitoring off. If the store cannot be opened, the run goes on without monitoring and a warning is logged.

## Actor input object example

```json
{
  "maxProductsPerSupplier": 0,
  "maxResults": 100,
  "scrapeProductPages": true,
  "sortBy": "relevance",
  "merchantType": "any",
  "dropshipping": false,
  "freeShipping": false,
  "dropshipFreeShipping": false,
  "sevenDayReturn": false,
  "fastInvoice": false,
  "officialLogistics": false,
  "verifiedFactory": false,
  "bigBrandOem": false,
  "includeSkuDetails": false,
  "includeDescriptionHtml": false,
  "includeReviews": 0,
  "includeSupplierIntelligence": false,
  "includeSameItems": false
}
```

# Actor output Schema

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

Dataset rows: products with prices, MOQ, stock, sales, images, attributes, supplier and shipping, and supplier profile rows. Opens in the Products view; the Search cards, Suppliers and Changes views show cards-only rows, supplier rows and the monitor column.

# 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("theshark/china-1688-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 = {}

# Run the Actor and wait for it to finish
run = client.actor("theshark/china-1688-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 '{}' |
apify call theshark/china-1688-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,theshark/china-1688-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/ds3x4ILP0gAcsJj69/builds/uVd28OZmdyk7yGNHC/openapi.json
