POST

API health

24h health
99%
24h average time
10.36 s
  • Healthy / normal
  • Available
  • Limited
  • Mostly down
Healthy

Last 24 hours

Last 30 days

Search Taobao and Tmall listings by keyword. Get price and ship-from location, plus units sold, rating, shop and coupon or discount details when available. Plain keyword searches are the most reliable and can page with page, 20 per page, though most of their rows lack units sold and shop name. Price ranges, popular, price_desc and tmall_only cannot page, and the last three cap a request at 10. Stock, authenticity and delivery are not confirmed.

Send POST https://api.everyinfra.com/api/v1/social with platform set to taobao and action set to search. Price $13.5 per 1,000 requests ($0.0135 per call). Failed calls and empty results are not charged. Synchronous. For slow jobs add "mode": "async" to the body, take the job_id and poll.

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.

AI prompt

#
Please help me write a data collection script with the EveryInfra Taobao Search endpoint (taobao/search).

How the endpoint works:
- Request: POST https://api.everyinfra.com/api/v1/social with the header Authorization: Bearer <API key>. Read the key from the EVERYINFRA_API_KEY environment variable and never hard-code it.
- In the request body, set platform to taobao and action to search, and put the parameters inside params.
- Required parameters:
  - keyword: Specifies the Taobao or Tmall product search term for the search action. It does not perform an exact search by store name.
- Optional parameters:
  - max_price: 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: 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.
  - page: 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.
  - sort: 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. (allowed: popular / price_desc / relevance)
  - tmall_only: 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.
  - limit: 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. (default: 20)
- Returns a list of records. Main fields of each record: id, url, title, price (Price as a number without a currency sy…), currency, price_basis (How price was obtained (present only wh…), sold_count (Units sold), rating, rating_scale, location (Ship-from location), shop_name (Shop name), image_url; 42 fields in total, full list at https://api.everyinfra.com/api/v1/social/catalog?platform=taobao.
- Example request body:
{
  "platform": "taobao",
  "action": "search",
  "params": {
    "keyword": "便携咖啡秤"
  }
}
- Price: $13.5 per 1,000 requests; failed and empty results are not charged.
- For dozens or hundreds of targets, add "mode": "async" to the body: you get a job_id at once and poll GET https://api.everyinfra.com/api/v1/jobs/{job_id} for the result.
- On 422, fix the request using the suggested parameter names and allowed values in the error; on 429 or 503, wait for Retry-After and try again.

Before writing code, ask me which targets I need, how many, which fields, and what output format I want; then confirm the plan and the rough cost with me.

Request parameters

#
NameInTypeRequiredDefaultDescription
AuthorizationheaderstringYes-Bearer followed by your API key. Create it in the console; never put it in a URL or a code repository.
platformbodystringYestaobaoPlatform identifier, fixed value.
actionbodystringYessearchCapability identifier, fixed value.
keywordbody.paramsstringYes-Specifies the Taobao or Tmall product search term for the search action. It does not perform an exact search by store name.
max_pricebody.paramsnumberNo-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_pricebody.paramsnumberNo-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.
pagebody.paramsintegerNo-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.
sortbody.paramsstring (enum)No-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.Allowed valuespopularprice_descrelevance
tmall_onlybody.paramsbooleanNo-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.
limitbody.paramsinteger (1–20)No20The 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.

Code samples

#
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": "便携咖啡秤"
  }
}'

OpenAPI definition (JSON)Samples read the key from the EVERYINFRA_API_KEY environment variable; copied code never contains your key.

Response example

#
Captured October 24, 2026 at 18:28 (UTC) by calling this API with the parameters in the code sample above. results and count are that call's real response with personal information (names, handles, avatars, profile links, contact details) removed; the list keeps the first 2. id, billing and quota differ on every call, so only their shape is shown.
json
{  "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": { … }}

Response fields

#

Business data is in results. The table lists the fields a record can contain; values the platform does not show are never made up.

FieldMeaning
idThe record's unique ID on the platform. Unique only within one platform; IDs can repeat across platforms.
urlLink to the record on the platform.
titleTitle. null when the platform has no titles (for example text-only posts).
pricePrice 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.
currencyCurrency code of the price (for example CNY, USD). If price is present but currency is null, do not assume a currency.
price_basisHow 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_countUnits sold. In product_detail only part of the calls return it, and that share changes from day to day.
ratingRating. 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_scaleMaximum of rating in the same row: 5 for five-star scales, 10 for ten-point scales. Present only when the row has a rating.
locationShip-from location. For sellers with several warehouses, calls for the same product can show different ship-from locations.
shop_nameShop name.
image_urlImage link. Capabilities with several images may return an image_urls array.
stockStock 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_idShop ID.
sold_textSales figure as shown (search), for example 100k+; figures with + or 10k units are rounded displays, not exact sales.
original_priceOriginal (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_pricePrice 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_typeDiscount or campaign type as written (for example flash sale).
is_tmallWhether 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.
brandBrand.
category_idCategory ID.
seller_credit_levelSeller credit level (a number; higher is better).
seller_positive_rateSeller positive-feedback rate (search), as a percentage: 100 means 100%.
shop_score_descriptionShop rating for item-as-described, on a 5-point scale.
shop_score_serviceShop rating for service, on a 5-point scale.
shop_score_deliveryShop rating for delivery, on a 5-point scale.
subtitleProduct subtitle (search), a short selling-point line.
search_rankPosition in this search result (search), starting at 1; when paging it keeps counting, so page 3 starts at 41.
free_shippingWhether shipping is free.
selling_pointsSelling-point tags.
review_tagsReview tags, each with tag (the label) and count (how often it was mentioned; may be missing).
imagesImage links: product photos on product_detail, the buyer's photos on reviews (absent when the review has none).
discount_rateKeeps the platform's own meaning
spu_idKeeps the platform's own meaning
category_pathCategory path (breadcrumb).
review_countNumber of reviews, for product and business capabilities. null means not disclosed, not 0.
latest_reviewKeeps the platform's own meaning
seller_typeSeller type code (product_detail).
shop_opened_atWhen the shop opened, as written (product_detail).
shop_age_yearsKeeps the platform's own meaning
shop_item_countNumber of items on sale in the shop (product_detail, search, shop).
shop_score_vs_industryKeeps the platform's own meaning
platformSource platform identifier, the same as platform in the request (for example xiaohongshu, tiktok).

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.

Errors and billing

#
401
Missing or invalid key.
402
Insufficient balance. Top up first.
422
Invalid parameter name or value. Fix it using the suggestions in the error. No charge.
429
Per-minute request limit reached. Wait for Retry-After, then try again.
503
Could not complete. The held charge is returned to your balance. If the outcome is unknown, verify it before you retry.
200 empty
No data. No charge.

Errors

Google Analytics needs consent. Privacy