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, 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 — read that before you plan around them.

Three real rows:

{"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.
• 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

{
  "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.

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.