# Taobao API for product listings, prices and shops

> Taobao's Open Platform is for partner apps that pass app review. Our Taobao API returns 20 listings per keyword as JSON, at 1 credit a call.

- URL: https://toolzerhub.com/blog/taobao-api
- Published: 2026-11-05
- Publisher: ToolzerHub (we sell the API this post describes)

## Short answer

- Taobao has an API, the Taobao Open Platform, but it is for partners building seller and shopping software, and an app key comes after onboarding and app review.
- It is not a feed of other shops' listings, and Taobao search works in Chinese: an English keyword returned no items at all.
- ToolzerHub's Taobao API returns a keyword's first 20 listings with prices, shops, brands and filters as JSON, plus shop pages, at 1 credit per call.

Taobao has an API, but not one for reading other shops' listings. The Taobao Open Platform is for partners who build software for Taobao sellers and shoppers, and its app key comes after onboarding and app review. To get prices and shops for products you don't sell, you read Taobao's public search and shop pages. Our API does that, and the script below saves each keyword's first page to CSV.

## What Taobao's API is for

The [Taobao Open Platform](https://open.taobao.com/doc.htm?docId=73&docType=1) (TOP) is for outside partners: third-party developers, software service providers and brand merchants. Its more than 10,000 APIs run shopping mini-programs, merchant tools for products, orders and ERP sold in the Taobao service market, and merchants' own back-office systems. Apps go through onboarding and app review, then get an App Key and App Secret. If you build software for your own Taobao shop, TOP is the right route, but it is not a feed of other shops' listings.

## Taobao listings with ToolzerHub

We make ToolzerHub. Our [Taobao API](https://toolzerhub.com/apis/taobao) returns public Taobao data as JSON with one API key. Each route is a `GET` with the `x-api-key` header at 1 credit a call:

- `/v1/taobao/search?keyword=...` returns one page of listings, with brands, filters and the category path.
- `/v1/taobao/category?category_id_or_url=...` works from a category id or link, such as the `category_id` on each listing.
- `/v1/taobao/shop?shop_id_or_url=...` returns a shop's ratings, item count and items.

```bash
export TOOLZERHUB_API_KEY=your_key
curl -G -H "x-api-key: $TOOLZERHUB_API_KEY" \
  --data-urlencode "keyword=手机壳" \
  "https://api.toolzerhub.com/v1/taobao/search"
```

A UGREEN listing in `data.items` for 手机壳 (phone case), trimmed:

```json
{
  "item_id": "582890145005",
  "title": "绿联适用苹果iPhone18ProMax气囊柔盾17手机壳防摔16Pro透明保护套全包+15镜头14超薄13软壳散热高级12xr11",
  "url": "https://item.taobao.com/item.htm?id=582890145005",
  "price": 29.9,
  "currency": "CNY",
  "price_hkd": 35.5,
  "price_twd": 148.62,
  "price_label": "热销款",
  "selling_points": ["全面防护 双C大气囊防摔", "军工级认证 升级气囊防摔"],
  "shop_id": "67095450",
  "shop_name": "绿联数码旗舰店",
  "category_id": "150704",
  "root_category_id": "50008090",
  "description_match_score": 4.87
}
```

The same call returns 17 brands with listing counts and filters such as 适用品牌 (compatible brand), from Apple/苹果 to Motorola. Search in Chinese: `mechanical keyboard` returned no items, while 机械键盘 returned 20.

## Save Taobao search results to CSV

The script takes Chinese keywords, calls search once per keyword and writes each first page to one CSV: rank, item_id, title, price, currency, price_label, shop, description_match_score and link. It prints a line per keyword with total results, median price, flagship stores and distinct shops. Save it as `taobao_search.py` and install `requests` (`pip install requests`).

```python
import csv
import os
import statistics
import sys
import time

import requests

BASE = "https://api.toolzerhub.com/v1/taobao"
HEADERS = {"x-api-key": os.environ.get("TOOLZERHUB_API_KEY", "")}
FIELDS = ["keyword", "rank", "item_id", "title", "price", "currency", "price_label",
          "shop_id", "shop_name", "description_match_score", "url"]


def get(path, params, tries=3):
    for attempt in range(tries):
        r = requests.get(f"{BASE}/{path}", headers=HEADERS, params=params, timeout=90)
        if r.status_code in (429, 500, 502, 503, 504) and attempt < tries - 1:
            time.sleep(10 * (attempt + 1))
            continue
        r.raise_for_status()
        return r.json()["data"]


def main(keywords, out="taobao_search.csv"):
    with open(out, "w", newline="", encoding="utf-8-sig") as f:
        writer = csv.DictWriter(f, fieldnames=FIELDS)
        writer.writeheader()
        for keyword in keywords:
            data = get("search", {"keyword": keyword})  # one page of about 20 listings
            items = data["items"]
            if not items:  # English keywords return nothing; search in Chinese
                print(f"{keyword}: no listings")
                continue
            for rank, it in enumerate(items, 1):
                writer.writerow({"keyword": keyword, "rank": rank,
                                 **{k: it.get(k) for k in FIELDS if k not in ("keyword", "rank")}})
            prices = [it["price"] for it in items if it.get("price")]
            flagship = sum("旗舰店" in (it.get("shop_name") or "") for it in items)  # brand flagship stores
            print(f"{keyword}: {data['total_results']} results, {len(items)} saved, "
                  f"median {statistics.median(prices)} CNY, {flagship} from flagship stores, "
                  f"{len({it['shop_id'] for it in items})} shops")
    print(f"saved to {out}")


if __name__ == "__main__":
    if len(sys.argv) < 2:
        sys.exit("usage: python taobao_search.py 机械键盘 蓝牙耳机 ...")
    if not HEADERS["x-api-key"]:
        sys.exit("set TOOLZERHUB_API_KEY first")
    main(sys.argv[1:])
```

`python taobao_search.py 机械键盘 蓝牙耳机 手机壳 咖啡豆 瑜伽垫` saved 100 listings in 5 calls and 13.9 seconds.

## What the first pages showed

The first page of Taobao search is mostly brand flagship stores: 56 of 100 rows. "Flagship" counts shop names that contain 旗舰店:

| Keyword | Results | Median (CNY) | Range (CNY) | Flagship of 20 | Shops |
|---|---|---|---|---|---|
| 机械键盘 mechanical keyboard | 17,766 | 299 | 39 to 999 | 11 | 15 |
| 蓝牙耳机 Bluetooth earbuds | 35,045 | 214 | 39.4 to 9,999 | 10 | 19 |
| 手机壳 phone case | 21,117 | 57.4 | 27.5 to 1,152 | 18 | 14 |
| 咖啡豆 coffee beans | 10,067 | 107 | 29.9 to 249 | 6 | 14 |
| 瑜伽垫 yoga mat | 7,081 | 54.45 | 15.9 to 129 | 11 | 14 |

Coffee beans had the fewest flagships, but 天猫超市 (Tmall Supermarket) ranked #1 at 198 CNY and filled 7 of the 20 coffee rows. The 9,999 CNY top of the earbuds range is a Huawei FreeBuds SE 4 listing, so compare medians, not averages.

优惠价 (discount price) was the most common `price_label`, and `price_label` came back as `"0"` on 14 of 100 rows, so treat that as no label.

The #1 phone case, at 29.9 CNY, comes from 绿联数码旗舰店, the UGREEN flagship. A shop call on its `shop_id`, 67095450, returned description 4.8, service 4.8 and delivery 4.9, with 1,304 items and 60 on the first page.

## What it costs

Each keyword is one call and 1 credit, so the five keywords above cost 5 credits and a daily check of 20 keywords is about 600 a month. The 100 free credits a month cover your first tests; $19 buys 10,000 credits that never expire, and [plans for higher volume](https://toolzerhub.com/pricing) cover larger keyword lists. Set your key and run the script on your own keywords; the first CSV is ready in seconds.

For other marketplace prices, see our [Ozon price parser in Python](https://toolzerhub.com/blog/ozon-price-parser-python); for another Chinese platform, see [Xiaohongshu search API in Python](https://toolzerhub.com/blog/xiaohongshu-search-api-python).

For shopping data from Korea, see the [Naver Shopping API](https://toolzerhub.com/blog/naver-shopping-api).

We are not affiliated with Taobao.
