{ "openapi": "3.0.1", "info": { "title": "Taobao & Tmall Products Scraper", "description": "Scrape Taobao & Tmall products by keyword, province, category, shop or product URL: title, price, discount, shop, shop rating, images. No login. Export to JSON, CSV or Excel.", "version": "0.0", "x-build-id": "eW8uQ1FUFBWkgeMHy" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/nice_dev~taobao-products-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-nice_dev-taobao-products-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/nice_dev~taobao-products-scraper/runs": { "post": { "operationId": "runs-sync-nice_dev-taobao-products-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/nice_dev~taobao-products-scraper/run-sync": { "post": { "operationId": "run-sync-nice_dev-taobao-products-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "startUrls": { "title": "Taobao / Tmall URLs", "maxItems": 1000, "type": "array", "description": "Any mix of: keyword pages (`https://www.taobao.com/list/product/蓝牙耳机.htm`, or a search link such as `https://s.taobao.com/search?q=iphone`, read as its keyword), category pages (`https://www.taobao.com/list/category/50005050.htm`), shop pages (`https://world.taobao.com/dianpu/239494884.htm`) and product pages (`https://item.taobao.com/item.htm?id=1042700373143`, `https://detail.tmall.com/item.htm?id=1042700373143`, `https://world.taobao.com/item/1042700373143.htm`, or e.tb.cn / m.tb.cn share links). When this list is not empty, the keyword fields below are ignored; filters, caps and monitoring still apply. Max 1 000 URLs.", "default": [], "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "query": { "title": "Search keyword", "maxLength": 200, "type": "string", "description": "Keyword, as typed on Taobao. Chinese keywords work best (e.g. `蓝牙耳机` = Bluetooth earphones); short English words like `iphone` or `sneakers` work too. Taobao publishes a public page for common product terms only: a keyword without one returns nothing and is named in the run log (not charged)." }, "searchQueries": { "title": "More search keywords", "maxItems": 100, "uniqueItems": true, "type": "array", "description": "Several keywords in one run: one search per keyword (times each province below, max 500 searches). Added to **Search keyword**; products found by several searches are saved once.", "default": [], "items": { "type": "string" } }, "location": { "title": "Ships from (province)", "maxLength": 200, "type": "string", "description": "Only products shipped from this Chinese province, as Taobao lists them (e.g. `广东` / `Guangdong`, `浙江` / `Zhejiang`, `上海` / `Shanghai`): Taobao's own 'province' filter. Empty = all of China." }, "locations": { "title": "More provinces", "maxItems": 100, "uniqueItems": true, "type": "array", "description": "Several provinces in one run: every keyword is searched in every province (3 keywords × 4 provinces = 12 searches, max 500). Added to **Ships from (province)**.", "default": [], "items": { "type": "string" } }, "categoryIds": { "title": "Category IDs", "maxItems": 100, "uniqueItems": true, "type": "array", "description": "Taobao category numbers, read in a category URL (`/category/50005050.htm` → `50005050`) or in the `categoryId` field of a previous run. Use the most precise category: a top-level category (e.g. `50011972`) has no public page.", "default": [], "items": { "type": "string" } }, "shopIds": { "title": "Shop IDs", "maxItems": 500, "uniqueItems": true, "type": "array", "description": "Taobao / Tmall shop numbers (the `shopId` field of a previous run, or the number in a `world.taobao.com/dianpu/239494884.htm` URL): the shop's listed products (up to 60 per shop).", "default": [], "items": { "type": "string" } }, "productUrls": { "title": "Product URLs or IDs", "maxItems": 1000, "uniqueItems": true, "type": "array", "description": "Single products to read, as URLs (`https://item.taobao.com/item.htm?id=1042700373143`, `https://detail.tmall.com/item.htm?id=1042700373143`, e.tb.cn share links) or bare product IDs (`1042700373143`). Each one is read from its product page, so it is charged as a product with **Product page** (see Pricing). Affiliate links (s.click.taobao.com) need a Taobao login and are skipped with a log line.", "default": [], "items": { "type": "string" } }, "maxItems": { "title": "Max products", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Maximum number of products to save for the whole run (after deduplication and filters). 0 = no limit.", "default": 100 }, "maxItemsPerQuery": { "title": "Max products per search", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Cap for EACH search (keyword, category, shop or search URL), so that the first search cannot use up the whole **Max products** budget. 0 = no per-search cap.", "default": 0 }, "deepScan": { "title": "Go past the first 20 results", "type": "boolean", "description": "Without an account, Taobao shows 20 products per keyword or category page and no page 2. On: the Actor reads the same search again in several orders, price ranges and brands, and keeps the new products each time, so a search returns hundreds of products instead of 20. On a small catalogue, some of the extra products may only have your keyword in their title: Taobao widens the search. The province filter is approximate too: about 2 products in 15 ship from another province. Off = 20 per keyword or category (faster). No fee of its own: you pay per product saved (with a filter on, each product it drops pays its filter fee, and more products are read).", "default": true }, "sortBy": { "title": "Sort", "enum": [ "sales", "price-desc", "default" ], "type": "string", "description": "Order of the search results, as on Taobao. Taobao has no 'lowest price first' order on these pages (it returns nothing): use **Max price** instead. Taobao has no 'newest' order: use **Only new products** below to get the new ones at each run.", "default": "sales" }, "minPrice": { "title": "Min price (CNY)", "minimum": 0, "maximum": 100000000, "type": "number", "description": "Only products from this price, in Chinese yuan (CNY). Sent to Taobao and checked again on each product." }, "maxPrice": { "title": "Max price (CNY)", "minimum": 0, "maximum": 100000000, "type": "number", "description": "Only products up to this price, in Chinese yuan (CNY). Sent to Taobao and checked again on each product. Empty or 0 = no maximum." }, "freeShippingOnly": { "title": "Free shipping only", "type": "boolean", "description": "Taobao filter 'free shipping' (包邮, within mainland China). Applied to keyword and category searches.", "default": false }, "language": { "title": "Chinese script", "enum": [ "zh-CN", "zh-TW" ], "type": "string", "description": "Script of the titles and shop names: simplified Chinese (mainland China, as the sellers write them) or traditional Chinese (Hong Kong, Taiwan). Prices are the same.", "default": "zh-CN" }, "extractDetails": { "title": "Product page", "type": "boolean", "description": "Read each product's page (1 extra request per product): Taobao or Tmall, ship-from city, original and promotion price, seller type and credit level, shop opening date and number of products, the shop's 3 scores against its category, the share of positive / neutral / negative buyer ratings, payment methods and the coupon link. Charged per product read (event `item-details`).", "default": false }, "includeReviews": { "title": "Latest review and review keywords", "type": "boolean", "description": "Add the latest buyer review shown on the product page (rating, text, date, variant bought, follow-up review, photo URLs) and the review keywords with how many buyers used them (e.g. `long battery life: 330`). Reads the product page, so it turns **Product page** on. Charged per product that has them (event `review`). Taobao shows only this one review without a login.", "default": false }, "includeShopProfile": { "title": "One row per shop", "type": "boolean", "description": "Add one row per shop (`type` = `shop`): shop name and logo, seller ID, the shop's 3 scores and the size of its whole catalogue. For the shops listed above, and also for each shop of the products found (1 extra request per shop). Charged per shop row (event `shop`).", "default": false }, "excludeKeywords": { "title": "Exclude keywords", "maxItems": 50, "uniqueItems": true, "type": "array", "description": "Drop the products whose title contains one of these words (case ignored; simplified and traditional Chinese both matched).", "default": [], "items": { "type": "string" } }, "minRating": { "title": "Min shop score", "minimum": 0, "maximum": 5, "type": "number", "description": "Only products whose shop scores at least this for 'item as described' (out of 5, e.g. `4.8`), as shown in the search results. Products without a score are dropped." }, "tmallOnly": { "title": "Tmall only", "type": "boolean", "description": "Only products sold by Tmall shops (brand and official stores). Taobao shows it on the product page only: needs **Product page** (without it this filter is ignored). A dropped product is charged a detail filter fee (see Pricing).", "default": false }, "onlyNew": { "title": "Only new products", "type": "boolean", "description": "Skip the products that a previous run (same **Memory key**) already delivered: they are not saved and not charged, and their page is not even opened. First run = everything is new. \"New\" means never delivered to you, not newly listed: Taobao has no listing date, so a later run can bring older products the earlier runs did not reach.", "default": false }, "includePriceChanges": { "title": "Also products whose price changed", "type": "boolean", "description": "With **Only new products**: also return the products already delivered whose price went up or down since the last run, with the previous price and the change in %. Charged per changed product (event `price-change`).", "default": false }, "minPriceChangePercent": { "title": "Min price change (%)", "minimum": 0, "maximum": 100, "type": "number", "description": "With **Also products whose price changed**: a product comes back only if its price (`price`, CNY) moved by at least this many % since the last time it was delivered.", "default": 3 }, "stateKey": { "title": "Memory key", "pattern": "^[a-zA-Z0-9_-]{1,64}$", "maxLength": 64, "type": "string", "description": "Name of the memory used by **Only new products**. Give each schedule / task its own key (e.g. `earphones-tmall`) so that they do not share their memory. Letters, digits, `-` and `_`.", "default": "default" }, "resetState": { "title": "Reset the memory", "type": "boolean", "description": "Forget everything remembered under this **Memory key** before the run: this run returns (and charges) every product again. Untick it afterwards.", "default": false }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Apify Proxy or your own proxies. Keep the default: it is included in the price, and the Actor switches IP by itself when Taobao turns one away. Sorting, price, province and free-shipping filters and **Go past the first 20 results** go through the Actor's own connections, also included in the price. The residential Apify proxy is not available in this Actor.", "default": { "useApifyProxy": true } }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 50, "type": "integer", "description": "Maximum number of requests processed in parallel.", "default": 5 }, "maxRequestsPerMinute": { "title": "Max requests per minute", "minimum": 10, "maximum": 2000, "type": "integer", "description": "Most requests to Taobao in any 60 seconds, all of them counted: search pages, product pages and shop pages. A budget, not an even pace: up to this many can leave at once when the minute starts (spread them with the minimum delay below). Lower it if the log shows many 'turned away' lines.", "default": 120 }, "minRequestIntervalMs": { "title": "Min delay between requests", "minimum": 0, "maximum": 60000, "type": "integer", "description": "Smallest gap between two requests, in milliseconds. Unlike the per-minute rate, this spreads the requests evenly instead of letting them go out in a burst. 0 = no gap.", "default": 0 }, "maxRequestRetries": { "title": "Max request retries", "minimum": 0, "maximum": 20, "type": "integer", "description": "Retries per request before it is marked as failed. Behind a proxy, a request Taobao turns away is also retried on a new proxy session up to 10 times without using up these retries.", "default": 5 }, "debugLog": { "title": "Debug log", "type": "boolean", "description": "Include debug messages in the run log.", "default": false } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }