# AliExpress Scraper — Products, Reviews & Review Analytics (`brilliant_gum/aliexpress-scraper`) Actor

Scrape AliExpress by keyword or category: product details, price, discount, SKUs, images, store and shipping, plus unlimited customer reviews. Then get built-in review analytics — per-review sentiment and aspect themes, with per-product rating distribution, positive/negative rate and top themes.

- **URL**: https://apify.com/brilliant\_gum/aliexpress-scraper.md
- **Developed by:** [Yuliia Kulakova](https://apify.com/brilliant_gum) (community)
- **Stats:** 3 total users, 2 monthly users, 90.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.01 / product scraped

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

## AliExpress Scraper — Products, Reviews & Review Analytics

Search AliExpress and extract full product details with per-SKU pricing, plus customer reviews with sentiment and aspect insights — no login, no API key.

![AliExpress Scraper](https://api.apify.com/v2/key-value-stores/IuFu0Cw6PpOkNkDV7/records/aliexpress-scraper-banner.png)

> **Enjoying this Actor?** If it's useful, please leave a ⭐️ rating and a short review — it genuinely helps others find it. **Something not working as expected?** Open an issue on the Actor's **Issues** tab — I actively maintain this Actor and try to respond and fix reported problems quickly.

***

Point it at keywords, search/category URLs, product URLs, or bare item IDs. Get back clean, structured records: product cards from search, full product detail (price, discount, variants, specs, store/seller, shipping, stock, video), and paginated reviews with sentiment and theme analysis. Built for **e-commerce and dropshipping research, price and competitor intelligence, and review/sentiment analysis**.

It combines three modes — **search**, **product-details**, and **reviews** — in a single run, with proxies configured automatically.

***

### Key features

- **Three modes in one actor, combinable.** Run a keyword/URL search, fetch full product detail by URL or item ID, and paginate reviews — separately or together (e.g. `search` + `reviews`, or `product-details` + `reviews`).
- **Per-SKU price matrix.** Every variant is emitted in `skus[]` with `skuId`, `price`, `originalPrice`, and `currency`, plus `priceMin`/`priceMax` across the whole SKU set — so you can compare a specific variant against competing listings, not just the headline price.
- **Full commercial fields.** `price`, `originalPrice`, `discountPercent`, `orders` (units sold; a floor like `10000` for `"10,000+ sold"`), `rating`, `reviewCount`, `wishlistCount`, `priceDisplay`.
- **Rich media & content.** Full image gallery (`images[]`, `primaryImage`), product `video` (`video`/`videoId`/`videoPoster`), `specifications[]` (name/value spec table), and the full `description` body text + inline `descriptionImages[]` (optional, one extra request).
- **Store & seller stats.** `storeName`, `storeId`, `storeUrl`, `sellerId`, `sellerPositiveRate`, `sellerReviews`, `sellerYears`, `storeOpenDate`.
- **Shipping & availability.** `shipsFrom`, `shippingCost` + `shippingCurrency`, `deliveryTime` (ETA window), `shippingText`, plus `inStock` / `availableQuantity` and human-readable `productType`.
- **Reviews with insight.** Per-review `sentiment` (`{score, label}`) and aspect `themes[]` (quality, value, shipping, ease, durability, appearance, size, performance), translated text, reviewer country, photos, and helpful votes — plus an optional per-product **review-insights** roll-up (rating distribution, sentiment breakdown, top themes, recent-negative trend).
- **Cross-run price-change monitoring.** In monitoring mode, products carry `previousPrice`, `priceDelta`, and `changeType` (`new` / `increased` / `decreased` / `unchanged`) and only new or price-changed items are emitted — ideal for price alerting.
- **Deduplication** within a run and, optionally, across scheduled runs via a named key-value store.
- **No login, no API key, no paid endpoints.** Public, non-authenticated pages only.

***

### Input

Provide input via the Apify UI or the API. Only `mode` is required; supply at least one source appropriate to the mode(s) you pick.

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | array | `["search"]` | Any of `search`, `product-details`, `reviews`. Combinable. |
| `searchTerms` | string\[] | — | Keywords to search (search mode). Paginated 60 products/page. |
| `searchUrls` | string\[] | — | Ready-made AliExpress search/category URLs, used verbatim. |
| `startUrls` | requestList | — | Product URLs feed details/reviews; search/category URLs are paginated. |
| `productUrls` | string\[] | — | Direct product URLs (`/item/<id>.html`) for details/reviews. |
| `itemIds` | string\[] | — | Bare numeric product IDs (e.g. `1005006976494502`). |
| `category` | select | `all` | Narrow keyword search to a category browse filter. |
| `maxItems` | integer | `0` | Max products per query (0 = all, capped at 3000). |
| `maxSearchPages` | integer | `0` | Cap search pages fetched per query (60/page). |
| `sortBy` | select | `default` | `default` / `orders` / `price_asc` / `price_desc`. |
| `minPrice` / `maxPrice` | number | — | Price filter, in the result currency. |
| `shipToCountry` | string | `US` | Two-letter ship-to code. Drives shipping context and localized pricing. |
| `currency` | string | `USD` | Three-letter result currency. |
| `language` | string | `en_US` | Locale for titles/text. |
| `fetchProductDetails` | boolean | `true` | Enrich each search result with the full product page (alias: `enrichListingDetails`). Turn off for a fast/cheap lightweight card. |
| `fetchDescription` | boolean | `false` | Also fetch the description body text + inline images (one extra request/product). Requires product details. |
| `maxReviews` | integer | `0` | Reviews per product (0 = all). |
| `reviewsSort` | select | `default` | `default` (most relevant) / `latest`. |
| `reviewsRating` | string\[] | — | Keep only these star ratings (`5`…`1`). |
| `reviewsFilter` | select | `all` | `all` / `image` / `additional` / `local`. |
| `reviewsFromDate` | string | — | `YYYY-MM-DD` or relative (`"30 days"`). |
| `reviewsKeywords` | string\[] | — | Keep only reviews containing any of these terms. |
| `includePersonalData` | boolean | `true` | Include reviewer name/country; off to redact identity. |
| `includeReviewInsights` | boolean | `false` | Emit one review-insights roll-up per product. |
| `reviewSentiment` | boolean | `true` | Add `{score, label}` sentiment to each review. |
| `themeExtraction` | boolean | `true` | Tag each review with aspect themes and polarity. |
| `deduplicate` | boolean | `true` | Drop already-seen `dedupKey`s (in-run, and cross-run if a store is set). |
| `deduplicateKeyStore` | string | — | Named KV store to persist seen keys across scheduled runs. |
| `monitoringMode` | boolean | `false` | Emit only new or price-changed products (requires a key store). |
| `maxConcurrency` | integer | `5` | Parallel product targets (keep 3–8 for reliability). |
| `maxChallengeRetries` | integer | `8` | Retry attempts per item on temporary failures. |
| `proxy` | proxy | (auto) | Proxies are included and configured automatically — leave empty. |

> **Currency:** set `shipToCountry` and `currency` together. Region and currency are handled automatically, so a US ship-to still returns USD prices.

#### Example — search + enrich

```json
{
  "mode": ["search"],
  "searchTerms": ["wireless earbuds"],
  "maxItems": 20,
  "sortBy": "orders",
  "fetchProductDetails": true,
  "shipToCountry": "US",
  "currency": "USD",
  "language": "en_US"
}
```

#### Example — product details (with description body)

```json
{
  "mode": ["product-details"],
  "productUrls": ["https://www.aliexpress.com/item/3256807903014930.html"],
  "itemIds": ["1005006976494502"],
  "fetchDescription": true,
  "shipToCountry": "US",
  "currency": "USD"
}
```

#### Example — reviews + insights

```json
{
  "mode": ["reviews"],
  "productUrls": ["https://www.aliexpress.com/item/3256807903014930.html"],
  "maxReviews": 15,
  "reviewsSort": "latest",
  "includeReviewInsights": true
}
```

***

### Output

Every record carries a `recordType` (`product`, `review`, or `review-insights`), a stable `dedupKey`, and a `scrapedAt` timestamp. Samples below are trimmed for readability; field names are exactly as emitted.

#### Product record (`recordType: "product"`)

```json
{
  "recordType": "product",
  "itemId": "3256807903014930",
  "title": "TWS Wireless Earbuds Bluetooth 5.3 Headphones",
  "url": "https://www.aliexpress.com/item/3256807903014930.html",
  "canonicalUrl": "https://www.aliexpress.com/item/3256807903014930.html",
  "price": 19.41,
  "originalPrice": 68.08,
  "discountPercent": 71,
  "currency": "USD",
  "priceDisplay": "$19.41",
  "priceMin": 17.83,
  "priceMax": 24.9,
  "rating": 4.7,
  "reviewCount": 1832,
  "orders": 10000,
  "ordersText": "10,000+ sold",
  "wishlistCount": 4521,
  "primaryImage": "https://ae01.alicdn.com/kf/S....jpg",
  "images": ["https://ae01.alicdn.com/kf/S....jpg", "https://ae01.alicdn.com/kf/S....jpg"],
  "video": "https://video.aliexpress-media.com/play/....mp4",
  "videoId": "3009876543210",
  "videoPoster": "https://ae01.alicdn.com/kf/S....jpg",
  "category": { "id": "70804001", "path": "44->70804001" },
  "productType": "Earphones & Headphones",
  "inStock": true,
  "availableQuantity": 9999,
  "storeName": "TWS Audio Official Store",
  "storeId": "1102345678",
  "storeUrl": "https://www.aliexpress.com/store/1102345678",
  "sellerId": 234567890,
  "sellerPositiveRate": "97.4",
  "sellerReviews": 15342,
  "sellerYears": 4,
  "storeOpenDate": "2021-06-18",
  "shipsFrom": "CN",
  "shippingCost": 0,
  "shippingCurrency": "USD",
  "shippingText": "Free shipping · AliExpress Standard Shipping",
  "deliveryTime": "Sep 18 - Oct 02",
  "specifications": [
    { "name": "Brand Name", "value": "OEM" },
    { "name": "Category", "value": "Earphones & Headphones" },
    { "name": "Bluetooth Version", "value": "5.3" }
  ],
  "variantOptions": [
    { "name": "Color", "values": ["Black", "White", "Blue"] }
  ],
  "skus": [
    { "skuId": "12000041234567890", "price": 19.41, "originalPrice": 68.08, "currency": "USD" },
    { "skuId": "12000041234567891", "price": 17.83, "originalPrice": 62.5, "currency": "USD" }
  ],
  "skuCount": 3,
  "sellingPoints": ["Free shipping", "Extra 1% off with coins"],
  "description": "Product Description\nBluetooth 5.3 chip, 40ms low latency ...",
  "descriptionImages": ["https://ae01.alicdn.com/kf/S....jpg"],
  "descriptionUrl": "https://ae01.alicdn.com/kf/....html",
  "ratingDistribution": { "1": 21, "2": 15, "3": 48, "4": 260, "5": 1488 },
  "previousPrice": null,
  "priceDelta": null,
  "changeType": null,
  "isSponsored": false,
  "position": 1,
  "searchQuery": "wireless earbuds",
  "detailed": true,
  "scrapedAt": "2026-09-03T09:20:00.000Z",
  "dedupKey": "product:3256807903014930"
}
```

**Product fields:** `itemId`, `title`, `url`, `canonicalUrl`, `price`, `originalPrice`, `discountPercent`, `currency`, `priceDisplay`, `priceMin`, `priceMax`, `rating`, `reviewCount`, `orders`, `ordersText`, `wishlistCount`, `images[]`, `primaryImage`, `video`, `videoId`, `videoPoster`, `category{id,path}`, `productType`, `inStock`, `availableQuantity`, `storeName`, `storeId`, `storeUrl`, `sellerId`, `sellerPositiveRate`, `sellerReviews`, `sellerYears`, `storeOpenDate`, `shipsFrom`, `shippingCost`, `shippingCurrency`, `shippingText`, `deliveryTime`, `specifications[{name,value}]`, `variantOptions[{name,values[]}]`, `skus[{skuId,price,originalPrice,currency}]`, `skuCount`, `sellingPoints[]`, `description`, `descriptionImages[]`, `descriptionUrl`, `ratingDistribution{1..5}`, `previousPrice`, `priceDelta`, `changeType`, `isSponsored`, `position`, `searchQuery`, `detailed`, `scrapedAt`, `dedupKey`.

> A lightweight search card (`fetchProductDetails: false`) carries `detailed: false` and fills only the fields available from the search result — id, title, url, price/originalPrice/discountPercent, rating, orders, image, `sellingPoints`, `isSponsored` — with the detail-only fields left `null`.

> `sellerPositiveRate` and `sellerReviews` are `null` when AliExpress doesn't publish a seller-feedback score for that store (common for newer stores) — reported as unknown rather than a misleading `0`.

#### Review record (`recordType: "review"`)

```json
{
  "recordType": "review",
  "reviewId": "800000123456789",
  "itemId": "3256807903014930",
  "productUrl": "https://www.aliexpress.com/item/3256807903014930.html",
  "productName": "TWS Wireless Earbuds Bluetooth 5.3 Headphones",
  "rating": 5,
  "text": "Great sound and the battery lasts all day. Fast shipping, arrived in 12 days.",
  "textTranslated": null,
  "author": "A***a",
  "authorCountry": "US",
  "date": "2026-08-21",
  "sku": "Color:Black",
  "verified": true,
  "anonymous": false,
  "aiGenerated": false,
  "helpful": 7,
  "downVotes": 0,
  "images": ["https://ae01.alicdn.com/kf/S....jpg"],
  "thumbnails": ["https://ae01.alicdn.com/kf/S....jpg"],
  "logistics": "AliExpress Standard Shipping",
  "labels": [{ "name": "Sound Quality", "value": "Excellent" }],
  "sentiment": { "score": 0.86, "label": "positive" },
  "themes": [
    { "theme": "performance", "polarity": "positive", "mentions": 2 },
    { "theme": "shipping", "polarity": "positive", "mentions": 1 }
  ],
  "scrapedAt": "2026-09-03T09:20:00.000Z",
  "dedupKey": "review:800000123456789"
}
```

**Review fields:** `reviewId`, `itemId`, `productUrl`, `productName`, `rating`, `text`, `textTranslated`, `author`, `authorCountry`, `date`, `sku`, `verified`, `anonymous`, `aiGenerated`, `helpful`, `downVotes`, `images[]`, `thumbnails[]`, `logistics`, `labels[{name,value}]`, `sentiment{score,label}`, `themes[{theme,polarity,mentions}]`, `scrapedAt`, `dedupKey`.

#### Review-insights record (`recordType: "review-insights"`, optional)

```json
{
  "recordType": "review-insights",
  "itemId": "3256807903014930",
  "productName": "TWS Wireless Earbuds Bluetooth 5.3 Headphones",
  "rating": 4.7,
  "reviewCount": 1832,
  "reviewsAnalyzed": 15,
  "sentimentBreakdown": { "positive": 12, "neutral": 2, "negative": 1 },
  "avgSentiment": 0.58,
  "catalogRatingDistribution": { "1": 21, "2": 15, "3": 48, "4": 260, "5": 1488 },
  "catalogPositiveRate": 95.4,
  "catalogNegativeRate": 2,
  "topThemes": [
    { "theme": "performance", "mentions": 9, "polarity": "positive" },
    { "theme": "shipping", "mentions": 6, "polarity": "positive" },
    { "theme": "value", "mentions": 4, "polarity": "positive" }
  ],
  "recentNegativeShare": 0.2,
  "scrapedAt": "2026-09-03T09:20:00.000Z",
  "dedupKey": "insights:3256807903014930:1756890000000"
}
```

**Insights fields:** `itemId`, `productName`, `rating`, `reviewCount`, `reviewsAnalyzed`, `sentimentBreakdown{positive,neutral,negative}`, `avgSentiment`, `catalogRatingDistribution{1..5}`, `catalogPositiveRate`, `catalogNegativeRate`, `topThemes[{theme,mentions,polarity}]`, `recentNegativeShare`, `scrapedAt`, `dedupKey`.

> **Two bases in one record.** `sentimentBreakdown`, `avgSentiment`, `topThemes` and `recentNegativeShare` are computed from the **`reviewsAnalyzed`** reviews scraped this run. The `catalog*` fields (`catalogRatingDistribution`, `catalogPositiveRate`, `catalogNegativeRate`) come from **AliExpress's own full review statistics** for the product — all reviews, not just the sample. For sentiment metrics to be representative, scrape enough reviews (`maxReviews`); the `catalog*` fields are full-catalog regardless. `catalogPositiveRate` and `catalogNegativeRate` are percentages (0–100). `catalog*` fields are `null` when AliExpress doesn't return those statistics.

***

### Pricing

This actor uses **pay-per-event**: you are charged per result you collect, plus a small actor-start fee. Product records and review records are priced separately (reviews are the cheapest, since they come in volume), and each per-product review-insights roll-up is its own event. You only pay for what you actually get, so cost scales with your run. Setting a `maxItems` / `maxReviews` cap, or turning off `fetchProductDetails` for lightweight cards, is the direct way to control spend. The exact per-event prices are shown on this actor's Apify Store page.

***

### Use cases

- **Product sourcing & dropship research** — pull full catalogs by keyword or category with variants, specs, images, and store/seller stats to shortlist products and suppliers.
- **Price & competitor intelligence** — track `price`, `originalPrice`, `discountPercent`, and the per-SKU price matrix across competing listings and stores.
- **Price monitoring & alerting** — schedule monitoring mode with a dedup key store to receive only new or price-changed products, with `priceDelta` and `changeType`.
- **Review & sentiment analysis** — collect reviews at scale with per-review sentiment and aspect themes, plus per-product roll-ups to spot quality, shipping, and value trends.

***

### Limitations (read this)

We would rather be upfront than surprise you.

- **No login or API key is needed** — and none is used. The actor scrapes only public, non-authenticated pages. Region, currency and site selection are handled automatically — just set `shipToCountry` and `currency`, and a US ship-to still returns USD prices.
- **Full product detail is occasionally unavailable for some items.** On a given run a share of items (~10% at default settings) may not return the full detail page — those **gracefully fall back to the still-useful search card** (id, title, url, price, rating, orders, image), flagged `detailed: false`. **No records are lost.** Raising `maxChallengeRetries` increases full-detail success at the cost of speed. Search and reviews are not affected.
- **`ratingDistribution` on products is backfilled only when reviews are also collected.** The current product page exposes only overall rating and count, not the per-star breakdown. When you run `product-details` (or `search` enrichment) together with `reviews` for the same item, the distribution is filled from the reviews' star statistics; in detail-only mode it is honestly left `null`.
- **Sentiment and themes are lexicon/rating-based**, not an external LLM — fast and deterministic, but a heuristic. Treat them as directional signal, not ground truth.
- **You are responsible for compliance** with AliExpress's Terms of Service and applicable law. Data is intended for lawful price, assortment, and review analytics. No personal data beyond the public reviewer display name/country is collected, and that can be redacted with `includePersonalData: false`.

***

### FAQ

**Do I need an AliExpress account or cookies?**
No. The actor uses only public pages and needs no login, cookies-from-login, or paid API key.

**Do I need to configure the proxy or region?**
No — proxies, region and currency are configured automatically. Just set `shipToCountry` and `currency`; a US ship-to still returns USD prices.

**Some products came back without full details — why?**
On a given run some items don't return the full detail page and fall back to the search card (`detailed: false`). Increase `maxChallengeRetries` to convert more of them to full detail.

**Can I get search results, full details, and reviews in one run?**
Yes — set `mode` to multiple values, e.g. `["search", "reviews"]` or `["product-details", "reviews"]`. When both product and reviews are collected for an item, the product's `ratingDistribution` is backfilled from the review star stats.

**How do I get the full description text?**
Set `fetchDescription: true` (requires product details). It adds one request per product and fills `description` + `descriptionImages[]`.

**How does price monitoring work?**
Set `monitoringMode: true` with a `deduplicateKeyStore`. Each run compares against the stored price state and emits only new or price-changed products, carrying `previousPrice`, `priceDelta`, and `changeType`.

**What currency/language will I get?**
Whatever you set in `currency` and `language`, aligned with `shipToCountry`. Defaults are `USD`, `en_US`, ship-to `US`.

# Actor input Schema

## `mode` (type: `array`):

What to scrape. 'search' runs each search term / search URL / category and returns one product record per result. 'product-details' fetches the full product record for each startUrls / productUrls / itemIds entry. 'reviews' paginates customer reviews for the resolved products. Modes can be combined (e.g. search + reviews, or product-details + reviews).

## `searchTerms` (type: `array`):

Keywords to search on AliExpress (e.g. "wireless earbuds", "phone case"). Search mode only. Each term is paginated (60 products per page).

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

Ready-made AliExpress search or category URLs (https://www.aliexpress.com/w/wholesale-...html or category pages). Used verbatim and paginated. Advanced alternative to searchTerms.

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

AliExpress URLs to scrape. Product URLs (/item/<id>.html) feed product-details/reviews; search or category URLs are paginated in search mode.

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

Direct AliExpress product URLs as plain strings (https://www.aliexpress.com/item/<id>.html). Used by product-details and reviews modes.

## `itemIds` (type: `array`):

Bare numeric AliExpress product IDs (e.g. 1005006976494502). Used by product-details and reviews modes.

## `category` (type: `string`):

Optional category to narrow keyword search. 'all' searches everything. Combined with searchTerms as a browse filter.

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

Maximum products per search term / search URL. 0 = all available (safety-capped at 3000). Does not limit reviews (see Max reviews).

## `maxSearchPages` (type: `integer`):

Maximum search result PAGES to fetch per query (60 products per page). 0 = until maxItems reached or no more results.

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

Sort order for search results.

## `minPrice` (type: `integer`):

Keep only products at or above this price (in the result currency). Passed to AliExpress and applied to output.

## `maxPrice` (type: `integer`):

Keep only products at or below this price (in the result currency).

## `shipToCountry` (type: `string`):

Two-letter ISO ship-to country code (e.g. US, GB, DE, FR, BR). Controls shipping context and localized pricing. Region and site are handled automatically — a US ship-to still returns USD prices.

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

Three-letter currency code for prices (e.g. USD, EUR, GBP).

## `language` (type: `string`):

Language/locale for titles and text (e.g. en\_US, de\_DE, fr\_FR).

## `fetchProductDetails` (type: `boolean`):

In search mode, enrich each result with the full product page (SKU variants, specs, store/seller, shipping, wishlist, full image gallery, per-SKU prices, video, stock, product type). Turn off for a faster/cheaper lightweight card (id, title, url, price, rating, orders, image, sponsored). Alias: enrichListingDetails.

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

Also fetch and extract the full product description text (and its inline image URLs) from AliExpress's description document. This adds one extra request per product, so it is off by default. Requires product details (search enrichment or product-details mode).

## `maxReviews` (type: `integer`):

Maximum reviews per product. 0 = all available (paginates AliExpress's reviews feed).

## `reviewsSort` (type: `string`):

Review ordering.

## `reviewsRating` (type: `array`):

Keep only reviews with these star ratings. Empty = all.

## `reviewsFilter` (type: `string`):

Which reviews to fetch from AliExpress. 'image' returns only reviews with photos; 'additional' only additional/follow-up reviews; 'local' only local-market reviews.

## `reviewsFromDate` (type: `string`):

Keep reviews on/after this date (YYYY-MM-DD) or relative like '30 days', '6 months'.

## `reviewsKeywords` (type: `array`):

Keep only reviews whose text contains any of these keywords.

## `includePersonalData` (type: `boolean`):

Include the reviewer's public fields (name, country). Turn off to redact reviewer identity and keep only the anonymous review id.

## `includeReviewInsights` (type: `boolean`):

Emit one 'review-insights' record per product: rating distribution, sentiment breakdown, top aspect themes and recent-negative trend (uses AliExpress's own star statistics).

## `reviewSentiment` (type: `boolean`):

Add sentiment {score,label} to each review (consumer lexicon + rating prior, no external AI).

## `themeExtraction` (type: `boolean`):

Tag each review with product aspect themes (quality, value, shipping, ease of use, durability, appearance, size, performance) and polarity.

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

Drop records whose dedupKey was already produced (within run, and across runs if a key store is set).

## `deduplicateKeyStore` (type: `string`):

Named key-value store to persist seen dedupKeys across scheduled runs. Empty = in-run dedup only.

## `monitoringMode` (type: `boolean`):

Output only records not seen in the previous run (requires a dedup key store). Great for price/review alerting.

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

Parallel product targets. Keep moderate (3-8) for reliability.

## `maxChallengeRetries` (type: `integer`):

Retry attempts per item on temporary failures. Full product detail is occasionally unavailable on a given run; higher values raise the full-detail success rate at the cost of speed.

## `proxy` (type: `object`):

Proxies are included and configured automatically — leave the default in place.

## Actor input object example

```json
{
  "mode": [
    "search"
  ],
  "searchTerms": [
    "wireless earbuds"
  ],
  "category": "all",
  "maxItems": 20,
  "maxSearchPages": 0,
  "sortBy": "default",
  "shipToCountry": "US",
  "currency": "USD",
  "language": "en_US",
  "fetchProductDetails": true,
  "fetchDescription": false,
  "maxReviews": 20,
  "reviewsSort": "default",
  "reviewsFilter": "all",
  "includePersonalData": true,
  "includeReviewInsights": false,
  "reviewSentiment": true,
  "themeExtraction": true,
  "deduplicate": true,
  "monitoringMode": false,
  "maxConcurrency": 5,
  "maxChallengeRetries": 8,
  "proxy": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

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

All scraped AliExpress product, review and review-insights records.

# 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 = {
    "mode": [
        "search"
    ],
    "searchTerms": [
        "wireless earbuds"
    ],
    "maxItems": 20,
    "maxReviews": 20,
    "proxy": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("brilliant_gum/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 = {
    "mode": ["search"],
    "searchTerms": ["wireless earbuds"],
    "maxItems": 20,
    "maxReviews": 20,
    "proxy": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("brilliant_gum/aliexpress-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 '{
  "mode": [
    "search"
  ],
  "searchTerms": [
    "wireless earbuds"
  ],
  "maxItems": 20,
  "maxReviews": 20,
  "proxy": {
    "useApifyProxy": true
  }
}' |
apify call brilliant_gum/aliexpress-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,brilliant_gum/aliexpress-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/dVikOgPDl2c1qLbWx/builds/YDtkKnczfabi5VaHb/openapi.json