# Taobao Search API (taobao.search)

- Canonical page: https://everyinfra.com/en/taobao-api/search
- Endpoint: POST https://api.everyinfra.com/api/v1/social with {"platform": "taobao", "action": "search", "params": {...}}
- Price: $0.0135 per call ($13.5 per 1,000 requests); failed calls and empty results are not charged
- Returns: list, default 20, max 20 per call
- Mode: sync; add "mode": "async" for slow tasks

Taobao Search finds Taobao and Tmall listings by `keyword` and returns each product's title, price and currency, units sold, rating, ship-from location, shop name, main image and stock. Use it to see what sells in a category and at what price, for product research, competitor price tracking and category studies.

Narrow by price with `min_price` and `max_price`, order with `sort` (relevance, popularity or price from high to low), and keep only Tmall listings with `tmall_only`. `tmall_only` takes a boolean true or false; a string is rejected before anything is charged. Before comparing `rating` values, check `rating_scale` on the same row, since the maximum differs between platforms.

## Health

- Live health (24h percent, hourly and daily trends): https://api.everyinfra.com/api/v1/social/availability?platform=taobao&action=search

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| keyword | not declared | yes | not declared | Specifies the Taobao or Tmall product search term for the search action. It does not perform an exact search by store name. |
| max_price | not declared | no | not declared | Sets the maximum item price filter for the search action in combination with min_price. It does not control SKU inventory limits. Decimals may be rounded up to a whole number. Searches with a price range cannot be paged. |
| min_price | not declared | no | not declared | Sets the minimum item price filter for the search action. It is not a review score filter or an API fee parameter, and it does not apply to shop, product_detail, reviews, or questions. Decimals may be rounded down to a whole number. Searches with a price range cannot be paged. |
| page | integer | no | not declared | Page number for product search, from 1 to 50, with 20 results per page. Omit it for page 1; each page is billed as one call. Only plain keyword searches can page (no min_price, max_price or tmall_only, and sort omitted or relevance). They are the more reliable way to search, though most rows carry no sales figures or shop name. A page above 1 combined with any of those filters is rejected before charging, so drop those filters to page. limit only sets how many results of that page you get, so keep it at 20 while paging. Rankings update in real time, so neighbouring pages can occasionally repeat a few items; dedupe by id when merging pages. |
| sort | enum: popular / price_desc / relevance | no | not declared | For product search, use relevance (default), popular, or price_desc. Default and relevance searches allow up to 20 results; popular and price_desc allow up to 10 and cannot be paged. Requests above the applicable limit are rejected before charging, and price_asc is not supported. Reviews and questions do not accept sort. For shop, sort applies only when paging with page; see the shop parameters. |
| tmall_only | not declared | no | not declared | Filters product search to Tmall-only items when set to the boolean true and limits the request to 10 results, without paging. Pass a JSON boolean only; strings such as "false" and requests above this limit are rejected before charging. |
| limit | integer (1–20) | no | 20 | The most rows to return in this call, an integer from 1 to 20. The default applies when you leave it out, and a call can return fewer rows. Larger values return 422 before any charge. |

## Response fields (items in `results`)

| field | meaning |
|---|---|
| id | The record's unique ID on the platform. Unique only within one platform; IDs can repeat across platforms. |
| url | Link to the record on the platform. |
| title | Title. null when the platform has no titles (for example text-only posts). |
| price | Price as a number without a currency symbol; see currency. In product_detail, prices (including each skus row's price) are either the CNY price shown on the Taobao page or a CNY price converted from US dollars, which can be about 1–4% above or below the page price; the page price is authoritative. In search, each row's price can be the current page price, the struck-through list price or a promotion price. price_basis says which kind you got. |
| currency | Currency code of the price (for example CNY, USD). If price is present but currency is null, do not assume a currency. |
| price_basis | How price was obtained (present only when there is a price). In product_detail: page is the CNY price shown on the Taobao page; converted is a CNY price converted from US dollars and can be about 1–4% above or below the price on the Taobao page. In search (one per row): page is the current price shown on the Taobao page; list is the struck-through list price, which is above the actual selling price when the item is discounted, sometimes twice as much; promotion is a Taobao affiliate promotion price and is often well below the page price. currency is CNY in every case, and calls for the same product can differ. |
| sold_count | Units sold. In product_detail only part of the calls return it, and that share changes from day to day. |
| rating | Rating. **The scale varies by platform**: rating_scale on the same row gives the maximum (usually 5; Booking, Douban, iQIYI and NAVER use 10). Convert with rating_scale before comparing across platforms, or the comparison can come out backwards. |
| rating_scale | Maximum of rating in the same row: 5 for five-star scales, 10 for ten-point scales. Present only when the row has a rating. |
| location | Ship-from location. For sellers with several warehouses, calls for the same product can show different ship-from locations. |
| shop_name | Shop name. |
| image_url | Image link. Capabilities with several images may return an image_urls array. |
| stock | Stock count. For sellers with several warehouses, calls for the same product can return different stock (and a different ship-from location). In product_detail, when the source gives no stock for the whole product, this is the sum of the SKU stocks. |
| shop_id | Shop ID. |
| sold_text | Sales figure as shown (search), for example 100k+; figures with + or 10k units are rounded displays, not exact sales. |
| original_price | Original (struck-through) price. In product_detail it is empty on most calls. In shop it is the only price: the struck-through figure the listing shows, not the selling price, and it can be well above it; use product_detail for the selling price. |
| coupon_price | Price after coupon: lower than price when a coupon applies, absent otherwise. In product_detail only part of the calls return it (that share changes from day to day), so a missing value does not always mean there is no coupon. |
| discount_type | Discount or campaign type as written (for example flash sale). |
| is_tmall | Whether the store is a Tmall store, as opposed to a regular Taobao shop; the two have different entry requirements and buyer guarantees. In product_detail, some sources do not return it. |
| brand | Brand. |
| category_id | Category ID. |
| seller_credit_level | Seller credit level (a number; higher is better). |
| seller_positive_rate | Seller positive-feedback rate (search), as a percentage: 100 means 100%. |
| shop_score_description | Shop rating for item-as-described, on a 5-point scale. |
| shop_score_service | Shop rating for service, on a 5-point scale. |
| shop_score_delivery | Shop rating for delivery, on a 5-point scale. |
| subtitle | Product subtitle (search), a short selling-point line. |
| search_rank | Position in this search result (search), starting at 1; when paging it keeps counting, so page 3 starts at 41. |
| free_shipping | Whether shipping is free. |
| selling_points | Selling-point tags. |
| review_tags | Review tags, each with tag (the label) and count (how often it was mentioned; may be missing). |
| images | Image links: product photos on product_detail, the buyer's photos on reviews (absent when the review has none). |
| discount_rate | platform-native meaning |
| spu_id | platform-native meaning |
| category_path | Category path (breadcrumb). |
| review_count | Number of reviews, for product and business capabilities. null means not disclosed, not 0. |
| latest_review | platform-native meaning |
| seller_type | Seller type code (product_detail). |
| shop_opened_at | When the shop opened, as written (product_detail). |
| shop_age_years | platform-native meaning |
| shop_item_count | Number of items on sale in the shop (product_detail, search, shop). |
| shop_score_vs_industry | platform-native meaning |
| platform | Source platform identifier, the same as platform in the request (for example xiaohongshu, tiktok). |

## Example

```bash
curl -X POST 'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer $EVERYINFRA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "platform": "taobao",
  "action": "search",
  "params": {
    "keyword": "便携咖啡秤"
  }
}'
```

```python
import os
import requests

response = requests.post(
    "https://api.everyinfra.com/api/v1/social",
    headers={"Authorization": f"Bearer {os.environ['EVERYINFRA_API_KEY']}"},
    json={
        "platform": "taobao",
        "action": "search",
        "params": {
            "keyword": "便携咖啡秤",
        },
    },
    timeout=120,
)
print(response.status_code)
print(response.json())
```

## Response example

Real response to the example request above, captured 2026-10-24T18:28:34Z. `results` and `count` are real with personal information (names, handles, avatars, profile links, contact details) removed; the list keeps the first 2 of 10. `id`, `billing` and `quota` differ on every call, so only their shape is shown.

```text
{
  "id": "req_…",
  "platform": "taobao",
  "action": "search",
  "results": [
    {
      "id": "•••",
      "url": "https://item.taobao.com/item.htm?id=1036557039587",
      "title": "手冲电子称豆盘咖啡称重展示盘咖啡豆粉秤豆碟茶叶茶则茶器便携",
      "price": 59.8,
      "currency": "CNY",
      "location": "浙江 杭州",
      "shop_name": "好货严选工厂",
      "image_url": "https://g.search.alicdn.com/img/bao/uploaded/i4/i2/2206584264218/O1CN01sCMEZhb10YE1chua_!!2206584264218-0-C2M.jpg",
      "stock": 438,
      "shop_id": "2206584264218",
      "sold_text": "1000+",
      "original_price": 59.8,
      "discount_type": "特价秒杀",
      "seller_credit_level": 20,
      "seller_positive_rate": 100,
      "shop_score_description": 4.74,
      "shop_score_service": 4.8,
      "shop_score_delivery": 4.82,
      "subtitle": "",
      "search_rank": 1,
      "images": [
        "https://img.alicdn.com/imgextra/i4/3937219703/O1CN01VRbcrW2LY2B5R9Jq9_!!3937219703-0-C2M.jpg",
        "https://img.alicdn.com/imgextra/i3/3937219703/O1CN01Bs0puN2LY2B58j8Nm_!!3937219703-0-C2M.jpg",
        "https://img.alicdn.com/imgextra/i4/3937219703/O1CN010vTDpb2LY2B5NXjqG_!!3937219703-0-C2M.jpg"
      ],
      "discount_rate": 100,
      "spu_id": "8995243647",
      "platform": "taobao"
    },
    {
      "id": "•••",
      "url": "https://item.taobao.com/item.htm?id=803310769271",
      "title": "Bincoo咖啡电子秤意式专用咖啡豆称重智能手冲迷你便携秤咖啡器具",
      "price": 88,
      "currency": "CNY",
      "shop_name": "bincoo旗舰店",
      "image_url": "https://g.search1.alicdn.com/img/bao/uploaded/i4/i3/4249388314/O1CN013agzRw2BHrr0rcgBA_!!0-item_pic.jpg",
      "stock": 1267,
      "shop_id": "4249388314",
      "sold_text": "1000+",
      "original_price": 128,
      "discount_type": "优惠价",
      "seller_credit_level": 16,
      "seller_positive_rate": 100,
      "shop_score_description": 4.9,
      "shop_score_service": 4.92,
      "shop_score_delivery": 4.93,
      "subtitle": "",
      "search_rank": 2,
      "images": [
        "https://img.alicdn.com/imgextra/i1/4249388314/O1CN01ZKqJQV2BHrqxP8GFJ_!!4249388314.jpg",
        "https://img.alicdn.com/imgextra/i2/4249388314/O1CN01tX38az2BHrqz5tjuQ_!!4249388314.jpg",
        "https://img.alicdn.com/imgextra/i1/4249388314/O1CN01Jddc8c2BHrqyzT1fk_!!4249388314.jpg"
      ],
      "discount_rate": 68.75,
      "spu_id": "7410827142",
      "platform": "taobao"
    }
  ],
  "count": 10,
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## FAQ

### Can I page through more results?

Yes, with `page`: pages 1 to 50, 20 results each, and each page is billed as one call; leaving it out means page 1. Paging works only for plain keyword searches, meaning no `min_price`, `max_price` or `tmall_only` and `sort` omitted or set to `relevance`. That is the more reliable way to search, though most rows carry no sales figures or shop name. Searches with a price range or `sort=popular` can include sales figures, but they return at most 10 or 20 results and cannot page, so a `page` above 1 with them is rejected before anything is charged. Rankings update in real time, so neighbouring pages can occasionally repeat a few items; dedupe by `id` when you merge pages.

### Which orders does `sort` support?

`relevance` (the default), `popular` and `price_desc`, which lists the most expensive first; there is no cheapest-first order today. Sorting by popularity or price returns at most 10 results per call and cannot page; for more results, run a plain keyword search without `sort` and page with `page`.

### How do the price filters work?

`min_price` and `max_price` bound the product price, and you can pass either one alone. They apply to product search only, not to ratings or call costs. `price` comes back without a currency symbol; read the currency from `currency`.

## Also

- Capability catalog (no key): https://api.everyinfra.com/api/v1/social/catalog?platform=taobao
- OpenAPI: https://everyinfra.com/openapi.json · Agents guide: https://everyinfra.com/agents.md
