# 1688.com Products Scraper (`codingfrontend/1688-com-products-scraper`) Actor

Extract public 1688.com product results with bulk price tiers, supplier badges, specifications, and demand metrics.

- **URL**: https://apify.com/codingfrontend/1688-com-products-scraper.md
- **Developed by:** [Coding Frontned](https://apify.com/codingfrontend) (community)
- **Stats:** 2 total users, 1 monthly users, 14.3% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.99 / 1,000 results

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

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

## What's an Apify Actor?

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

### What this Actor does

This Actor collects product cards from public search pages on [1688.com](https://www.1688.com/). Search with product keywords or provide one or more 1688 search URLs. Results can include product links, visible prices and bulk price tiers, minimum order quantities (MOQ), supplier details, product images, specifications, and source-labelled demand signals. When product detail collection is enabled, Schema.org Product and Offer data found on matching public product pages can add fields such as product identifiers, availability, reviews, and offer details.

Use the results to compare products and suppliers, research wholesale options, or build a product shortlist. If a page needs JavaScript to display products, the Actor also tries a browser. It does not sign in or solve CAPTCHA pages, so accessible results depend on 1688 and the search you provide.

### How to run it

1. Open the Actor's **Input** tab.
2. Enter keywords in **Product keywords**, or paste one or more public 1688 search URLs. The default search is `wireless earbuds`.
3. Choose whether to collect product detail page data, a product limit, page range, and any filters. The input form is enough; you do not need to write code.
4. Click **Start**.
5. Open **Dataset** to view or download product records. Open **Output summary** for the separate run summary.

### Input

All input fields are optional. If you provide no search URL or keyword, the Actor uses the default `searchQuery` value, `wireless earbuds`. Search URLs take precedence: when at least one valid source URL is supplied, keyword fields do not create additional searches.

#### Search settings

| Field | Type | Required? | Default | What it does |
| --- | --- | --- | --- | --- |
| `searchQuery` | Text | Optional | `wireless earbuds` | One keyword search in Chinese or English, up to 300 characters. |
| `queries` | List of text | Optional | Uses `searchQuery` | Adds up to 100 keyword searches, with up to 300 characters per entry. |
| `sourceUrls` | List of URLs | Optional | Empty list | Searches up to 100 public 1688 search URLs. URL entries must point to 1688 search pages. |
| `maxItems` | Integer | Optional | `100` | Maximum number of products saved across the entire run. Range: 1–1,000. |
| `maxPages` | Integer | Optional | `1` | Maximum pages to visit for each keyword search or URL. Range: 1–20. |
| `startPage` | Integer | Optional | `1` | First page number for each search. Range: 1–1,000. |
| `deduplicate` | Boolean | Optional | `true` | Keep one record per canonical product URL across the run. |
| `sortBy` | Text choice | Optional | `relevance` | Sort the collected results by one of the choices below. Sorting is applied after collection and filtering. |

`queries` and `searchQuery` are combined when both contain values. The input form may prefill `searchQuery`; clear it if you want to use only `queries`. A supplied search URL takes precedence over all keyword searches. Repeated URLs are removed.

Keyword fields are combined and deduplicated, with at most 100 unique queries kept for a run.

| `sortBy` choice | Order |
| --- | --- |
| `relevance` | Keep the order found on the collected pages. |
| `minPrice` | Lowest minimum price first. |
| `maxPrice` | Lowest maximum price first. |
| `title` | Product title alphabetically. |
| `supplierName` | Supplier name alphabetically. |
| `demandMetric` | Lowest visible demand metric first. |

The product limit `maxItems` is shared across all searches. `maxPages` applies separately to each search or URL. Reaching `maxItems` is normal completion and does not make the run partial.

#### Product and supplier filters

Filters are optional and apply after detail collection. When a filter needs a value that is missing from a product record, that product does not pass that filter. With detail collection enabled, up to `maxItems` candidates are selected using the requested sort and their search-page values. Detail information can change those values; the final selected records are filtered and sorted again. Some candidates may fail your filters, so fewer products can be saved. Price values use the currency shown by 1688; the Actor does not convert currencies or combine ranges from different currencies. If both price bounds are set, `minPrice` must be no greater than `maxPrice`.

| Field | Type | Required? | Default | What it does |
| --- | --- | --- | --- | --- |
| `minPrice` | Number | Optional | No lower bound | Keep products whose observed price range reaches this amount or higher. Minimum: 0. |
| `maxPrice` | Number | Optional | No upper bound | Keep products whose observed price range starts at this amount or lower. Minimum: 0. |
| `minOrderQuantity` | Number | Optional | No filter | Keep products whose observed MOQ is at least this amount. Minimum: 0. |
| `minRating` | Number | Optional | No filter | Keep products with an observed rating at or above this value. Minimum: 0. |
| `minSales` | Number | Optional | No filter | Keep products with a visible demand metric at or above this value. Minimum: 0. The metric can represent different activity labels shown by the source. |
| `minSupplierYears` | Number | Optional | No filter | Keep suppliers with an observed operating-year value at or above this number. Minimum: 0. |
| `location` | Text | Optional | No filter | Match part of the supplier location without regard to capitalization. Maximum length: 120 characters. |
| `supplierType` | Text | Optional | No filter | Match the displayed supplier type without regard to capitalization. Maximum length: 80 characters. |
| `factoryOnly` | Boolean | Optional | `false` | Keep products whose visible supplier details identify a factory. |
| `crossBorderOnly` | Boolean | Optional | `false` | Keep products with a visible cross-border signal. |
| `dispatchWithin24h` | Boolean | Optional | `false` | Keep products with a visible 24-hour dispatch signal. |
| `requiredBadges` | List of text | Optional | Empty list | Require every listed badge phrase to appear in the supplier badges. Maximum: 50 entries. |

#### Information to include

| Field | Type | Required? | Default | What it does |
| --- | --- | --- | --- | --- |
| `includeMedia` | Boolean | Optional | `true` | Include product image URLs when they are available. |
| `includeAttributes` | Boolean | Optional | `true` | Include category paths and specifications when available. |
| `includeSupplierDetails` | Boolean | Optional | `true` | Include supplier fields and the nested `supplier` object when available. |
| `includeProductDetails` | Boolean | Optional | `true` | Fetch supported Schema.org Product and Offer fields from matching public pages, for up to `maxItems` selected products. Turn off to use search-page data only. A detail-page failure leaves an already collected product record available. |

#### Input examples

**A small keyword search:**

```json
{
  "searchQuery": "bamboo drawer organizer",
  "maxItems": 20,
  "maxPages": 1
}
```

**Filter and sort a product search:**

```json
{
  "searchQuery": "thermal label printer",
  "minPrice": 1,
  "maxPrice": 20,
  "factoryOnly": true,
  "sortBy": "minPrice",
  "maxItems": 40
}
```

**Search multiple 1688 URLs and deduplicate products:**

```json
{
  "sourceUrls": [
    "https://s.1688.com/selloffer/offer_search.htm?keywords=reusable%20shopping%20bag",
    "https://s.1688.com/selloffer/offer_search.htm?keywords=paper%20gift%20box"
  ],
  "maxPages": 2,
  "maxItems": 50,
  "deduplicate": true
}
```

**Continue from a later page:**

```json
{
  "searchQuery": "stainless steel lunch container",
  "startPage": 2,
  "maxPages": 3,
  "maxItems": 30
}
```

**Use search-page data only and omit optional images, specifications, and supplier details:**

```json
{
  "searchQuery": "recycled cotton tote bag",
  "includeMedia": false,
  "includeAttributes": false,
  "includeSupplierDetails": false,
  "includeProductDetails": false,
  "maxItems": 25
}
```

#### Request settings

Most users can keep these values as they are. Timeouts and delays are in milliseconds.

| Field | Type | Required? | Default | What it does |
| --- | --- | --- | --- | --- |
| `requestTimeoutMs` | Integer | Optional | `30000` ms | Per-request timeout. Range: 5,000–120,000 ms. |
| `requestDelayMs` | Integer | Optional | `500` ms | Pause between page requests and retry attempts. Range: 0–10,000 ms. |
| `maxRequestRetries` | Integer | Optional | `2` | Extra attempts after retryable request failures. Range: 0–5. |
| `maxConcurrency` | Integer | Optional | `1` | Number of independent searches processed at once. Range: 1–4. |
| `maxResponseBytes` | Integer | Optional | `5,000,000` bytes | Reject an HTML response larger than this size. Range: 100,000–20,000,000 bytes. |
| `userAgent` | Text | Optional | Built-in Chrome 131 user agent | Identification for standard requests. With the default value, the browser uses its own identity; a custom value applies to both. Maximum length: 300 characters. |
| `proxyConfiguration` | Object | Optional | `{ "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"], "apifyProxyCountry": "CN" }` | Uses Apify Residential Proxy in China by default. Set `useApifyProxy` to `false` for direct access, or change `apifyProxyGroups` and `apifyProxyCountry` to use another available route. `proxyUrls`, if used, accepts up to 20 valid HTTP or HTTPS proxy URLs. Residential traffic adds charges. |

### Output

Each dataset item is one product record. The schema-required fields are `id`, `title`, and `productUrl`. Other fields are optional and appear only when the source provides them. Product detail fields are collected only when `includeProductDetails` is enabled and the public detail page exposes supported Schema.org data. Missing information is omitted; the Actor does not fill in unavailable numbers, text, or links.

You can download the dataset in various formats such as JSON, HTML, CSV, or Excel.

**Illustrative product record:** The product details and links are illustrative, not a verified live product. The supplier metric labels and scores demonstrate the source-backed field shape and are not tied to this example product.

```json
{
  "id": "1688:123456789",
  "title": "Reusable cotton shopping bag",
  "description": "Reusable cotton bag with reinforced handles.",
  "brand": "Illustrative Bag Brand",
  "sku": "BAG-REC-01",
  "mpn": "RB-38-62",
  "gtin": "06912345678901",
  "availability": "https://schema.org/InStock",
  "itemCondition": "https://schema.org/NewCondition",
  "priceValidUntil": "2026-12-31",
  "productUrl": "https://detail.1688.com/offer/123456789.html",
  "priceTiers": [
    {
      "minQuantity": 50,
      "maxQuantity": 199,
      "price": 3.2,
      "currency": "CNY",
      "unit": "piece"
    },
    {
      "minQuantity": 200,
      "price": 2.5,
      "currency": "CNY",
      "unit": "piece"
    }
  ],
  "minPrice": 2.5,
  "maxPrice": 3.2,
  "currency": "CNY",
  "minOrderQuantity": 50,
  "supplierName": "Illustrative cotton goods supplier",
  "supplierUrl": "https://illustrative-supplier.1688.com/",
  "supplierType": "factory",
  "isFactory": true,
  "supplierBadges": [
    "Factory supplier",
    "Buyer protection"
  ],
  "supplierLocation": "Guangdong",
  "supplierYears": 8,
  "responseRate": 98.5,
  "returnRate": 1.2,
  "repeatBuyerRate": 54,
  "supplierServiceRatings": {
    "采购咨询": 4.5,
    "退换体验": 4.3,
    "品质体验": 4.3,
    "纠纷解决": 5,
    "物流时效": 3.7
  },
  "buyerProtection": true,
  "transactions90d": 420,
  "specifications": {
    "Material": "Recycled cotton",
    "Bag width": "38 cm",
    "Handle length": "62 cm"
  },
  "categoryPath": [
    "Bags",
    "Shopping bags",
    "Reusable bags"
  ],
  "imageUrl": "https://cbu01.alicdn.com/illustrative/cotton-bag-front.jpg",
  "imageUrls": [
    "https://cbu01.alicdn.com/illustrative/cotton-bag-front.jpg",
    "https://cbu01.alicdn.com/illustrative/cotton-bag-detail.jpg"
  ],
  "demandMetric": 3200,
  "demandLabel": "sold 3,200",
  "demand": {
    "salesCount": 3200,
    "label": "sold 3,200",
    "period": "last 90 days"
  },
  "rating": 4.8,
  "reviewCount": 84,
  "ratingCount": 72,
  "bestRating": 5,
  "worstRating": 1,
  "offers": [
    {
      "url": "https://detail.1688.com/offer/123456789.html",
      "price": 3.2,
      "currency": "CNY",
      "availability": "https://schema.org/InStock",
      "itemCondition": "https://schema.org/NewCondition",
      "priceValidUntil": "2026-12-31",
      "sellerName": "Illustrative cotton goods supplier",
      "sellerUrl": "https://illustrative-supplier.1688.com/",
      "minQuantity": 50,
      "maxQuantity": 199,
      "unit": "piece"
    },
    {
      "lowPrice": 2.5,
      "highPrice": 3.2,
      "currency": "CNY",
      "minQuantity": 200,
      "unit": "piece"
    }
  ],
  "crossBorder": true,
  "dispatchWithin24h": true,
  "pricing": {
    "currency": "CNY",
    "unit": "piece",
    "minOrderQuantity": 50,
    "minPrice": 2.5,
    "maxPrice": 3.2,
    "tiers": [
      {
        "minQuantity": 50,
        "maxQuantity": 199,
        "price": 3.2,
        "currency": "CNY",
        "unit": "piece"
      },
      {
        "minQuantity": 200,
        "price": 2.5,
        "currency": "CNY",
        "unit": "piece"
      }
    ]
  },
  "supplier": {
    "name": "Illustrative cotton goods supplier",
    "url": "https://illustrative-supplier.1688.com/",
    "type": "factory",
    "isFactory": true,
    "location": "Guangdong",
    "badges": [
      "Factory supplier",
      "Buyer protection"
    ],
    "years": 8,
    "responseRate": 98.5,
    "returnRate": 1.2,
    "repeatBuyerRate": 54,
    "serviceRatings": {
      "采购咨询": 4.5,
      "退换体验": 4.3,
      "品质体验": 4.3,
      "纠纷解决": 5,
      "物流时效": 3.7
    },
    "buyerProtection": true,
    "transactions90d": 420
  },
  "product": {
    "categoryPath": [
      "Bags",
      "Shopping bags",
      "Reusable bags"
    ],
    "specifications": {
      "Material": "Recycled cotton",
      "Bag width": "38 cm",
      "Handle length": "62 cm"
    },
    "imageUrls": [
      "https://cbu01.alicdn.com/illustrative/cotton-bag-front.jpg",
      "https://cbu01.alicdn.com/illustrative/cotton-bag-detail.jpg"
    ]
  },
  "logistics": {
    "crossBorder": true,
    "dispatchWithin24h": true
  }
}
```

#### Output fields

`MOQ` means minimum order quantity. The top-level fields make common comparisons easier; matching information can also appear in the nested objects. Product identity and offer fields come from the public detail page when the page supplies them. `brand` describes the product brand and is separate from the supplier.

| Field | Type | Required? | Meaning |
| --- | --- | --- | --- |
| `id` | Text | Required | Product identifier. |
| `title` | Text | Required | Product title. |
| `description` | Text | Optional | Product description from the public detail page, when provided. |
| `brand` | Text | Optional | Product brand. This is kept separate from supplier identity. |
| `sku` | Text | Optional | Source-provided stock keeping unit. |
| `mpn` | Text | Optional | Source-provided manufacturer part number. |
| `gtin` | Text | Optional | Source-provided Global Trade Item Number. |
| `availability` | Text | Optional | Availability value supplied for the product. |
| `itemCondition` | Text | Optional | Condition value supplied for the product. |
| `priceValidUntil` | Text | Optional | Price validity date supplied by the source. |
| `productUrl` | URL | Required | Direct product page link. |
| `priceTiers` | List of objects | Optional | Bulk prices. Each tier may contain minimum and maximum quantities, price, currency, and unit. |
| `minPrice` | Number | Optional | Lowest observed price. |
| `maxPrice` | Number | Optional | Highest observed price. |
| `currency` | Text | Optional | Currency code shown with a price, such as `CNY`. |
| `minOrderQuantity` | Number | Optional | Observed MOQ. |
| `supplierName` | Text | Optional | Supplier name. |
| `supplierUrl` | URL | Optional | Supplier page link. |
| `supplierType` | Text | Optional | Supplier type shown on the page. |
| `isFactory` | Boolean | Optional | Whether a factory signal was observed. |
| `supplierBadges` | List of text | Optional | Visible supplier badges. |
| `supplierLocation` | Text | Optional | Supplier location. |
| `supplierYears` | Number | Optional | Supplier years shown on the page. |
| `responseRate` | Number | Optional | Supplier response rate when shown. |
| `returnRate` | Number | Optional | Supplier return or returned-order rate only when the source labels it as such. The 1688 `回头率` measure is a repeat-buyer rate, not a return rate. |
| `repeatBuyerRate` | Number | Optional | Supplier repeat-buyer rate shown by the source label `回头率`, expressed as a percentage. It is separate from returned orders. |
| `supplierServiceRatings` | Object of numbers | Optional | Supplier service scores keyed by the source's visible labels, such as `采购咨询` or `物流时效`. These are supplier scores, not product ratings or reviews. |
| `buyerProtection` | Boolean | Optional | Whether buyer protection was indicated. |
| `transactions90d` | Number | Optional | Supplier transactions over 90 days when shown. |
| `specifications` | Object of text | Optional | Product attributes, such as material or size. |
| `categoryPath` | List of text | Optional | Product category path. |
| `imageUrl` | URL | Optional | First available product image. |
| `imageUrls` | List of URLs | Optional | Available product images. |
| `demandMetric` | Number | Optional | Visible sales or order activity metric used by supported demand filters. Review counts are reported separately. |
| `demandLabel` | Text | Optional | Source label for the demand metric. |
| `demand` | Object | Optional | Source-labelled `salesCount`, `label`, and `period` values when available. |
| `rating` | Number | Optional | Product rating when available. |
| `reviewCount` | Number | Optional | Number of reviews reported by the source. |
| `ratingCount` | Number | Optional | Number of ratings reported by the source. |
| `bestRating` | Number | Optional | Upper bound of the source's rating scale. |
| `worstRating` | Number | Optional | Lower bound of the source's rating scale. |
| `offers` | List of objects | Optional | Product offer data. Each offer may include its URL, price or price range, currency, availability, item condition, validity date, seller, quantity bounds, and unit. |
| `crossBorder` | Boolean | Optional | Whether a cross-border signal was observed. |
| `dispatchWithin24h` | Boolean | Optional | Whether a 24-hour dispatch signal was observed. |
| `pricing` | Object | Optional | `currency`, `unit`, `minOrderQuantity`, `minPrice`, `maxPrice`, and `tiers`. |
| `supplier` | Object | Optional | Supplier name, URL, type, factory signal, location, badges, years, response, return and repeat-buyer rates, service ratings, buyer protection, and 90-day transactions. Its `serviceRatings` map uses the source's visible labels. |
| `product` | Object | Optional | Category path, specifications, and product image URLs. |
| `logistics` | Object | Optional | Cross-border and 24-hour dispatch signals. |

Within `supplier`, `repeatBuyerRate` mirrors the top-level value and `serviceRatings` mirrors `supplierServiceRatings`. The 1688 label `回头率` describes repeat buyers, not returned products or orders. The service score map keeps the source labels as keys; these are supplier service scores, not product ratings, reviews, or rating counts.

Offer objects may contain these source-provided fields:

| Offer field | Type | Meaning |
| --- | --- | --- |
| `url` | URL | Offer link. |
| `price` | Number | Specific offer price. |
| `lowPrice` | Number | Lower price in an aggregate offer. |
| `highPrice` | Number | Upper price in an aggregate offer. |
| `currency` | Text | Currency code supplied with the offer price. |
| `availability` | Text | Offer availability value. |
| `itemCondition` | Text | Offer condition value. |
| `priceValidUntil` | Text | Offer price validity date. |
| `sellerName` | Text | Offer seller name. |
| `sellerUrl` | URL | Offer seller link. |
| `minQuantity` | Number | Minimum quantity for the offer. |
| `maxQuantity` | Number | Maximum quantity for the offer. |
| `unit` | Text | Unit supplied for the offer quantity or price. |

#### Run status

| Status | What it means |
| --- | --- |
| `SUCCEEDED` | At least one validated product record was saved. |
| `SUCCEEDED` with limited results | A collection or write problem stopped part of the run after one or more products were saved. Saved products remain in the dataset. |
| `FAILED` | No real product records were saved. This includes blocked or empty searches and searches where no products pass the filters. |

The completion message reports the saved product count. Reaching the requested `maxItems` limit is normal completion. The run summary is stored separately from product records.

#### Output summary

The **Output summary** link in the Output tab opens `OUTPUT_SUMMARY` from the run's default **Key-value store**. The summary is stored separately from the product dataset and contains only these three fields:

```json
{
  "status": "SUCCEEDED",
  "itemsStored": 25,
  "isPartial": false
}
```

| Field | Type | Required? | Meaning |
| --- | --- | --- | --- |
| `status` | Text | Required | `SUCCEEDED` when at least one real product was saved; otherwise `FAILED`. |
| `itemsStored` | Nonnegative integer | Required | Number of validated product writes that completed during the run. |
| `isPartial` | Boolean | Required | `true` when a failure stopped part of collection after products were saved; otherwise `false`. |

A run with no saved products has `status: "FAILED"`, `itemsStored: 0`, and `isPartial: false`. Error details are written to the run log, not to the summary.

### Tips and access

- A product limit is a maximum, not a promised result count. More pages or fewer filters may return more products when those pages are accessible.
- If a search is blocked or asks for sign-in or verification, check the run log. This Actor does not bypass those access pages.
- Missing prices, supplier details, and attributes are omitted. Filters that need a missing value exclude that product.
- Current pricing is $3.99 per 1,000 dataset records, plus $0.001 per actor start per GB (minimum 1 GB), plus Apify platform usage. Check the Actor's Pricing tab for current prices before running larger searches. More pages, retries, and proxy use can increase resource use.
- For support, use the Actor's Issues tab. Include the run ID and describe the input and problem; do not post credentials or other private values.
- Use public data responsibly and follow 1688's terms and applicable rules. This Actor is not affiliated with or endorsed by 1688.

# Actor input Schema

## `searchQuery` (type: `string`):

Chinese or English keywords used to build a public 1688 search URL when no source URL is supplied.

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

Optional list of independent keyword searches. Combined with searchQuery when it contains a value. Up to 100 entries of at most 300 characters each.

## `sourceUrls` (type: `array`):

Public HTTPS 1688 search-result URLs. Duplicate URLs are removed.

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

Maximum real product records saved to the dataset.

## `startPage` (type: `integer`):

One-based page number used for page-number fallback.

## `maxPages` (type: `integer`):

Bounded sequential page traversal per source.

## `deduplicate` (type: `boolean`):

Deduplicate canonical product URLs across pages and sources.

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

Sorting is applied after bounded collection; relevance keeps source order.

## `minPrice` (type: `number`):

Keep products whose observed price range overlaps this lower bound.

## `maxPrice` (type: `number`):

Keep products whose observed price range overlaps this upper bound.

## `minOrderQuantity` (type: `number`):

Keep products whose observed minimum order quantity is at least this value.

## `minRating` (type: `number`):

Keep products with an observed rating at or above this value.

## `minSales` (type: `number`):

Keep products with an observed demand metric at or above this value.

## `minSupplierYears` (type: `number`):

Keep suppliers with an observed operating-year value at or above this value.

## `location` (type: `string`):

Case-insensitive substring filter on the observed supplier location.

## `supplierType` (type: `string`):

Observed public supplier type, such as factory or trader.

## `factoryOnly` (type: `boolean`):

Keep rows whose observed supplier type or factory flag identifies a factory.

## `crossBorderOnly` (type: `boolean`):

Keep rows with an observed cross-border signal.

## `dispatchWithin24h` (type: `boolean`):

Keep rows with an observed 24-hour dispatch signal.

## `requiredBadges` (type: `array`):

Case-insensitive badge substrings that must all be observed on the supplier card.

## `includeMedia` (type: `boolean`):

Return product-owned image URLs when available.

## `includeAttributes` (type: `boolean`):

Return public product specifications and category paths when available.

## `includeSupplierDetails` (type: `boolean`):

Return public supplier fields when available.

## `includeProductDetails` (type: `boolean`):

Visit the public detail page for selected products and add available Schema.org Product and Offer fields. Detail requests are bounded by maxItems and can be disabled to use search-page data only.

## `requestTimeoutMs` (type: `integer`):

Per-request HTTP timeout, bounded to 5–120 seconds.

## `requestDelayMs` (type: `integer`):

Delay between sequential page requests and bounded retry backoff.

## `maxRequestRetries` (type: `integer`):

Maximum bounded retries for retryable network or source errors.

## `maxConcurrency` (type: `integer`):

Maximum independent sources processed at once; pages within one source remain ordered.

## `maxResponseBytes` (type: `integer`):

Reject oversized HTML responses before parsing.

## `userAgent` (type: `string`):

Honest browser-like user agent for public HTTP requests; no stealth or CAPTCHA bypass is performed.

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

Proxy settings for page and browser requests. The default uses Apify Residential Proxy in China. You can turn it off or choose another group or country. Residential traffic adds charges.

## Actor input object example

```json
{
  "searchQuery": "wireless earbuds",
  "sourceUrls": [],
  "maxItems": 100,
  "startPage": 1,
  "maxPages": 1,
  "deduplicate": true,
  "sortBy": "relevance",
  "factoryOnly": false,
  "crossBorderOnly": false,
  "dispatchWithin24h": false,
  "includeMedia": true,
  "includeAttributes": true,
  "includeSupplierDetails": true,
  "includeProductDetails": true,
  "requestTimeoutMs": 30000,
  "requestDelayMs": 500,
  "maxRequestRetries": 2,
  "maxConcurrency": 1,
  "maxResponseBytes": 5000000,
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "CN"
  }
}
```

# Actor output Schema

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

Product records with observed search-page fields and, when enabled and available, public product detail page data.

## `runSummary` (type: `string`):

Separate key-value store record containing the run status, saved item count, and partial-run flag.

# 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("codingfrontend/1688-com-products-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("codingfrontend/1688-com-products-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 codingfrontend/1688-com-products-scraper --silent --output-dataset

```

## MCP server setup

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