# Taobao Search Scraper (`apt_marble/taobao-search-scraper`) Actor

Search Taobao by keyword and get every product as a clean row: price in yuan, promotions, shop name, images and direct links, in the site's sales ordering. Related searches reach wider. No account, no login.

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

## Pricing

$1.20 / 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?

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

## Taobao Search Scraper

Turn any Taobao search into a clean, structured product table. For every
product you get the price in yuan, any running promotion, and the shop behind
it — name and link — plus images, buyer-opinion tags and a direct link, in the
site's own sales ordering, so you can compare products side by side instead of
opening dozens of tabs. Each term also reaches further through the site's own
related searches, and every extra row is marked with the related search that
produced it. No account and no login are needed: type your search terms, press
start, and the results arrive ready to use. Runs are fast because pages are
read directly, with no browser and nothing to sign in to.

### What you can do with it

- **Research a product idea.** Pull the site's sales-ordered selection for
  "蓝牙耳机" and see exactly which products, prices and shops lead the market.
- **Go wider with related searches.** One term fans out into two levels of
  the site's own related searches — up to 1,000 products per term — so even a
  huge niche like "蓝牙耳机" is covered in a single run. Higher limits simply
  read further into the query graph.
- **Track prices.** Schedule the same searches weekly and watch prices and
  promotions move over time.
- **Find suppliers and shops.** Every row carries its shop, so repeated
  searches build a map of who sells what.
- **Feed a spreadsheet or store.** Every field is a plain column — export to
  Excel, Google Sheets, CSV or JSON in one click.

### What you get

One row per product, in the site's sales ordering. Abridged real example:

```json
{
  "keyword": "蓝牙耳机",
  "sourceQuery": null,
  "searchPosition": 1,
  "itemId": "765833709683",
  "title": "華強北Pro3代藍牙耳機降噪無線2026新款5洛達頂配2高音質超長待機",
  "url": "https://world.taobao.com/item/765833709683.htm",
  "price": 388,
  "promoPrice": null,
  "promoLabel": "活動價",
  "currency": "CNY",
  "shopId": "467290190",
  "shopName": "深圳華強北正品直銷總店",
  "shopUrl": "https://world.taobao.com/dianpu/467290190.htm",
  "freeShipping": false,
  "serviceScore": 4.76,
  "topReviewTags": [],
  "imageUrl": "https://img.alicdn.com/imgextra/i3/2523443838/O1CN01QULkBg1eDrFVYcid7_!!2523443838.jpg",
  "scrapedAt": "2026-09-21T00:00:00.000Z"
}
```

### Input reference

| Field | Type | Default | What it does |
| --- | --- | --- | --- |
| `keywords` | list of text | `["蓝牙耳机"]` | The searches to run, exactly as you would type them on the site, in Chinese or English. Up to 10 per run. |
| `maxResultsPerKeyword` | number | `100` | How many products to collect for each search term: 20 from the term itself, the rest from its related searches (maximum 220). |
| `minPrice` | number | — | Keep only collected products at or above this price, in yuan. Leave empty for no floor. |
| `maxPrice` | number | — | Keep only collected products at or below this price, in yuan. Leave empty for no ceiling. |
| `freeShippingOnly` | true/false | `false` | Keep only collected products with free shipping. |
| `includeRelatedSearches` | true/false | `true` | Read the site's own related searches for each term to reach more products. Turn off for the term's own 20 only. |
| `parallelSearches` | number | `3` | How many search terms to work through at the same time (1–5). |

### Output fields

| Field | Type | Description |
| --- | --- | --- |
| `keyword` | text | The search term this product was collected for. |
| `sourceQuery` | text | The related search that produced this row; empty for the term's own selection. |
| `searchPosition` | number | Running position in the collected order, which follows the site's sales ordering. |
| `itemId` | text | The product's identifier on the site. |
| `title` | text | Product title. |
| `url` | text | Direct link to the product. |
| `price` | number | Current selling price, in yuan. |
| `promoPrice`, `promoLabel` | number / text | Discounted price and the promotion's label while the site advertises one; `promoPrice` is empty when the promotion matches the selling price. |
| `currency` | text | Always `CNY`. |
| `shopId`, `shopName`, `shopUrl` | text | The shop behind the product. |
| `freeShipping` | true/false | Whether the product ships free. |
| `serviceScore` | number | The seller's description-match score, as the site publishes it. |
| `topReviewTags` | list | The product's top buyer-opinion tags with buyer counts, when the site publishes them. |
| `categoryId` | text | The site's own category for this product. |
| `imageUrl`, `images` | text / list | The main product picture the listing publishes (one per product on this surface). |
| `scrapedAt` | text | When the row was collected. |

### Pricing

You pay per product returned — nothing else, and nothing for a search that
comes back with nothing.

| What you pay for | Price |
| --- | --- |
| Each product row | $1.20 per 1,000 |

**Worked example.** Four search terms × 100 products each = 400 rows =
**$0.48** for the run.

### Limits & what this actor cannot do

- Each term returns the site's own sales-ordered selection — 20 products —
  plus two levels of related searches (10 queries, then each query's own
  related searches), up to 1,000 products per term. Reads run in parallel
  waves and later waves compensate for failed reads and repeats, so the run
  keeps filling until your requested number is reached or the query graph runs
  out. Shard a big topic into several terms to go wider still.
- Rows arrive in the site's sales ordering, but per-product sales totals are
  not published on this surface, so positions are reported and totals are not.
- Prices, promotions and rankings are a snapshot at the moment of collection
  and keep changing afterwards. Two runs minutes apart can return a slightly
  different mix, because the site itself reshuffles them.
- Price and shipping filters narrow the collected products after each read;
  they do not change which products the site serves.
- Some products publish no buyer-opinion tags. Those come back with an empty
  tag list rather than invented tags.
- Only the main product picture is published on this surface — one image per
  product. Galleries live behind interactive views that need a browser, which
  is deliberately out of scope to keep runs fast.
- Speed depends on the size of the job and on the source site's own response
  times; no fixed throughput is promised.
- The source site's terms govern automated access. You are responsible for
  using the data lawfully and in line with those terms, and for handling any
  personal data in line with applicable privacy law.

### FAQ

**Do I need a Taobao account?**
No. Nothing is signed in to and nothing is bought.

**Does it need my login or password?**
No. There is no place to enter one, and none is ever used.

**Can I search in English?**
Yes. Type the term either way; Chinese terms usually return the widest
selection, because most listings are written in Chinese.

**What is `sourceQuery`?**
The related search a row came from. Rows collected directly for your term
leave it empty, so you can always tell the term's own selection apart from
the wider net.

**I asked for 100 but got 20 — why?**
Because related searches are turned off. A term's own page holds 20 products
and the site serves no further pages for it, so 20 is the complete answer for
that setting — the run summary says so explicitly. Turn related searches back
on to reach higher limits through the term's own related queries.

**Can I schedule it?**
Yes. Save your search terms as a task and run it on any schedule Apify
supports — hourly, daily or weekly — then compare the results over time.

**Is the data complete?**
It is everything the site publishes for that term and its related searches,
up to 220 products per term. Shard a big topic into several terms to go
wider.

# Actor input Schema

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

Keep only the collected products with free shipping. Applied to the results after collection.

## `includeRelatedSearches` (type: `boolean`):

Also read the site's own related searches for each term (up to 10 per term) to reach more products. Each extra row is marked with the related search that produced it. Turned off, a term yields its own page of 20 products even when the limit is higher.

## `keywords` (type: `array`):

One or more product searches, exactly as you would type them on the site (Chinese or English). Each term returns the site's sales-ordered selection plus related searches. Up to 10 per run.

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

Keep only collected products at or below this price, in yuan. Applied to the results after collection; leave empty for no ceiling.

## `maxResultsPerKeyword` (type: `integer`):

How many products to collect for each search term: 20 from the term itself, the rest from two levels of related searches (up to 1,000). Higher limits read more queries and take longer.

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

Keep only collected products at or above this price, in yuan. Applied to the results after collection; leave empty for no floor.

## `parallelSearches` (type: `integer`):

How many search terms to work through at the same time. Higher is faster; lower is gentler on the source site.

## Actor input object example

```json
{
  "freeShippingOnly": false,
  "includeRelatedSearches": true,
  "keywords": [
    "蓝牙耳机"
  ],
  "maxResultsPerKeyword": 100,
  "parallelSearches": 3
}
```

# Actor output Schema

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

Every product matching your search, with price, sales, shop and ratings.

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

Counts per search term, including any term that could not be read.

# 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 = {
    "keywords": [
        "蓝牙耳机"
    ],
    "maxResultsPerKeyword": 100,
    "parallelSearches": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("apt_marble/taobao-search-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 = {
    "keywords": ["蓝牙耳机"],
    "maxResultsPerKeyword": 100,
    "parallelSearches": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("apt_marble/taobao-search-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 '{
  "keywords": [
    "蓝牙耳机"
  ],
  "maxResultsPerKeyword": 100,
  "parallelSearches": 3
}' |
apify call apt_marble/taobao-search-scraper --silent --output-dataset

```

## MCP server setup

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