# AliExpress Category Scraper (`apt_marble/aliexpress-category-scraper`) Actor

Collect whole AliExpress categories in one run. Up to 998 products each with price, list price, discount, star rating, exact lifetime orders, launch date and Choice badge — plus the subcategories and brands beneath every category. 24 categories, any country, one clean table.

- **URL**: https://apify.com/apt\_marble/aliexpress-category-scraper.md
- **Developed by:** [Hamza](https://apify.com/apt_marble) (community)
- **Categories:** E-commerce
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.70 / 1,000 product scrapeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#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 Category Scraper

Pull an entire AliExpress category at once. Pick one of the 24 top-level
categories — or all of them — and get back every product the category publishes,
each with its selling price, list price and discount, star rating, lifetime
order count, launch date, AliExpress Choice badge, promotional badges, delivery
window and a direct link. The same run can also return the structure underneath
each category: the subcategories AliExpress groups products into, the numeric
category identifiers it uses for them, and the brands it associates with the
category. Built for product researchers, dropshippers and category managers who
need a whole shelf rather than the first two screens of a keyword search.

### What you can do with it

- **Build a category catalogue.** Sweep all 24 top-level categories in one run
  and get roughly 24,000 products in a single table, ready for a spreadsheet or
  a database. (The defaults keep a run small; raise the per-category and total
  limits to collect everything.)
- **Find winners inside a niche.** Order a category by lifetime orders, by
  rating, or by price, and keep only the products above the thresholds you set.
- **Spot new arrivals.** Every product carries the date it was first listed, so
  "everything added to Pet Supplies since March" is one setting.
- **Track discount depth.** Selling price, list price and the discount
  percentage come back side by side, so you can see which shelves are being
  cleared.
- **Compare markets.** Run the same category for the United States and for
  Germany and see two genuinely different assortments, each priced in that
  country's own currency.
- **Map the category tree.** Export the subcategories and brands beneath each
  category, with the numeric identifiers AliExpress uses for them — the cleanest
  way to seed a taxonomy of your own.

### What you get

A product row (abridged — a direct product link and a few more columns come with it):

```json
{
  "recordType": "product",
  "categoryId": "automotive",
  "categoryName": "Automotive",
  "productId": "1005010109964659",
  "globalProductId": "1005010109964659",
  "variantId": "3256809923649907",
  "skuId": "12000051179970093",
  "title": "Cute Cat 3-Piece Car Accessory Set for Women Breathable Mesh Steering Wheel Cover Handbrake Cover Gearshift Cover Rimless",
  "imageUrl": "https://ae-pic-a1.aliexpress-media.com/kf/Sd6e169e0e1e34da1b4a9c108977204cdI.jpg",
  "price": 0.99,
  "priceFormatted": "US $0.99",
  "listPrice": 12.65,
  "listPriceFormatted": "US $12.65",
  "discountPercent": 92,
  "currency": "USD",
  "rating": 5,
  "ordersCount": 61,
  "ordersText": "61 sold",
  "isChoice": true,
  "hasFreeShipping": true,
  "promotionBadges": ["Extra 1% off with coins", "Free shipping"],
  "launchDate": "2025-10-08",
  "deliveryDaysMin": 6,
  "deliveryDaysMax": 11,
  "deliveryEarliest": "2026-08-15",
  "deliveryLatest": "2026-08-20",
  "feedPosition": 1,
  "shopFromCountry": "US",
  "scrapedAt": "2026-08-10T09:14:02.117Z"
}
```

A subcategory row, when category structure is switched on (a ready-made listing link comes with it too):

```json
{
  "recordType": "subcategory",
  "categoryId": "automotive",
  "categoryName": "Automotive",
  "subcategoryKey": "automotive#car_electronics#smart_driving_systems",
  "subcategoryName": "Smart Driving Systems",
  "searchTerm": "smart car systems",
  "siteCategoryIds": ["200161143", "201673901", "201997201", "202175206"],
  "frontCategoryId": "12135",
  "iconUrl": "https://ae-pic-a1.aliexpress-media.com/kf/Se2cc961e10ef4b218f6cd1b2f9feef96q.png"
}
```

And a brand row:

```json
{
  "recordType": "brand",
  "categoryId": "automotive",
  "brandKey": "automotive#Brand#SucceBuy",
  "brandName": "SucceBuy",
  "relevanceScore": 0.306928,
  "globalRelevanceScore": 0.258318,
  "siteCategoryIds": ["34"],
  "iconUrl": "https://img.alicdn.com/bao/uploaded/O1CN01-!!-2457c58df8a694ed8f581eadb5c6d7f80bc13eeb71fa6c166d952bfdd681fc85"
}
```

### Input reference

| Field | Type | Default | What it does |
| --- | --- | --- | --- |
| `categories` | array of text | `["pet_supplies", "electronics"]` | Which top-level categories to collect. Type the name as it appears on the site (`Pet Supplies`), the short id (`pet_supplies`) or the numeric id (`11072`). Use `all` for every one of the 24. |
| `country` | select | `us` | Which country's version of AliExpress to read. Sets the currency **and** the assortment. |
| `resultType` | select | `products` | `Products`, `Category structure (subcategories & brands)`, or `Both`. |
| `sortBy` | select | `feed_order` | How to order the products the category published: as presented, most orders, newest launch, lowest price, highest price, or best rated. |
| `maxProductsPerCategory` | integer | `200` | How many products to keep from each category. Maximum 998. |
| `maxProducts` | integer | `2000` | A ceiling across the whole run. Maximum 25,000. |
| `minOrders` | integer | empty | Keep only products with at least this many lifetime orders. |
| `minRating` | number | empty | Keep only products rated at least this highly out of 5, decimals accepted (`4.5`). Unrated products are excluded, never counted as zero. |
| `minPrice` | number | empty | Lowest price to keep, decimals accepted (`0.99`), in the currency of the country you chose. |
| `maxPrice` | number | empty | Highest price to keep, decimals accepted, in the currency of the country you chose. |
| `choiceOnly` | boolean | `false` | Keep only products carrying the AliExpress Choice badge. |
| `freeShippingOnly` | boolean | `false` | Keep only products advertising free shipping on their listing. |
| `launchedAfter` | text | empty | `YYYY-MM-DD`. Keep only products first listed on or after this date. |
| `categoriesAtOnce` | integer | `2` | How many categories to work through at the same time, 1 to 4. Higher finishes a big job sooner. |

### Output fields

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

| Field | Description |
| --- | --- |
| `categoryId`, `categoryName` | The category this product was collected from. |
| `productId` | The product identifier as the chosen country sees it. |
| `globalProductId` | The product's stable worldwide identifier. Use this to match the same product across two countries. |
| `variantId`, `skuId` | The specific listed variant the price belongs to. |
| `title` | Full product title. |
| `url` | Direct link to the product. |
| `imageUrl` | Main product image. |
| `price`, `priceFormatted` | Current selling price as a number and as the site displays it. |
| `listPrice`, `listPriceFormatted` | The struck-through price shown beside it, when there is one. |
| `discountPercent` | Discount off the list price. |
| `currency` | Currency code of both prices, read from the listing itself. |
| `rating` | Star rating out of 5, or `null` when the product has none yet. |
| `ordersCount`, `ordersText` | Exact lifetime order count as a number and as the site words it. |
| `isChoice` | Whether the product carries the AliExpress Choice badge. |
| `hasFreeShipping` | Whether free shipping is advertised on the listing. |
| `promotionBadges` | The promotional labels shown on the listing, as text. |
| `launchDate` | The date the product was first listed. |
| `deliveryDaysMin`, `deliveryDaysMax` | Estimated delivery window in days, or `null` when the listing shows none. |
| `deliveryEarliest`, `deliveryLatest` | The same estimate as dates. |
| `feedPosition` | Where the product sat in the category, before your ordering was applied. |
| `shopFromCountry` | The country you selected. |
| `scrapedAt` | When the run collected the row. |

#### Category-structure rows (`recordType: "subcategory"` / `"brand"`)

| Field | Description |
| --- | --- |
| `subcategoryKey`, `subcategoryName` | The subcategory's stable key and its display name. |
| `brandKey`, `brandName` | The brand's stable key and its display name. |
| `searchTerm` | The wording AliExpress itself uses to look this subcategory up. |
| `siteCategoryIds` | The numeric AliExpress category identifiers behind the entry. |
| `frontCategoryId` | The numeric identifier of the entry itself. |
| `relevanceScore`, `globalRelevanceScore` | How strongly AliExpress associates the brand with the category, within the category and overall. |
| `iconUrl` | The icon or logo shown for the entry. |
| `listingUrl` | A ready-made link to the matching listing on AliExpress. |

### Pricing

You pay per result row. There is no charge for a category that turns out to be
unreadable, for products your own filters removed, or for duplicates dropped
when the same product appears in two categories.

| What is charged | Price |
| --- | --- |
| Each row added to your results — a product, a subcategory or a brand | $0.0007 ($0.70 per 1,000 rows) |

Worked example: five categories at 200 products each is 1,000 rows, so **$0.70**.
Sweeping all 24 categories for everything they publish is roughly 24,000 rows,
about **$16.80**, plus the platform's usual compute charge.

### Limits & what this actor cannot do

- **A category publishes up to 998 products.** That is what AliExpress makes
  publicly available for a category, and it is what you get — it is not the
  entire category catalogue, and no setting can raise it.
- **There are 24 top-level categories, and they are separate shelves.** Where
  the same product does turn up under two of them it is written once, not twice.
- **Ordering happens inside the category you collected.** "Most orders first" is
  the bestseller order *of the 998 products this category published*, not a
  site-wide AliExpress bestseller chart. The same is true of "newest" and of
  every price and rating ordering. AliExpress publishes no ordering control on
  this listing, so nothing else is possible — and an actor that claimed
  otherwise would be selling you a number that does not exist. Whenever you
  order or filter, the whole listing is collected first and then ranked, so the
  order you get is the order of everything the category published — never of a
  truncated slice of it.
- **Filters narrow what the category published.** They do not make AliExpress
  serve a different or a larger set, so filtering hard on a big minimum will
  return few rows rather than digging deeper.
- **Every row states the currency it was priced in.** If AliExpress serves a
  category in a different currency from the one you selected, the rows say so
  and the run says so, and a minimum or maximum price is refused for that
  category rather than being applied across two currencies.
- **Store and seller details are not on this listing.** No shop name, no seller
  rating, no review count, no ship-from country and no stock level — AliExpress
  simply does not publish them here. They are reported nowhere rather than as
  empty columns.
- **Roughly a third of products have no rating yet.** Those come back as `null`,
  never as a zero, and are excluded from a minimum-rating filter rather than
  quietly failing it.
- **About half of listings carry no delivery estimate.** Those come back empty
  rather than as zero days.
- **Some categories list no brands at all.** Pet Supplies and Women's Clothing
  are examples. The run reports that plainly instead of treating it as a
  failure.
- **The subcategory tree is uneven.** Most categories publish around two dozen
  subcategories; a few publish far fewer, and Books & Media publishes one. You
  get what the category publishes.
- **Country changes the products, not just the currency.** Two countries return
  genuinely different assortments, so two runs are not a like-for-like price
  comparison of the same list.
- **The displayed price can be a promotional one.** AliExpress shows
  first-time-shopper allowances and coin discounts on many listings, and the
  price you see is the price it advertises to a new shopper in that country.
- **Prices, ratings, order counts and positions are a snapshot** taken when the
  run collected the row, and they keep moving afterwards.
- **A category serves the same products in the same order each time.** Running
  the same category twice in a row will not surface anything new; run it on a
  schedule instead to watch it change over days.
- **Product questions and answers do not exist on AliExpress** and are not
  returned by anything.
- **Speed depends on how much you asked for** and on how quickly AliExpress
  answers on the day. No fixed throughput is promised.
- **AliExpress's terms govern automated collection.** You are responsible for
  using the data lawfully and in line with those terms.

### FAQ

**Do I need an AliExpress account?**
No. Nothing is signed in to and nothing personal is involved.

**Does it need my login or password?**
No. The actor never asks for one and could not use one.

**Can I schedule it?**
Yes. Schedule it on Apify like any other actor. A daily or weekly run over the
same categories is the intended way to watch prices, discounts and new arrivals
move.

**Is the data complete?**
It is everything AliExpress publishes for the category — up to 998 products per
category — collected in the order the category presents them. It is not the
site's entire catalogue for that category, and no public route to that exists.

**Why do two countries give me different products?**
Because AliExpress genuinely shows different assortments to shoppers in
different countries, with different prices and shipping. Pick the country you
sell into and the results match what your customers would see.

**Can I get the seller or the number of reviews?**
Not from this actor. A category listing on AliExpress carries neither, and
inventing the columns would be worse than leaving them out. The star rating and
the exact lifetime order count are both included.

**What is `globalProductId` for?**
AliExpress numbers the same product differently for different countries. That
field is the identifier that stays the same everywhere, so you can join a US run
to a German one product by product.

# Actor input Schema

## `categories` (type: `array`):

Which AliExpress top-level categories to read. Type a category name as it appears on the site ("Pet Supplies", "Electronics") or its short id ("pet\_supplies"). Enter "all" to read every one of the 24 top-level categories.

## `country` (type: `string`):

Which country's version of AliExpress to read. This changes the prices, the currency AND which products are shown — two countries return genuinely different selections, not the same list at a different exchange rate.

## `resultType` (type: `string`):

Products collects the category's product listings. Category structure collects the subcategories and brands that sit under each category, including the numeric category ids AliExpress uses internally. Both collects each of them.

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

How to order the products WITHIN each category listing. AliExpress does not offer an ordering control on this listing, so this reorders the products the category returned — it is not a site-wide bestseller or newest chart.

## `maxProductsPerCategory` (type: `integer`):

How many products to keep from each category. A category returns up to 998 products; asking for more than that is not possible and the run will simply keep all of them.

## `maxProducts` (type: `integer`):

A ceiling across the whole run, applied on top of the per-category limit.

## `minOrders` (type: `integer`):

Keep only products with at least this many lifetime orders. Leave empty for no minimum.

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

Keep only products rated at least this highly, out of 5. Decimals are accepted (4.5). Products with no rating yet are excluded by this filter rather than counted as zero.

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

In the currency of the country you chose above. Decimals are accepted (0.99).

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

In the currency of the country you chose above. Decimals are accepted (9.99).

## `choiceOnly` (type: `boolean`):

Keep only products carrying the AliExpress Choice badge.

## `freeShippingOnly` (type: `boolean`):

Keep only products advertising free shipping on their listing card.

## `launchedAfter` (type: `string`):

A date in YYYY-MM-DD form. Keep only products whose launch date is on or after it — useful for finding recent additions to a category.

## `categoriesAtOnce` (type: `integer`):

Raising this makes a large run finish sooner. The safe ceiling is 4; going faster than the site tolerates gets a run cut short, so this is capped.

## Actor input object example

```json
{
  "categories": [
    "pet_supplies",
    "electronics"
  ],
  "country": "us",
  "resultType": "products",
  "sortBy": "most_orders",
  "maxProductsPerCategory": 100,
  "maxProducts": 2000,
  "choiceOnly": false,
  "freeShippingOnly": false,
  "categoriesAtOnce": 2
}
```

# Actor output Schema

## `products` (type: `string`):

Every row this run produced.

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

Counts, skipped categories and failures for this run.

## `openInConsole` (type: `string`):

The run in the Apify console.

# 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 = {
    "categories": [
        "pet_supplies",
        "electronics"
    ],
    "country": "us",
    "resultType": "products",
    "sortBy": "most_orders",
    "maxProductsPerCategory": 100,
    "maxProducts": 2000,
    "categoriesAtOnce": 2
};

// Run the Actor and wait for it to finish
const run = await client.actor("apt_marble/aliexpress-category-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 = {
    "categories": [
        "pet_supplies",
        "electronics",
    ],
    "country": "us",
    "resultType": "products",
    "sortBy": "most_orders",
    "maxProductsPerCategory": 100,
    "maxProducts": 2000,
    "categoriesAtOnce": 2,
}

# Run the Actor and wait for it to finish
run = client.actor("apt_marble/aliexpress-category-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 '{
  "categories": [
    "pet_supplies",
    "electronics"
  ],
  "country": "us",
  "resultType": "products",
  "sortBy": "most_orders",
  "maxProductsPerCategory": 100,
  "maxProducts": 2000,
  "categoriesAtOnce": 2
}' |
apify call apt_marble/aliexpress-category-scraper --silent --output-dataset

```

## MCP server setup

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