# AliExpress Bulk Scraper Pro (`codingfrontend/aliexpress-bulk-scraper-pro`) Actor

Collect public AliExpress product details from keyword searches or public item URLs, with product records in the dataset and a separate run summary.

- **URL**: https://apify.com/codingfrontend/aliexpress-bulk-scraper-pro.md
- **Developed by:** [Coding Frontned](https://apify.com/codingfrontend) (community)
- **Stats:** 2 total users, 1 monthly users, 13.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 does AliExpress Bulk Scraper Pro do?

AliExpress Bulk Scraper Pro collects public product information from AliExpress search pages and item links. Search for products, provide item URLs directly, or use both sources in one run. The Actor reads standard Product structured data (JSON-LD) and saves a product only when that data includes a matching public item URL, numeric product ID, and name.

Current live AliExpress fields have not been verified. The supported field mapping follows standard Product structured data and has not been confirmed against current live AliExpress pages. A page may omit some or all optional product fields. If it does not publish a matching product record, the Actor may save no row.

The Actor only reads public pages. It does not sign in, use private APIs, or try to get around CAPTCHA challenges or other access controls.

### Why use this Actor?

- Search with up to 50 phrases or inspect up to 100 public item URLs.
- Combine searches and direct URLs under one limit of 1–100 unique products. Direct URLs are processed first, and repeated product IDs are saved once.
- Collect product facts that the matching Product data publishes, such as offers, seller names, ratings, categories, attributes, and images.
- Use Apify schedules, API access, integrations, run history, and monitoring in your product research workflow.

The Actor does not fill gaps from nearby products or infer missing prices, ratings, or descriptions. It does not add the search phrase to product rows, so a row does not say which phrase found it.

### How to scrape AliExpress

1. Open AliExpress Bulk Scraper Pro in Apify Console and select **Input**.
2. Enter search phrases, public product URLs, or both. If both source lists are empty, the Actor searches for `wireless earbuds`.
3. Set the maximum number of unique products. Direct item URLs are processed before search phrases.
4. Start the run. Product rows appear in **Dataset**; the run outcome appears in the key-value store as `OUTPUT_SUMMARY`.

The Actor reads one search page for each phrase. It does not provide page numbers, sorting, product filters, or a field for search-phrase attribution. Search and item pages must publish matching Product structured data for a row to be saved.

### Input

See the **Input** tab for the configuration. The schema defaults `queries` and `productUrls` to empty lists. The form may show `wireless earbuds` as a starting value for `queries`; that is a form prefill. At runtime, if both lists are empty, the Actor searches for `wireless earbuds`. Supplying direct URLs with an empty `queries` list runs only those URLs.

| Field | Required? | Type | Default | Limits and behavior |
| --- | --- | --- | --- | --- |
| `queries` | Optional | Array of strings | `[]` | Up to 50 phrases, each 1–200 characters. Phrases are converted to AliExpress search-page URLs. |
| `productUrls` | Optional | Array of objects | `[]` | Up to 100 direct product URLs. Each object contains one `url` field. |
| `productUrls[].url` | Required in each item | URL string | — | HTTPS item page on an approved AliExpress host, with an 8–30 digit ID. Query parameters, fragments, credentials, ports, and other paths are rejected. |
| `itemLimit` | Optional | Integer | `10` | 1–100 unique products across all sources. Duplicate item IDs count once. |
| `timeoutMs` | Optional | Integer | `30000` | 5,000–120,000 milliseconds for each search page, item page, or robots request. |
| `maxResponseBytes` | Optional | Integer | `5000000` | 1,000–15,000,000 bytes per response. |
| `useBrowser` | Optional | Boolean | `false` | Uses ordinary browser rendering when enabled. It does not sign in or bypass access controls. |
| `proxyConfiguration` | Optional | Object | `{ "useApifyProxy": false }` | Optional Apify Proxy settings. Proxy use is off by default and depends on your account access. |
| `proxyConfiguration.useApifyProxy` | Optional within the object | Boolean | `false` | Turns Apify Proxy use on or off. |
| `proxyConfiguration.apifyProxyGroups` | Optional within the object | Array of strings | — | Proxy groups available to your Apify account. |
| `proxyConfiguration.proxyUrls` | Optional within the object | Array of strings | — | Proxy URLs accepted by Apify Proxy configuration. |

Unknown fields and invalid values fail input validation. You can start from the checked-in [`input.json`](./input.json) example.

#### Search the default product type

```json
{
  "queries": ["wireless earbuds"],
  "productUrls": [],
  "itemLimit": 10,
  "timeoutMs": 30000,
  "maxResponseBytes": 5000000,
  "useBrowser": false,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

#### Inspect item pages directly

```json
{
  "queries": [],
  "productUrls": [
    { "url": "https://www.aliexpress.com/item/1005001234567890.html" },
    { "url": "https://www.aliexpress.com/item/1005009876543210.html" }
  ],
  "itemLimit": 10
}
```

#### Combine searches and item pages

```json
{
  "queries": ["wireless earbuds", "usb hub"],
  "productUrls": [
    { "url": "https://www.aliexpress.com/item/1005001234567890.html" }
  ],
  "itemLimit": 20,
  "timeoutMs": 45000
}
```

#### Use browser rendering with Apify Proxy

This example enables ordinary browser rendering and Apify Proxy. Proxy access depends on your account and may incur separate charges. It does not bypass access controls.

```json
{
  "queries": ["wireless earbuds"],
  "productUrls": [],
  "itemLimit": 10,
  "timeoutMs": 45000,
  "maxResponseBytes": 5000000,
  "useBrowser": true,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

### Output

Each dataset row contains only product fields. `productId`, `title`, and `productUrl` are required; the remaining fields are optional and appear only when matching Product data publishes a usable value. The table describes all 28 fields in a row.

| Field | Required? | Type | Meaning |
| --- | --- | --- | --- |
| `productId` | Required | String | Native 8–30 digit AliExpress item ID, matched to the product URL. |
| `title` | Required | String | Product name in the matching Product data. |
| `productUrl` | Required | URL string | Public AliExpress item page whose ID matches `productId`. |
| `description` | Optional | String | Description published by the matching Product. |
| `salePrice` | Optional | String | Price from a matching Product offer that publishes a price. |
| `priceCurrency` | Optional | String | Three-letter uppercase currency published with `salePrice`. |
| `offers` | Optional | Array of objects | Up to 20 offers with the explicit details listed in the nested fields table below. |
| `aggregateOffer` | Optional | Object | Published low and high prices, currency, offer count, and nested offers. |
| `brand` | Optional | Object | Brand name published by the product. |
| `manufacturer` | Optional | Object | Manufacturer name published by the product. |
| `model` | Optional | String | Product model text. |
| `gtin` | Optional | String | 8-, 12-, 13-, or 14-digit trade item number. |
| `gtin8` | Optional | String | 8-digit trade item number. |
| `gtin12` | Optional | String | 12-digit trade item number. |
| `gtin13` | Optional | String | 13-digit trade item number. |
| `gtin14` | Optional | String | 14-digit trade item number. |
| `mpn` | Optional | String | Manufacturer part number. |
| `skuId` | Optional | String | Stock keeping unit. |
| `color` | Optional | String | Product color. |
| `material` | Optional | String | Product material. |
| `size` | Optional | String or object | A size value or a size specification with optional units and size system. |
| `additionalProperties` | Optional | Array of objects | Up to 100 named product attributes with a scalar value and optional units. |
| `aggregateRating` | Optional | Object | Published rating value, best and worst ratings, rating count, and review count. |
| `starRating` | Optional | Number | Convenience value copied from `aggregateRating.ratingValue` only when it is on a 0–5 scale. |
| `reviewCount` | Optional | Integer | Convenience value copied from `aggregateRating.reviewCount`; it is not copied from `ratingCount`. |
| `productType` | Optional | String | Product category. |
| `mainImageUrl` | Optional | URL string | First valid image published by the product. |
| `imageUrls` | Optional | Array of URL strings | Up to 50 distinct valid product images. |

Nested fields are also included only when the matching Product data publishes a usable value. Required values below are required only when their containing object or list item is present.

| Path | Type | Required? | Meaning |
| --- | --- | --- | --- |
| `offers[]` | Object | Each list item | One explicit Product offer; its properties below are optional. |
| `offers[].price` | String | Optional | Offer price. |
| `offers[].priceCurrency` | String | Optional | Three-letter uppercase currency code. |
| `offers[].availability` | String | Optional | Published availability such as `InStock` or `OutOfStock`. |
| `offers[].itemCondition` | String | Optional | Published condition such as `NewCondition` or `UsedCondition`. |
| `offers[].seller` | Object | Optional | Seller object. |
| `offers[].seller.name` | String | Required in object | Published seller name. |
| `offers[].url` | URL string | Optional | Public item URL for the same product ID. |
| `aggregateOffer.lowPrice` | String | Optional | Published low price. |
| `aggregateOffer.highPrice` | String | Optional | Published high price. |
| `aggregateOffer.priceCurrency` | String | Optional | Three-letter uppercase currency code. |
| `aggregateOffer.offerCount` | Integer | Optional | Published number of offers. |
| `aggregateOffer.offers[]` | Object | Each list item | One nested offer; its properties follow the same rules as `offers[]`. |
| `aggregateOffer.offers[].price` | String | Optional | Nested offer price. |
| `aggregateOffer.offers[].priceCurrency` | String | Optional | Three-letter uppercase currency code. |
| `aggregateOffer.offers[].availability` | String | Optional | Published availability. |
| `aggregateOffer.offers[].itemCondition` | String | Optional | Published item condition. |
| `aggregateOffer.offers[].seller` | Object | Optional | Nested seller object. |
| `aggregateOffer.offers[].seller.name` | String | Required in object | Published seller name. |
| `aggregateOffer.offers[].url` | URL string | Optional | Public item URL for the same product ID. |
| `brand.name` | String | Required in object | Published brand name. |
| `manufacturer.name` | String | Required in object | Published manufacturer name. |
| `size.name` | String | Optional | Name of the size specification. |
| `size.value` | String, number, or Boolean | Optional | Size value. |
| `size.unitText` | String | Optional | Unit text for the size value. |
| `size.unitCode` | String | Optional | Unit code for the size value. |
| `size.sizeSystem` | String | Optional | Published size system. |
| `size.sizeGroup` | String | Optional | Published size group. |
| `additionalProperties[]` | Object | Each list item | One named product attribute. |
| `additionalProperties[].name` | String | Required in item | Attribute name. |
| `additionalProperties[].value` | String, number, or Boolean | Required in item | Attribute value. |
| `additionalProperties[].unitText` | String | Optional | Unit text for the attribute value. |
| `additionalProperties[].unitCode` | String | Optional | Unit code for the attribute value. |
| `aggregateRating.ratingValue` | Number | Optional | Published rating value. |
| `aggregateRating.bestRating` | Number | Optional | Published upper end of the rating scale. |
| `aggregateRating.worstRating` | Number | Optional | Published lower end of the rating scale. |
| `aggregateRating.ratingCount` | Integer | Optional | Number of ratings. |
| `aggregateRating.reviewCount` | Integer | Optional | Number of reviews. |

This field mapping follows standard Product structured data. AliExpress may omit some or all of these fields, and the current site payload has not been verified. The Actor does not use generic page text or nearby products to fill missing product facts. Product images are limited to AliExpress hosts and `alicdn.com` image hosts with recognized image file extensions.

The JSON below shows every supported top-level field and every nested field. Values illustrate the format; they are not a live AliExpress result.

```json
{
  "productId": "1005001234567890",
  "title": "Protective Phone Case",
  "productUrl": "https://www.aliexpress.com/item/1005001234567890.html",
  "description": "Protective case with a slim finish.",
  "salePrice": "4.90",
  "priceCurrency": "USD",
  "offers": [
    {
      "price": "4.90",
      "priceCurrency": "USD",
      "availability": "InStock",
      "itemCondition": "NewCondition",
      "seller": { "name": "Example Seller" },
      "url": "https://www.aliexpress.com/item/1005001234567890.html"
    }
  ],
  "aggregateOffer": {
    "lowPrice": "4.90",
    "highPrice": "7.90",
    "priceCurrency": "USD",
    "offerCount": 2,
    "offers": [
      {
        "price": "4.90",
        "priceCurrency": "USD",
        "availability": "InStock",
        "itemCondition": "NewCondition",
        "seller": { "name": "Example Seller" },
        "url": "https://www.aliexpress.com/item/1005001234567890.html"
      }
    ]
  },
  "brand": { "name": "Example Brand" },
  "manufacturer": { "name": "Example Manufacturer" },
  "model": "PC-01",
  "gtin": "0123456789012",
  "gtin8": "12345670",
  "gtin12": "012345678905",
  "gtin13": "0123456789012",
  "gtin14": "01234567890128",
  "mpn": "PC-01",
  "skuId": "CASE-01",
  "color": "Black",
  "material": "Polycarbonate",
  "size": {
    "name": "Case width",
    "value": 20,
    "unitText": "centimeters",
    "unitCode": "CMT",
    "sizeSystem": "EU",
    "sizeGroup": "Adult"
  },
  "additionalProperties": [
    {
      "name": "Compatible models",
      "value": "Selected phone models",
      "unitText": "models",
      "unitCode": "C62"
    }
  ],
  "aggregateRating": {
    "ratingValue": 4.8,
    "bestRating": 5,
    "worstRating": 1,
    "ratingCount": 125,
    "reviewCount": 120
  },
  "starRating": 4.8,
  "reviewCount": 120,
  "productType": "Phone cases",
  "mainImageUrl": "https://ae01.alicdn.com/kf/product-image.jpg",
  "imageUrls": ["https://ae01.alicdn.com/kf/product-image.jpg"]
}
```

Download the dataset in formats such as JSON, HTML, CSV, or Excel.

### Run status

`OUTPUT_SUMMARY` is saved in the key-value store separately from product rows. It contains `status`, `itemsStored`, and `isPartial`.
The examples below show the summary format; they are not results from a live AliExpress run.

#### Completed with results

At least one row was saved and collection completed without an early stop.

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

#### Stopped early after saving results

At least one row was saved, then collection or storage stopped early.

```json
{
  "status": "SUCCEEDED",
  "itemsStored": 3,
  "isPartial": true
}
```

#### No rows saved

No valid product row was saved. The source may not have published matching product data, or public access may not have been available.

```json
{
  "status": "FAILED",
  "itemsStored": 0,
  "isPartial": false
}
```

Reaching `itemLimit` is normal completion. `isPartial` is used only when at least one row was saved before an early stop.

### How much will it cost to scrape AliExpress?

Apify usage follows the current pricing shown in your account; this README does not quote a fixed price. Larger product limits, browser rendering, longer request timeouts, and larger response limits can increase run time or compute use. Optional Apify Proxy access may have separate account pricing and is off by default.

Start with a low `itemLimit` to see what current public pages provide. A direct item page uses a request for that page. Search results may also be followed by item-page requests, subject to public access and the page's robots rules.

### Tips, support, and responsible use

- Start with a small item limit. Raise it only after checking what current public pages return.
- Follow AliExpress terms, robots rules, rate limits, and applicable law. The Actor stops when a source denies or challenges public access.
- The Actor is not affiliated with AliExpress. It reads public product information and does not request buyer or seller account data.
- Use the Actor's **Issues** tab for bugs or feature requests. Include a run ID and a short description, and leave out credentials or private account details.
- Use the **API** tab for programmatic runs and integrations.

Public listings can still contain personal data. Do not collect or use personal data unless you have a legitimate reason and follow applicable privacy laws. Consult qualified legal counsel if you are unsure.

# Actor input Schema

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

Search phrases used to build public AliExpress product search pages. Supply up to 50 phrases; an empty list uses the default search only when productUrls is also empty.

## `itemLimit` (type: `integer`):

Maximum number of unique product records across all direct item URLs and search phrases.

## `productUrls` (type: `array`):

Public AliExpress item pages to inspect directly. Provide up to 100 HTTPS item URLs on an approved AliExpress host, without query parameters or fragments. These are processed before searches and share the overall item limit.

## `timeoutMs` (type: `integer`):

Maximum time for each public search page, item page, or robots.txt request.

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

Maximum response body size accepted for each public request.

## `useBrowser` (type: `boolean`):

Render public pages with a standard browser when enabled. It does not log in, solve CAPTCHA challenges, or bypass access controls.

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

Optional account-enabled Apify Proxy settings for public requests. Proxy use is off by default and depends on your account access.

## Actor input object example

```json
{
  "queries": [
    "wireless earbuds"
  ],
  "itemLimit": 10,
  "productUrls": [],
  "timeoutMs": 30000,
  "maxResponseBytes": 5000000,
  "useBrowser": false,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

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

Validated public product records saved to the run's default dataset.

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

Run status, saved product count, and whether collection ended early.

# API

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

## JavaScript example

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

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

// Prepare Actor input
const input = {
    "queries": [
        "wireless earbuds"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("codingfrontend/aliexpress-bulk-scraper-pro").call(input);

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

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

```

## Python example

```python
from apify_client import ApifyClient

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

# Prepare the Actor input
run_input = { "queries": ["wireless earbuds"] }

# Run the Actor and wait for it to finish
run = client.actor("codingfrontend/aliexpress-bulk-scraper-pro").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "queries": [
    "wireless earbuds"
  ]
}' |
apify call codingfrontend/aliexpress-bulk-scraper-pro --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,codingfrontend/aliexpress-bulk-scraper-pro"
        }
    }
}
```

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/olzzuHvCbBpVSjXJc/builds/YTx5TKNzpQCu0ceMR/openapi.json