Taobao Search API

Q: 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, so split broad searches into narrower keywords or price bands.

Q: 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.

Q: Can I search Tmall only?

Yes: set tmall_only to the boolean true (the default is false). It must be a boolean, since the string 'false' is rejected before anything is charged, and with it on each call returns at most 10 results.

POST

API health

24h health: 71%
24h average time: 11.90 s

Healthy / normal
Available
Limited
Mostly down

Available

Last 24 hours

Last 30 days

Search Taobao and Tmall listings by keyword for price, units sold, rating, shop, ship-from location and coupon or discount details. Default and relevance sorts allow up to 20 results, while popular, price_desc and tmall_only cap a request at 10; stock, authenticity and delivery are not confirmed.

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.

Price $1.39 per 1,000 requests ($0.001389 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.

AI prompt

Paste this into your AI assistant. It already holds this endpoint's parameters, response fields and an example request, so the assistant can ask what you need and then write the scraper.

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

Endpoint contract:
- 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.
  - 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.
  - 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. (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. Pass a JSON boolean only; strings such as "false" and requests above this limit are rejected before charging.
  - 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, currency, sold_count (Units sold), rating, rating_scale, location, shop_name (Shop name), image_url, stock (Stock); 30 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: $1.39 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

Name	In	Type	Required	Default	Description
`Authorization`	header	`string`	Yes	-	Bearer followed by your API key. Create it in the console; never put it in a URL or a code repository.
`platform`	body	`string`	Yes	`taobao`	Platform identifier, fixed value.
`action`	body	`string`	Yes	`search`	Capability identifier, fixed value.
`keyword`	body.params	Not declared	Yes	-	Specifies the Taobao or Tmall product search term for the search action. It does not perform an exact search by store name.
`max_price`	body.params	Not declared	No	-	Sets the maximum item price filter for the search action in combination with min_price. It does not control SKU inventory limits.
`min_price`	body.params	Not declared	No	-	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.
`sort`	body.params	`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. Requests above the applicable limit are rejected before charging, and price_asc is not supported. Reviews and questions do not accept sort, and shop does not expose this sort parameter.Allowed values`popularprice_descrelevance`
`tmall_only`	body.params	Not declared	No	-	Filters product search to Tmall-only items when set to the boolean true and limits the request to 10 results. Pass a JSON boolean only; strings such as "false" and requests above this limit are rejected before charging.
`limit`	body.params	`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.

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

Field preview

There is no real sample for these example parameters yet: this shows the response shape and fields from the contract, with … as placeholders. It is not the result of a real call.

json

{
  "id": "req_…",
  "platform": "taobao",
  "action": "search",
  "results": [
    {
      "id": …,
      "url": …,
      "title": …,
      "price": …,
      "currency": …,
      "sold_count": …,
      "rating": …,
      "rating_scale": …,
      "location": …,
      "shop_name": …,
      "image_url": …,
      "stock": …,
      "shop_id": …,
      "sold_text": …,
      "original_price": …,
      "coupon_price": …,
      "discount_type": …,
      "is_tmall": …,
      "brand": …,
      "category_id": …,
      "seller_credit_level": …,
      "seller_positive_rate": …,
      "shop_score_description": …,
      "shop_score_service": …,
      "shop_score_delivery": …,
      "subtitle": …,
      "search_rank": …,
      "free_shipping": …,
      "selling_points": …,
      "review_tags": …,
      "platform": …
    }
  ],
  "count": …,
  "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.

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.
`currency`	Currency code of the price (for example CNY, USD). If price is present but currency is null, do not assume a currency.
`sold_count`	Units sold.
`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`	Location description passed through as is; the format varies by platform.
`shop_name`	Shop name.
`image_url`	Image link. Capabilities with several images may return an image_urls array.
`stock`	Stock.
`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 price.
`coupon_price`	Price after coupon: lower than price when a coupon applies, absent otherwise.
`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.
`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.
`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).
`platform`	Source platform identifier, the same as platform in the request (for example xiaohongshu, tiktok).

FAQ

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, so split broad searches into narrower keywords or price bands.

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.

Can I search Tmall only?

Yes: set tmall_only to the boolean true (the default is false). It must be a boolean, since the string 'false' is rejected before anything is charged, and with it on each call returns at most 10 results.

Errors and billing

401: Missing or invalid key. Authentication runs before parameter checks, so unauthenticated requests never see the parameter schema.
422: Wrong parameter name or value. The error lists the parameters and allowed values this capability accepts and the closest match; it happens before any charge.
402: Insufficient balance. Top up first.
429: The account's per-minute request limit was reached (all of its API keys count together; a key's own lower limit applies first). Wait for Retry-After and try again; a rate package in the console raises the limit.
503: Could not complete right now. Any charge for the call goes back to your balance automatically, and the billing receipt in the response states the actual outcome, including when it is not yet known. Do not resend blindly.
200 empty: The request completed without data and is not charged (billing.reason = empty_result_refunded).