# Alibaba Listings Scraper (`w3crawler/alibaba-listings-scraper`) Actor

The Alibaba Listings Scraper extracts paginated public product results from Alibaba for market research and supplier analysis.

- **URL**: https://apify.com/w3crawler/alibaba-listings-scraper.md
- **Developed by:** [w3crawler](https://apify.com/w3crawler) (community)
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.99 / 1,000 product listings

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 does Alibaba Listings Scraper do?

Alibaba Listings Scraper collects public product cards from Alibaba search, country/category, and showroom pages. It parses the public HTML/JSON-LD contract observed on Alibaba's current listings surface and returns product titles, canonical links, price ranges, MOQ, supplier facts, ratings, review counts, sold/reorder signals, product-scoped media, badges, attributes, and shipping or delivery text when those values are visible.

It supports multiple search sources, observed next-page links, bounded pagination, rich filters, stable sorting, deterministic local fixtures, and standard Apify Proxy routing. It never requires an Alibaba login and does not attempt CAPTCHA solving or access-control bypass.

### How to use it

1. Open the **Input** tab.
2. Enter `searchQuery`, or provide one or more public Alibaba `sourceUrls`.
3. Set `maxPages` and `maxItems` for the amount of data required.
4. Add filters or choose `sortBy` when a focused result set is needed.
5. Start the Actor and open the dataset from the Output tab.

The Actor follows Alibaba's public next-page links such as `/countrysearch/CN/wireless-earbuds_2.html`. If a page does not expose a usable link, it uses a bounded, source-specific fallback URL. Pagination is sequential within each source; independent sources can run up to `maxConcurrency` in parallel.

### Input

All input values are validated before a request starts. Unsafe hosts, credentials, non-HTTPS URLs, unsupported properties, invalid ranges, and unsafe fixture paths are rejected. Values are bounded rather than silently expanded.

#### Search sources and limits

| Input | Type | Default | Meaning |
| --- | --- | --- | --- |
| `searchQuery` | string | `wireless earbuds` | Query used when no source URL is supplied. |
| `queries` | string\[] | `[]` | Additional independent queries. |
| `sourceUrls` | string\[] | generated from `searchQuery` | Public Alibaba search/category/showroom URLs. |
| `startUrls` | string\[] | `[]` | Compatibility alias for `sourceUrls`. |
| `maxPages` | integer 1–100 | `2` | Pages per source. |
| `maxItems` | integer 1–5000 | `100` | Final product rows after filtering, sorting, and deduplication. |
| `deduplicate` | boolean | `true` | Deduplicate canonical product URLs across pages and sources. |

When `sourceUrls` is supplied, it takes precedence over generated query URLs. `queries` is useful for separate product families; the global `maxItems` limit is applied after all sources are collected.

#### Filters and sorting

| Input | Type | Meaning |
| --- | --- | --- |
| `textQuery` | string | Match observed title, supplier, category, badge, or selling-point text. |
| `currency` | 3-letter string | Keep a displayed currency such as `USD`, `INR`, or `EUR`. |
| `supplierCountries` | string\[] | Keep observed supplier country/region codes such as `CN` or `IN`. |
| `minPrice`, `maxPrice` | number | Keep overlapping advertised price ranges. |
| `minOrderQuantity`, `maxOrderQuantity` | number | Keep observed MOQ values in range. |
| `minSupplierRating` | number 0–5 | Minimum displayed rating. |
| `minReviewCount` | integer | Minimum displayed review count. |
| `minSoldCount` | integer | Minimum displayed sold count. |
| `minSupplierYears` | number 0–100 | Minimum displayed Alibaba tenure. |
| `minReorderRatePercent` | number 0–100 | Minimum displayed reorder rate. |
| `requiredBadges` | string\[] | Every value must occur in observed badge labels. |
| `requiredCertifications` | string\[] | Every value must occur in badge, selling-point, or attribute text. |
| `certifiedOnly` | boolean | Keep cards with explicit certified/verified/assessed/Gold Supplier evidence. |
| `sortBy` | enum | `relevance`, `price_asc`, `price_desc`, `supplier_rating_desc`, `review_count_desc`, `sold_count_desc`, `supplier_years_desc`, `moq_asc`, or `title_asc`. |

Unknown optional values are not guessed. A filter requiring a missing value excludes that row, while an unfiltered row keeps the remaining observed fields.

#### Dataset detail controls

| Input | Default | Meaning |
| --- | --- | --- |
| `includeMedia` | `true` | Keep product-scoped Alibaba CDN images, thumbnail, alt text, and count. |
| `includeAttributes` | `true` | Keep observed product specification key-value pairs. |

Image extraction is intentionally strict: only image URLs associated with the product card and hosted on Alibaba's public CDN are retained. Navigation icons, flags, certification icons, unrelated recommendations, and arbitrary third-party image URLs are not promoted to `imageUrl`, `thumbnailUrl`, or `imageUrls`.

#### Developer options

| Input | Default | Range / meaning |
| --- | --- | --- |
| `requestDelayMs` | `1000` | 0–15000 ms before each live request. |
| `maxConcurrency` | `2` | 1–5 independent source crawls; pages inside one source remain ordered. |
| `maxRequestRetries` | `3` | 0–10 transient retries with bounded backoff. Challenges and unsafe redirects are not retried as a bypass. |
| `requestTimeoutSecs` | `60` | 15–300 seconds per request. |
| `maxResponseBytes` | `20000000` | 100000–50000000 byte response safety cap. |
| `proxyConfiguration` | disabled | Standard Apify Proxy object with `useApifyProxy`, optional `apifyProxyGroups`, and optional `apifyProxyCountry`. |
| `userAgent` | actor default | Optional transparent browser-like User-Agent. |
| `locale` | `en-US` | Accept-Language locale. |

Proxy routing changes the network route only. It does not solve CAPTCHAs or bypass Alibaba access controls.

#### Local validation fixtures

The local parser tests load inline and Actor-relative HTML fixtures directly. Ordered fixtures cover page 1, later pages, and multi-source parsing without network access; public Actor inputs do not expose fixture overrides.

Example input:

```json
{
  "searchQuery": "wireless earbuds",
  "sourceUrls": [
    "https://www.alibaba.com/countrysearch/CN/wireless-earbuds.html"
  ],
  "maxPages": 3,
  "maxItems": 50,
  "minPrice": 5,
  "maxPrice": 100,
  "minSupplierRating": 4.5,
  "requiredBadges": ["certified"],
  "sortBy": "price_asc",
  "includeMedia": true,
  "requestDelayMs": 750,
  "maxConcurrency": 1,
  "maxRequestRetries": 2,
  "requestTimeoutSecs": 45,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyCountry": "US"
  }
}
```

Fixture pagination example:

```json
{
  "sourceUrls": [
    "https://www.alibaba.com/countrysearch/CN/wireless-earbuds.html"
  ],
  "maxPages": 2,
  "maxItems": 100,
  "sortBy": "supplier_rating_desc",
  "requestDelayMs": 0
}
```

### Dataset output

Normal dataset rows contain only real public product facts and provenance. They do not contain `fieldCoverage`, `dataQuality`, `httpStatus`, `record`, `recordId`, `recordType`, or run-debug wrapper fields.

Example product row:

```json
{
  "title": "Acme ANC Earbuds",
  "productId": "160000000001",
  "productUrl": "https://www.alibaba.com/product-detail/Acme-Earbuds_160000000001.html",
  "url": "https://www.alibaba.com/product-detail/Acme-Earbuds_160000000001.html",
  "priceMin": 12.5,
  "priceMax": 18,
  "currency": "USD",
  "priceText": "$12.50 - $18.00",
  "priceFormatted": "$12.50 - $18.00",
  "minOrderQuantity": 10,
  "minOrderUnit": "pieces",
  "moqText": "MOQ: 10 pieces",
  "supplierName": "Acme Audio Co., Ltd.",
  "supplierProfileUrl": "https://acme-audio.en.alibaba.com/",
  "supplierCountry": "CN",
  "supplierYears": 8,
  "supplierYearsText": "8 yrs",
  "supplierRating": 4.8,
  "reviewCount": 71,
  "reorderRatePercent": 22,
  "reorderRateText": "Reorder rate 22%",
  "imageUrl": "https://s.alicdn.com/@sc04/kf/acme-1.jpg_300x300.jpg",
  "imageUrls": ["https://s.alicdn.com/@sc04/kf/acme-1.jpg_300x300.jpg"],
  "thumbnailUrl": "https://s.alicdn.com/@sc04/kf/acme-1.jpg_300x300.jpg",
  "imageCount": 1,
  "imageAlt": "Acme ANC Earbuds - Product Image 1",
  "badges": ["5% off", "certified"],
  "promotions": ["5% off", "Delivery by 10 Oct", "Reorder rate 22%"],
  "sellingPoints": ["5% off", "Delivery by 10 Oct", "Reorder rate 22%", "certified"],
  "attributes": {},
  "shippingInfo": "Delivery by 10 Oct",
  "leadTime": "Delivery by 10 Oct",
  "deliveryEstimate": "Delivery by 10 Oct",
  "discount": "5% off",
  "category": "Wireless earbuds",
  "isAd": false,
  "isCertified": true,
  "canAddToCart": false,
  "canChatNow": true,
  "sourceType": "alibaba_product_search",
  "sourceUrl": "https://www.alibaba.com/countrysearch/CN/wireless-earbuds.html",
  "pageUrl": "https://www.alibaba.com/countrysearch/CN/wireless-earbuds.html",
  "pageNum": 1,
  "position": 1,
  "query": "wireless earbuds",
  "pageTitle": "Wireless Earbuds China Trade - Alibaba.com",
  "scrapedAt": "2026-09-06T00:00:00.000Z"
}
```

The `url` alias always equals the canonical `productUrl`; tracking query parameters and hashes are removed. Optional values are omitted when Alibaba does not expose them. When `includeMedia` or `includeAttributes` is false, the corresponding fields are omitted.

The dataset contains only source-backed product listing records. Run metrics and operational issue counts are written to `OUTPUT_SUMMARY`; per-source page metadata is written to `SOURCE_METADATA`, and failure details stay in the run logs. A valid search with no matching products completes with `status: SUCCEEDED` and `dataStatus: NO_RESULTS`; a request/input failure before any product row fails the run. If rows were saved before a later request or optional-output failure, the run completes as `SUCCEEDED` with `dataStatus: PARTIAL` and keeps those rows.

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

### Output fields

| Field | Meaning |
| --- | --- |
| `title`, `productId`, `productUrl`, `url` | Product identity and canonical public link. |
| `priceMin`, `priceMax`, `currency`, `priceText`, `priceFormatted` | Observed advertised price range and display text. |
| `minOrderQuantity`, `minOrderUnit`, `moqText` | Public minimum-order information. |
| `supplierName`, `supplierProfileUrl`, `supplierCountry`, `supplierYears`, `supplierYearsText` | Supplier identity and public tenure facts. `supplierProfileUrl` is omitted when no supplier/company profile link was observed; the source search URL is never used as a fallback. |
| `supplierRating`, `reviewCount` | Public rating and review count shown on the card. |
| `soldCount`, `transactionCount`, `soldText`, `reorderRatePercent`, `reorderRateText` | Public sales and reorder signals when shown. |
| `imageUrl`, `imageUrls`, `thumbnailUrl`, `imageCount`, `imageAlt` | Product-scoped public Alibaba CDN media only. |
| `badges`, `promotions`, `sellingPoints`, `attributes` | Public card labels and structured specifications. |
| `shippingInfo`, `leadTime`, `deliveryEstimate`, `discount`, `category` | Visible delivery, shipping, promotion, and category text. |
| `isAd`, `isCertified`, `canAddToCart`, `canChatNow` | Card capabilities or explicit public status signals. |
| `sourceType`, `sourceUrl`, `pageUrl`, `pageNum`, `position`, `query`, `pageTitle` | Useful source provenance, not run-debug metadata. |
| `scrapedAt` | UTC emission timestamp. |

### Pricing and cost estimation

Apify charges for compute, network usage, and storage consumed by a run. Keep `maxPages`, `maxItems`, and `maxConcurrency` close to the amount of data needed. Small exploratory runs are usually the most economical; review your current Apify pricing and usage limits before scheduling large collections.

### Access, reliability, and troubleshooting

Alibaba can return an AWSC or other anti-automation challenge instead of product markup. The Actor fails closed and records `ACCESS_BOUNDARY` in operational metadata; it does not solve the challenge. Transient request failures use the configured bounded retry count. Non-HTML responses, oversized responses, and unsafe redirects are reported outside the dataset.

If a run returns no rows, inspect `OUTPUT_SUMMARY` and the run logs, then try a focused public country/category URL or use a respectful `requestDelayMs`. A page can be valid while optional fields remain absent because Alibaba rendered them only client-side or changed the visible card.

### Legal and support

Collect only public pages and follow Alibaba's terms, robots policy, and applicable privacy laws. This Actor does not bypass login, paywalls, CAPTCHA, or access controls. For a reproducible issue, include the public source URL, input JSON, and relevant diagnostic code in the Issues tab.

Run summaries include the required `status`, `runStatus`, and `dataStatus` fields. `status` and `runStatus` are `SUCCEEDED` when source-backed rows were saved or a run completed cleanly with no matches; they are `FAILED` only when a real failure occurs before any rows are saved. `dataStatus` is `COMPLETE`, `PARTIAL`, `NO_RESULTS`, or `FAILED`. Failure details stay in the run logs; key-value summaries retain counts only.

# Actor input Schema

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

Product keywords used to build a public Alibaba search URL when no source URLs are supplied.

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

Additional product queries. Each query becomes an independent public source and can be paginated.

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

One or more public Alibaba search, category, or showroom URLs. When supplied, these take precedence over generated queries.

## `startUrls` (type: `array`):

Compatibility alias for sourceUrls.

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

Maximum number of linked public result pages to request for each source. The Actor follows Alibaba's observed next-page links and uses a safe URL fallback when needed.

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

Maximum product rows emitted after global filtering, deduplication, and sorting.

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

Stable result ordering applied after all source pages are collected.

## `textQuery` (type: `string`):

Keep rows whose observed title, supplier, category, badge, or selling-point text contains this value.

## `currency` (type: `string`):

Keep only rows with this observed three-letter currency code, such as USD, INR, EUR, or CNY.

## `supplierCountries` (type: `array`):

Keep rows whose observed supplier country/region code matches one of these values, for example CN or IN.

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

Keep a price range when its advertised upper bound reaches this value.

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

Keep a price range when its advertised lower bound is at or below this value.

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

Keep listings with an observed minimum order quantity at or above this value.

## `maxOrderQuantity` (type: `number`):

Keep listings with an observed minimum order quantity at or below this value.

## `minSupplierRating` (type: `number`):

Keep listings with a displayed supplier/product rating at or above this five-point value.

## `minReviewCount` (type: `integer`):

Keep listings with at least this displayed review count.

## `minSoldCount` (type: `integer`):

Keep listings with at least this publicly displayed sold count.

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

Keep listings from suppliers with at least this observed number of years on Alibaba.

## `minReorderRatePercent` (type: `number`):

Keep listings with a displayed reorder rate at or above this percentage.

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

Keep rows whose observed badge labels contain every listed value, for example certified or 5% off.

## `requiredCertifications` (type: `array`):

Keep rows whose observed badge, selling-point, or attribute text contains every listed certification.

## `certifiedOnly` (type: `boolean`):

Keep only cards with explicit certified, verified, assessed, or Gold Supplier evidence.

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

Suppress the same canonical product URL across pages and sources.

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

Include only product-scoped public Alibaba CDN imageUrl, thumbnailUrl, imageUrls, imageAlt, and imageCount fields.

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

Include observed product specification key-value attributes when the public card exposes them.

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

Delay before each live public request. Use a respectful value and follow Alibaba's terms and robots policy.

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

Maximum number of independent source crawls running concurrently. Pagination within each source stays ordered.

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

Retries for transient network failures. Access challenges and unsafe redirects are fail-closed and are not bypassed.

## `requestTimeoutSecs` (type: `integer`):

Timeout for one public page request.

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

Safety cap for a downloaded HTML response.

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

Optional standard Apify Proxy routing for public requests. Proxying changes the route only; it does not solve CAPTCHA or bypass access controls.

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

Optional transparent browser-like User-Agent for public requests.

## `locale` (type: `string`):

Locale sent in Accept-Language, such as en-US or en-GB.

## Actor input object example

```json
{
  "searchQuery": "wireless earbuds",
  "sourceUrls": [
    "https://www.alibaba.com/trade/search?SearchText=wireless%20earbuds"
  ],
  "maxPages": 2,
  "maxItems": 100,
  "sortBy": "relevance",
  "certifiedOnly": false,
  "deduplicate": true,
  "includeMedia": true,
  "includeAttributes": true,
  "requestDelayMs": 1000,
  "maxConcurrency": 2,
  "maxRequestRetries": 3,
  "requestTimeoutSecs": 60,
  "maxResponseBytes": 20000000,
  "locale": "en-US"
}
```

# Actor output Schema

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

No description

## `summary` (type: `string`):

No description

## `sourceMetadata` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

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

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("w3crawler/alibaba-listings-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("w3crawler/alibaba-listings-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 w3crawler/alibaba-listings-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,w3crawler/alibaba-listings-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/wADl6Dl8Sj4rVrzjV/builds/qtlybQB34tOiU7hHh/openapi.json