# Taobao Keyword Suggestions Scraper - 淘宝 Autocomplete (`dami_studio/taobao-keyword-suggestions-scraper`) Actor

Scrape Taobao's search-box autocomplete: the Chinese keywords real shoppers type. 100 per seed, recursive expansion (5,000 in 13s), Tmall demand counts and category IDs. No account, proxy or Chinese IP. $0.085/1,000 keywords, flat on every plan. Keywords, not products.

- **URL**: https://apify.com/dami\_studio/taobao-keyword-suggestions-scraper.md
- **Developed by:** [Dami's Studio](https://apify.com/dami_studio) (community)
- **Categories:** E-commerce, SEO tools
- **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

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

## Taobao Keyword Suggestions Scraper

Pulls the autocomplete list that drops down under Taobao's own search box. Type 蓝牙耳机 on
taobao.com and Taobao offers you 蓝牙耳机政府补贴, 蓝牙耳机超长续航大电量, 蓝牙耳机降噪 and 97 more.
Those are real queries real Chinese shoppers type. This actor collects them in bulk.

It is a **keyword research tool**. It does not return products, prices, sellers or reviews — see
[What this does not do](#what-this-does-not-do), which is the most important section in this file.

Useful if you are picking product titles for a Taobao or Tmall listing, sizing demand for a category
before you source it, building a Chinese-language SEO or PPC keyword set, or feeding a translation
pipeline with the phrasing shoppers actually use rather than the phrasing a dictionary suggests.

***

### What you get

One row per unique keyword. From a real 5,000-keyword run (12 seed terms, expansion depth 1):

| Field | Coverage | Example |
|---|---|---|
| `keyword` | 100% | `蓝牙耳机政府补贴` |
| `parentQuery` | 100% | `蓝牙耳机` |
| `seedKeyword` | 100% | `蓝牙耳机` |
| `depth` | 100% | `0` |
| `rank` | 100% | `1` |
| `source` | 100% | `suggest` or `tmall-b2c` |
| `scrapedAt` | 100% | `2026-08-09T17:25:24.353Z` |
| `demandCount` | 0.5% overall — **100% of `tmall-b2c` rows** | `68` |
| `relevanceScore` | 0.5% overall — **100% of `tmall-b2c` rows** | `0.84` |
| `categoryIds` | 0.5% overall — **100% of `tmall-b2c` rows** | `["3224662070"]` |
| `refinementTags` (opt-in) | 26.1% overall; 83.1% of depth-0 rows | `[{"tag":"挂耳式","isHot":true}, …]` |

Those percentages are counted from the run, not estimated. The three sparse fields are explained
under [About the demand numbers](#about-the-demand-numbers) — read that before you plan around them.

Three real rows:

```json
{"keyword":"蓝牙耳机政府补贴","parentQuery":"蓝牙耳机","seedKeyword":"蓝牙耳机","depth":0,"rank":1,
 "source":"suggest","demandCount":null,"relevanceScore":null,"categoryIds":[]}

{"keyword":"索尼蓝牙耳机","parentQuery":"蓝牙耳机","seedKeyword":"蓝牙耳机","depth":0,"rank":1,
 "source":"tmall-b2c","demandCount":68,"relevanceScore":0.84,"categoryIds":["3224662070"]}

{"keyword":"蓝牙耳机政府补贴漫步者","parentQuery":"蓝牙耳机政府补贴","seedKeyword":"蓝牙耳机","depth":1,
 "rank":9,"source":"suggest","demandCount":null,"relevanceScore":null,"categoryIds":[]}
```

`rank` is the position Taobao itself put the suggestion in. Taobao does not publish a search volume
for these, and the actor does not invent one — position is the ordering signal, nothing more.

***

### What this does not do

Please read this before buying. It is the difference between this actor being useful to you and
being useless to you.

- **It is not Taobao product search.** You cannot get products, prices, images, SKUs, stock, seller
  names or ratings from it. Taobao's keyword search API (`mtop.taobao.wsearch.appsearch`) sits behind
  an authentication gate that answers `RGV587_ERROR::SM` and redirects to `login.taobao.com` on every
  version, host and referer we tested, from four different countries including a mainland-China
  address. If you need products, use a product scraper instead — ours is
  [Taobao Category Products Scraper](https://apify.com/dami_studio/taobao-category-products-scraper).
- **It is not search volume.** `demandCount` is Taobao's own relative counter on the Tmall
  suggestion list, not a monthly search volume, and it is present on a small minority of rows.
- **It is not a trend or history tool.** Every row is a snapshot of right now. Re-run it on a
  schedule if you want a time series.
- **It does not translate.** Keywords come back in Chinese, because that is the language Taobao's
  suggestion index is built in.
- **English seeds return almost nothing.** `bluetooth earphones` returns an empty list where
  `蓝牙耳机` returns 100 keywords. Seed it in Chinese.

***

### Input

```json
{
  "seedKeywords": ["蓝牙耳机", "连衣裙"],
  "expansionDepth": 0,
  "maxKeywords": 1000,
  "includeDemandData": true,
  "includeRefinementTags": false
}
```

| Option | What it does |
|---|---|
| `seedKeywords` | Terms to expand. Each returns up to 100 suggestions. Short broad terms return the most. |
| `expansionDepth` | `0` asks only about your seeds. `1` also asks about every suggestion that came back — roughly 100x more keywords. `2` goes one level deeper again. |
| `maxKeywords` | Hard cap on unique keywords. This is your spend control. |
| `includeDemandData` | Adds one request per seed against the Tmall suggestion list, the only source of `demandCount` and `categoryIds`. |
| `includeRefinementTags` | Attaches Taobao's attribute/brand vocabulary for the parent query to each row. Off by default because it repeats on every row of a query. |
| `maxConcurrency` | Requests in flight. Default 15. |
| `proxyConfiguration` | Optional and normally pointless — see below. |

Duplicates are removed across the whole run. A keyword that shows up under three different parents
is returned once and charged once.

***

### Depth, and why there is no page 2

Taobao returns **at most 100 suggestions per query** and offers no pagination — no `page`, no
`offset`, no `start`. We measured this directly: asking for 150, 200, 500 and 1,000 all returned
exactly 100 rows in a byte-identical 6,777-byte response.

So depth comes only from re-seeding: take the suggestions, ask Taobao about each of those, repeat.
That is what `expansionDepth` does. Measured yield at depth 1 was **68 new keywords per request**,
and 12 seeds reached the 5,000-keyword cap in 115 requests and 13 seconds.

Plan for the shape of it: depth 0 gives you a clean ~100 keywords per seed. Depth 1 gives you
thousands and they get long-tail fast. Depth 2 gets very large — set `maxKeywords` deliberately.

***

### About the demand numbers

Taobao runs a second, Tmall/B2C suggestion list. It is short, but every row on it carries a real
numeric count, a Taobao category id and a relevance score. That is the only numeric signal available
anywhere on this endpoint, so the actor fetches it for your seed keywords.

It is genuinely sparse and we would rather you knew that up front:

- It answered for **31 of 60** head terms we tested (52%), returning 1–11 rows each.
- It answered for **2 of 300** expanded long-tail terms (0.7%). That is why the actor does not spend
  a request on it past depth 0 — it would double the request count to add almost nothing.
- Across the 5,000-row run it filled 26 rows (0.5%).
- Where it does answer, the numbers are real and they vary: 洗发水 returned 去屑洗发水 at 236,
  防脱洗发水 at 84, 洗发水资生堂 at 18. Observed range across the run: 5 to 268.

Two fields that exist in the raw response are **deliberately not shipped**, because shipping them
would be lying:

- the second element of a standard suggestion row looks like a popularity weight. It is the string
  `"100"` on **54,228 of 54,228** rows we harvested. It is a constant.
- a `tmall` echo field appears on **0.5%** of responses and carries no information the row does not
  already have.

***

### Speed, rate limits and proxies

`suggest.taobao.com` did not rate-limit us at all. Measured: **1,200 consecutive requests through a
single datacenter address at 50 requests/second, 1,200 successes, zero failures, zero throttling,
zero challenges.** A separate 320-request run on another address was also clean.

Consequences, all of which are in your favour:

- **No proxy is used by default.** The actor runs from its own address, so there is no proxy line on
  your bill. `proxyConfiguration` exists if you want the traffic to leave from somewhere specific,
  but you almost certainly do not need it.
- **No Chinese IP is needed.** This endpoint answers identically from a home connection in Canada and
  from US datacenter addresses.
- **No login, no cookies, no token, no signature, no browser.** It is a plain GET returning JSON.

The actor still handles being wrong about this: it retries three times, rotates across whatever
addresses it has, and if the endpoint ever starts serving Alibaba's challenge page instead of JSON,
it says so in an uncharged diagnostic row rather than reporting an empty success.

***

### Reliability, honestly

The one dependency worth flagging: `n=100`, `area=c2c` and `area=b2c` are **undocumented query
parameters** on a public endpoint. They are not part of a published API and Taobao can change or
remove them without notice. If `n` stopped being honoured, runs would return 10 keywords per query
instead of 100. If the JSON shape changed, the actor fails loudly — it raises an error and marks the
run as failed rather than quietly returning nothing, and you are not charged for rows it did not
return.

What we already know breaks and how it is handled:

| Situation | What the actor does | Charged? |
|---|---|---|
| No seed keywords supplied | One labelled sample row | No |
| A term Taobao has no suggestions for (8.5% of long-tail terms) | `NO_SUGGESTIONS` diagnostic row | No |
| A request fails or times out | Retries 3x, then a `QUERY_FAILED` diagnostic row | No |
| Every request fails | Run fails with the underlying error | No |
| A keyword already returned earlier in the run | Skipped | No |

***

### Pricing

**$0.085 per 1,000 keywords**, plus $0.001 when a run starts. You are charged once per unique
keyword actually returned. Sample rows, diagnostic rows and duplicates are never charged.

Real runs, real invoices:

| Run | Keywords returned | Charged events | Cost to you |
|---|---|---|---|
| Empty input | 0 (one sample row) | 0 | $0.001 |
| 2 seeds, depth 0 | 201 | 201 | $0.018 |
| 12 seeds, depth 1 | 5,000 | 5,000 | $0.426 |

The rate is flat: $0.085 per 1,000 on the free plan and $0.085 per 1,000 on every paid plan. No
volume tiers to reach, no minimum spend, no subscription, no proxy line on the bill. What you read
here is what a run costs on day one and on day four hundred.

One caveat worth stating plainly: keywords are not products. If what you actually need is prices,
images or sellers, a keyword feed is the wrong purchase however cheap it is.

***

### FAQ

**Does this scrape Taobao search results or products?**
No. It returns keywords only — the autocomplete suggestions from Taobao's search box. No products,
prices, images or sellers. Taobao's product search API requires a logged-in account, which this
actor does not use and does not ask you for.

**Do I need a Taobao account, cookies, or an API key?**
No. Nothing. The endpoint is public and unauthenticated.

**Do I need a proxy or a Chinese IP address?**
No. It runs without a proxy by default and works from anywhere. That is why it is cheap.

**Can I use English keywords?**
You can, but you will get very little. Taobao's suggestion index is Chinese. `蓝牙耳机` returns 100
suggestions; `bluetooth earphones` returns none. Translate your seeds first.

**How many keywords will I get from one seed?**
Up to 100 at depth 0. At depth 1 expect roughly 68 new keywords per request on top of that. Twelve
seeds at depth 1 hit 5,000 keywords in 13 seconds.

**Why is `demandCount` empty on most rows?**
Because Taobao only publishes it on its short Tmall suggestion list, which answers for about half of
head terms and almost no long-tail terms. Every row where `source` is `tmall-b2c` has it. See
[About the demand numbers](#about-the-demand-numbers).

**Is there a search volume field?**
No. Taobao does not expose search volume on this endpoint, so there is none to hand you.
`demandCount` is a relative counter on a subset of rows, and `rank` is Taobao's own ordering.

**How fast is it?**
5,000 keywords in 13 seconds, measured. 115 requests at roughly 50 per second.

**What is `categoryIds` for?**
It is the real Taobao category id (sometimes several, for ambiguous terms) that Taobao associates
with that keyword. Handy for mapping a keyword to where it actually sits in the catalogue.

**Can I run this on a schedule?**
Yes. Suggestions shift as shopping seasons and campaigns change — 蓝牙耳机政府补贴 ("government
subsidy") ranking first is a snapshot of a moment. Weekly runs make a decent trend series.

# Actor input Schema

## `seedKeywords` (type: `array`):

Terms to expand, one per line. Taobao's suggestion index is Chinese — 蓝牙耳机 returns 100 suggestions where "bluetooth earphones" returns none. Short, broad terms return the most. Each seed returns up to 100 suggestions.

## `expansionDepth` (type: `integer`):

0 = only ask Taobao about your seeds, which returns up to 100 keywords per seed. 1 = also ask about every suggestion that came back, roughly 100x more keywords. 2 = one level deeper again, which gets very large. Taobao has no pagination, so re-seeding is the only way to go deeper. Use the keyword cap below to control spend.

## `maxKeywords` (type: `integer`):

Hard cap on unique keywords returned across the whole run. You are charged once per unique keyword; duplicates are never charged twice.

## `includeDemandData` (type: `boolean`):

Adds one extra request per seed keyword against Taobao's Tmall/B2C suggestion list, which is the only variant carrying a numeric demand count, a Taobao category ID and a relevance score. It answers for roughly half of head terms and returns nothing for most long-tail ones, so it is only asked for your seeds — never for expanded keywords.

## `includeRefinementTags` (type: `boolean`):

Attaches Taobao's own attribute and brand refinement vocabulary for the parent query (style, material, brand, with its "hot" markers) to each row. Present for about 80% of short head terms and 13% of expanded long-tail terms. Off by default because it repeats the same list on every row of a query.

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

How many suggestion requests run at once. 1,200 requests from one address measured zero throttling, so the default is safe; lower it only if you are running through a proxy that dislikes bursts.

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

Optional and normally unnecessary. suggest.taobao.com does not rate-limit and does not require a Chinese IP, so the actor runs from its own address by default and you pay no proxy bill. Set this only if you want the traffic to leave from somewhere specific.

## Actor input object example

```json
{
  "seedKeywords": [
    "蓝牙耳机",
    "连衣裙"
  ],
  "maxKeywords": 1000,
  "includeDemandData": true,
  "maxConcurrency": 15,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

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

One row per suggested keyword in the default dataset: the suggestion, its rank and expansion depth, the parent query and seed term, plus Tmall demand counts, category IDs and refinement tags where Taobao exposes them. Empty or blocked runs return a single uncharged row instead.

# 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 = {
    "seedKeywords": [
        "蓝牙耳机",
        "连衣裙"
    ],
    "expansionDepth": 0,
    "maxKeywords": 1000,
    "includeDemandData": true,
    "includeRefinementTags": false,
    "maxConcurrency": 15,
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("dami_studio/taobao-keyword-suggestions-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 = {
    "seedKeywords": [
        "蓝牙耳机",
        "连衣裙",
    ],
    "expansionDepth": 0,
    "maxKeywords": 1000,
    "includeDemandData": True,
    "includeRefinementTags": False,
    "maxConcurrency": 15,
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("dami_studio/taobao-keyword-suggestions-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 '{
  "seedKeywords": [
    "蓝牙耳机",
    "连衣裙"
  ],
  "expansionDepth": 0,
  "maxKeywords": 1000,
  "includeDemandData": true,
  "includeRefinementTags": false,
  "maxConcurrency": 15,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call dami_studio/taobao-keyword-suggestions-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,dami_studio/taobao-keyword-suggestions-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/me8CyfPoV4FS9ZHm0/builds/7vx755dbcrP0IZjLw/openapi.json