# Aliexpress Scraper (`ayen-data/aliexpress-scraper`) Actor

Scrape AliExpress products by category, search, or URL into import-ready records — variants with per-SKU prices, stock and images, localized shipping, full image gallery, description and specifications. Choose your country, currency and language.

- **URL**: https://apify.com/ayen-data/aliexpress-scraper.md
- **Developed by:** [Anyx Solutions](https://apify.com/ayen-data) (community)
- **Categories:** E-commerce, Automation, Developer tools
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.29 / 1,000 results

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

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## AliExpress Product Scraper

![banner](https://i.ibb.co/MkFk35VS/Screenshot-2026-07-28-at-11-27-45-AM.png)

Scrape **AliExpress products** by category, search, or product URL and get clean,
**import-ready data** for every item — title, all variants with their own prices,
stock and images, localized shipping, the full image gallery, description and
product specifications.

Pick your **country, currency and language**, point the scraper at a category (or
a list of products), and export everything to **JSON, CSV or Excel** in one run.
Perfect for dropshipping, building or updating a product catalog, price and stock
monitoring, and market research.

***

### What you can extract

For every product, the scraper returns:

- **Title** in your chosen language
- **Product ID** and **category ID** (with the full category path)
- **All variants (SKUs)** — each with its own **sale price**, **original price**,
  **stock**, availability, option values (e.g. colour, size) and **variant image**
- **Localized shipping** — cost, currency, destination country and estimated
  delivery time
- **Full image gallery**
- **Product description**
- **Specifications / attributes** (e.g. material, brand, model)
- **Rating**, **number of reviews** and **units sold**
- **Store / seller** name and link

Because every variant carries its own price, stock and image, the output drops
straight into a product-import workflow — you don't have to gather variants,
prices or shipping separately.

***

### Common use cases

- **Dropshipping** — pull a whole category into your store with variants, images
  and prices already structured for import.
- **Catalog building & updates** — keep titles, prices, stock and images in sync.
- **Price & stock monitoring** — schedule runs and track how prices change.
- **Market & product research** — filter by rating, reviews and units sold to
  find winning products.

***

### How to use the AliExpress Product Scraper

1. **Choose what to scrape.** Enter one or more **Category IDs** (e.g. `1511`), or
   paste **Category / search URLs**. To scrape only specific items, use **Product
   URLs** or **Product IDs** instead.
2. **Set your market.** Choose the **Ship-to country**, **Currency** and
   **Language** so prices, shipping and titles match the market you sell to.
3. **Set how many products** you want per source with **Max products per source**.
4. **Add a proxy.** Leave **Proxy** on Residential and set the proxy country to the
   same country as your Ship-to country (see [Proxy](#proxy) below).
5. **(Optional) Add filters** — minimum rating, reviews or units sold — and a
   **skip list** for products you've already imported.
6. **Run the scraper**, then open the **Storage / Dataset** tab and **export** as
   JSON, CSV or Excel.

> **Tip:** the results table in the app shows a summary. The complete details —
> all variants, the full gallery, description and specifications — are always in
> the **exported file** (JSON keeps the richest structure).

***

### Input

#### What to scrape (fill in at least one)

| Input | Description |
|-------|-------------|
| **Category IDs** | AliExpress category IDs, e.g. `1511`. Found in a category page URL like `aliexpress.com/category/1511/...`. Each category is paged through up to your product limit. |
| **Category / search URLs** | Full category or search-result page URLs, as an alternative to IDs. |
| **Product URLs** | Scrape only these exact products, by page URL. Skips category browsing. |
| **Product IDs** | Scrape only these exact products, by numeric ID. |

#### How many products

| Input | Default | Description |
|-------|---------|-------------|
| **Max products per source** | 100 | Maximum products scraped from each category or search source. |
| **Max listing pages per source** | — | Optional cap on listing pages per source. Leave empty to let the product limit decide. |
| **Include full product description** | On | Include each product's full description. Turn off for faster, lighter runs. |

#### Localization

Set these to match the market you sell to.

| Input | Default | Description |
|-------|---------|-------------|
| **Ship-to country** | United States | The country prices and shipping are calculated for. Use a proxy in the **same** country for accurate results. |
| **Currency** | USD | The currency for all prices. |
| **Language** | English | Language for titles, option names and descriptions. |

#### Quality filters (optional)

| Input | Description |
|-------|-------------|
| **Minimum times sold** | Keep only products sold at least this many times. |
| **Minimum rating** | Keep only products rated at least this many stars (0–5). |
| **Minimum number of reviews** | Keep only products with at least this many reviews. |
| **Only keep these category IDs (allowlist)** | Keep a product only if its category — or any parent category — is in this list. Great for narrowing a broad category or search to exactly the categories you want. Leave empty to keep everything. |

#### Skip already-imported products (optional)

| Input | Description |
|-------|-------------|
| **Skip these product variants (SKU IDs)** | List of SKU IDs to skip. Matching variants are removed; if all variants of a product are listed, the whole product is skipped. |
| **SKU list URL** | For large sets: a link to a file of SKU IDs (JSON, CSV or plain text). Merged with the list above. |

#### Proxy

| Input | Default | Description |
|-------|---------|-------------|
| **Proxy** | Residential | Required. Use residential proxies and set the proxy country to the **same** country as your Ship-to country — this is what makes shipping resolve to that country. |

> **Advanced settings** (locale override, seller-rating filter, account cookies,
> parallelism and retry limits) are available in a separate section for power
> users. The defaults work for most runs.

***

### Example input

Scrape 50 well-reviewed watches from category 1511, priced in euros, shipping to
the Netherlands, with Dutch titles:

```json
{
  "categoryIds": ["1511"],
  "maxItems": 50,
  "localeCountry": "NL",
  "localeCurrency": "EUR",
  "localeLanguage": "nl",
  "minRating": 4,
  "minSold": 50,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"],
    "apifyProxyCountry": "NL"
  }
}
```

Scrape a few specific products (in US dollars, shipping to the US):

```json
{
  "productIds": ["1005006789883056"],
  "localeCountry": "US",
  "localeCurrency": "USD",
  "localeLanguage": "en",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"],
    "apifyProxyCountry": "US"
  }
}
```

***

### Output

One record per product, containing the product details, full image gallery,
description, specifications, and a `variants` list — one entry per buyable option,
each with its own price, stock, image and shipping.

#### Example output

```json
{
  "productId": "1005006789883056",
  "categoryId": "200362144",
  "title": "Colorful Cartoon Unicorn Student & Kids Watch",
  "descriptionHtml": "<div>...</div>",
  "galleryImages": [
    "https://ae01.alicdn.com/kf/....jpg",
    "https://ae01.alicdn.com/kf/....jpg"
  ],
  "attributes": [
    { "name": "Movement", "value": "Quartz" },
    { "name": "Case Material", "value": "Plastic" }
  ],
  "variants": [
    {
      "skuId": "12000038307818142",
      "option1Name": "Color",
      "option1Value": "Pink",
      "offerSalePrice": 2.55,
      "skuPrice": 4.97,
      "stock": 24,
      "available": true,
      "variantImage": "https://ae01.alicdn.com/kf/....jpg",
      "shipping": {
        "price": 1.99,
        "currency": "EUR",
        "shipToCode": "NL",
        "deliveryDaysMin": 6,
        "deliveryDaysMax": 10,
        "available": true
      }
    }
  ],
  "variantCount": 5,
  "rating": 4.8,
  "reviews": 1548,
  "soldCount": 3000,
  "store": { "name": "..." }
}
```

Each record also includes `thumbnail`, `basePrice` (price range), `topCategoryId`,
`categoryPathIds`, and a `qualityFlags` block that tells you, for example, whether
shipping resolved to your requested country.

***

### Frequently asked questions

**Do I need a proxy?**
Yes. A residential proxy is required to run reliably and to get correct localized
prices and shipping. Set the proxy country to match your Ship-to country.

**How do I get accurate shipping for my country?**
Set the **Ship-to country** and use a **residential proxy in that same country**.
Shipping is reported exactly as AliExpress returns it — if it ever resolves to a
different country, the record is flagged (`qualityFlags.shippingMatchesCountry`)
so you always know the true destination.

**Can I scrape just a few specific products?**
Yes — use **Product URLs** or **Product IDs**, and the scraper skips category
browsing.

**Which formats can I export?**
JSON, CSV, Excel and more. JSON preserves the full nested structure (variants,
gallery, specifications).

***

### Notes

- **A residential proxy is required.** Without one, requests are blocked quickly
  and shipping may not resolve to your chosen country.
- **Shipping is per product, not per variant** — AliExpress returns one shipping
  quote per product, so all variants of a product share the same shipping.
- **Category names may be unavailable** — AliExpress often exposes only category
  **IDs**. The IDs are always included (`categoryId`, `topCategoryId`,
  `categoryPathIds`); map them to names on your side if you need labels.
- **Option values come from the seller** — the option name is localized, but
  individual values may appear exactly as the seller entered them, sometimes in
  mixed languages.
- **Prices and stock are live** and change daily; the same product can show
  different numbers on different days.

### Contact  Support

> This scraper is developed and maintained by [Anyx Solutions](https://anyx.solutions).
>
> **Email**: \[thorthanots@gmail.com]
>
> We provide:
>
> - 24/7 technical support
> - Free consultation on how to use the actor
> - Custom scraper development
> - Data processing and API integration
> - Proxy configuration and optimization

# Actor input Schema

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

AliExpress category IDs to scrape. The scraper opens each category, pages through the listings, and collects products up to your product limit. You can find a category ID in an AliExpress category page URL — e.g. in `aliexpress.com/category/1511/watches.html` the ID is `1511`. Add one or more.

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

Paste full AliExpress category or search-result page URLs instead of category IDs. Example: `https://www.aliexpress.com/category/1511/watches.html`. Every product found on those pages is scraped, up to your product limit.

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

Scrape specific products only, by their product page URL (e.g. `https://www.aliexpress.com/item/1005006789883056.html`). When you use this, the scraper skips category browsing and goes straight to these products.

## `productIds` (type: `array`):

Scrape specific products only, by their numeric product ID (e.g. `1005006789883056`). Same as Product URLs, just shorter to paste.

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

Maximum number of products to scrape from each category or search source. For example, with two category IDs and a limit of 100 you get up to 200 products. Does not apply when you scrape by product URL / ID.

## `maxPagesPerCategory` (type: `integer`):

Optional cap on how many listing pages to open per category or search source. Leave empty to let the product limit above decide. AliExpress allows up to 100 pages per listing.

## `fetchDescription` (type: `boolean`):

Include each product's full HTML description in the output. Turn off for faster, lighter runs when you only need titles, prices, variants and images.

## `localeCountry` (type: `string`):

The country prices and shipping are calculated for. This decides the shipping cost, delivery time and destination in the output. For accurate results, use a proxy located in this same country (see Proxy below).

## `localeCurrency` (type: `string`):

The currency for all prices in the output.

## `localeLanguage` (type: `string`):

The language for product titles, option names and descriptions. Note: individual option values (like a colour name) come straight from the seller and may still appear in mixed languages.

## `minSold` (type: `integer`):

Keep only products that have been sold at least this many times. Leave empty for no limit.

## `minRating` (type: `integer`):

Keep only products rated at least this many stars (0–5). Leave empty for no limit.

## `minReviews` (type: `integer`):

Keep only products with at least this many reviews. Leave empty for no limit.

## `allowedCategoryIds` (type: `array`):

Optional allowlist. When set, a product is kept only if its own category — or any of its parent categories — is in this list. Useful when a broad category or search returns products from categories you don't want. Leave empty to keep products from every category.

## `blacklistSkuIds` (type: `array`):

Optional list of AliExpress SKU IDs to skip — for example variants you have already imported. Any matching variant is removed from the output; if every variant of a product is on the list, the whole product is skipped.

## `blacklistUrl` (type: `string`):

Alternative to the list above for large sets: a link to a file of SKU IDs to skip. The file can be a JSON array, a JSON object like `{"skus": [...]}`, a CSV, or a plain text file with one ID per line. Merged with the inline list above.

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

A proxy is required to run reliably and to get correct localized prices and shipping. Use residential proxies and set the proxy country to the same country as your Ship-to country above — that is what makes shipping resolve to that country.

## `localeLang` (type: `string`):

Advanced: set the full AliExpress locale as `language_COUNTRY` (e.g. `en_NL`). Leave empty to use the Language and Ship-to country selected above. Overrides the Language field when set.

## `minShopRating` (type: `integer`):

Advanced: minimum seller positive-feedback percentage (0–100). Not always available; combine with the option below to control how missing values are treated.

## `excludeOnMissingFilterField` (type: `boolean`):

Advanced: when a filter is set but the value can't be read for a product, drop that product (on) or keep it and flag the missing value (off).

## `sessionCookies` (type: `array`):

Advanced and optional: AliExpress cookies exported from a browser logged in to an account in your Ship-to country. A good residential proxy is usually enough; provide these only if you need to guarantee the shipping country in edge cases.

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

Advanced: how many products to fetch in parallel. Higher is faster but more likely to hit rate limits. The default is a safe balance.

## `maxReclaims` (type: `integer`):

Advanced: if a product is rate-limited, retry it up to this many times on a fresh proxy IP before giving up.

## `discoveryConcurrency` (type: `integer`):

Advanced: how many category/search listing pages to load in parallel while collecting products.

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

Advanced: how many times to retry a listing page that fails or is blocked before skipping it.

## Actor input object example

```json
{
  "categoryIds": [
    "1511"
  ],
  "maxItems": 100,
  "fetchDescription": true,
  "localeCountry": "US",
  "localeCurrency": "USD",
  "localeLanguage": "en",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  },
  "excludeOnMissingFilterField": false,
  "maxConcurrency": 5,
  "maxReclaims": 3,
  "discoveryConcurrency": 3,
  "maxRequestRetries": 8
}
```

# Actor output Schema

## `results` (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 = {
    "categoryIds": [
        "1511"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("ayen-data/aliexpress-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 = { "categoryIds": ["1511"] }

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

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

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

```

## CLI example

```bash
echo '{
  "categoryIds": [
    "1511"
  ]
}' |
apify call ayen-data/aliexpress-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=ayen-data/aliexpress-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/Ulhewwe6MLio6IXwx/builds/nYcoOoCresoqGlfis/openapi.json