{
  "openapi": "3.0.1",
  "info": {
    "title": "Taobao Scraper: Taobao Products and Tmall Best Sellers, Prices",
    "description": "Taobao scraper for 淘宝 and Tmall 天猫 best sellers by keyword, category or item id: title, price in CNY, promo price, shop, category, images and selling points. English keywords are translated for you and prices can be converted to 25 currencies. Item details on request. No login.",
    "version": "0.1",
    "x-build-id": "sJXrSL3cHE9w6hczx"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/themineworks~taobao-products-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-themineworks-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/themineworks~taobao-products-scraper/runs": {
      "post": {
        "operationId": "runs-sync-themineworks-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/themineworks~taobao-products-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-themineworks-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": {
          "keywords": {
            "title": "Keywords",
            "type": "array",
            "description": "One per line: a product word in Chinese (手机壳, 连衣裙, 机械键盘) or in English (phone case, lipstick, wireless earbuds), or a keyword page link. English words are turned into the Chinese word Taobao has a page for (see Translate English keywords). Each gives Taobao's 20 best sellers for the word, plus up to 40 top rated ones, and with Products per keyword above 60 a deep search that goes up to 1,000. Taobao only has pages for common product words; any other word is reported as having no page and costs nothing. Up to 200 per run.",
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "Links and item ids",
            "type": "array",
            "description": "Paste any mix, one per line: Taobao or Tmall product links (item.taobao.com, detail.tmall.com, world.taobao.com, www.taobao.com/list/item), bare item ids, keyword page links (www.taobao.com/list/product, world.taobao.com/product, s.taobao.com/search?q=), category page links, or shop links (shop123456.taobao.com, www.taobao.com/list/dianpu/123456.htm). Each line is sorted into keywords, categories, shops and items for you. The links themselves are never opened: the actor reads the id or word from them and uses Taobao's public pages. Up to 1,000 per run.",
            "items": {
              "type": "string"
            }
          },
          "categories": {
            "title": "Categories",
            "type": "array",
            "description": "One per line: a Taobao category id (150704) or a www.taobao.com/list/category/ link. Each gives the category's 20 best sellers. Category ids are in every row (category_id, root_category_id). Up to 100 per run.",
            "items": {
              "type": "string"
            }
          },
          "shops": {
            "title": "Shops",
            "type": "array",
            "description": "One per line: a Taobao shop id (the number in shop67095450.taobao.com), a shop link (shop67095450.taobao.com, www.taobao.com/list/dianpu/67095450.htm, world.taobao.com/dianpu/67095450.htm). Each gives up to 60 of the shop's products with the shop's name, seller id, its three scores and how many products the whole shop has (shop_profile). A shop.m.taobao.com link with only user_id names the seller, not the shop, and cannot be read. Up to 200 per run.",
            "items": {
              "type": "string"
            }
          },
          "items": {
            "title": "Items",
            "type": "array",
            "description": "One per line: a Taobao item id (971278517006) or any Taobao or Tmall item link that carries the id. Each gives one row with price (and price range), ships from, the seller's three scores, shop age and size, how many buyers reviewed it, what buyers mention most and a recent review. Taobao shortens the title on this page; keyword rows carry the full title. Short m.tb.cn links are not read. Up to 1,000 per run.",
            "items": {
              "type": "string"
            }
          },
          "translateKeywords": {
            "title": "Translate English keywords",
            "type": "boolean",
            "description": "Turn English keywords into the Chinese word Taobao has a page for (a built-in list of verified product words first, then the English word as Taobao itself understands it, then a free translation service). The row keeps your English word in keyword_original. Off: keywords are used exactly as written.",
            "default": true
          },
          "sortBy": {
            "title": "Sort products by",
            "enum": [
              "sales",
              "price_low",
              "price_high",
              "rating"
            ],
            "type": "string",
            "description": "Taobao ranks its lists by sales. The price and score sorts reorder the products read for each keyword (up to 60); Taobao's pages cannot be asked for another order, so they do not reach beyond those 60.",
            "default": "sales"
          },
          "currency": {
            "title": "Also show prices in",
            "enum": [
              "USD",
              "EUR",
              "GBP",
              "INR",
              "JPY",
              "KRW",
              "AUD",
              "CAD",
              "SGD",
              "MYR",
              "THB",
              "IDR",
              "PHP",
              "VND",
              "AED",
              "SAR",
              "BRL",
              "MXN",
              "TRY",
              "PLN",
              "ZAR",
              "RUB",
              "NGN",
              "PKR",
              "BDT",
              "CNY"
            ],
            "type": "string",
            "description": "Adds price_converted and promo_price_converted: the yuan price converted at the day's rate (fx_rate and fx_date are in every row). Taobao's own HKD and TWD prices stay in price_hkd and price_twd. Choose CNY to leave the converted columns empty.",
            "default": "USD"
          },
          "includeTopRated": {
            "title": "Add top rated products",
            "type": "boolean",
            "description": "For each keyword, also read Taobao's top rated list (up to 40 products, about half of them not among the 20 best sellers). Off: only the 20 best sellers.",
            "default": true
          },
          "addItemDetails": {
            "title": "Add item page details",
            "type": "boolean",
            "description": "Open each listed product's item page and add where it ships from, Tmall or Taobao, price range, how many buyers reviewed it and what they mention most, the share of positive, neutral and negative ratings (Taobao shops), the seller's description, service and logistics scores, shop open date, shop size, payment methods, a recent review with its photos, and Taobao's own generated summary where it has one. One more page per product, so the run takes longer. Charged as a separate details event on rows where the item page was read.",
            "default": false
          },
          "freeShippingOnly": {
            "title": "Free shipping only",
            "type": "boolean",
            "description": "Keep only products Taobao marks as free shipping. Products left out are never charged.",
            "default": false
          },
          "maxProductsPerKeyword": {
            "title": "Products per keyword",
            "minimum": 1,
            "maximum": 1000,
            "type": "integer",
            "description": "Most products delivered for one keyword or category. Up to 60 come from Taobao's own best seller and top rated pages. Above 60, each keyword is read again in slices (price bands, sort orders, brands) on Taobao's Singapore keyword pages until this many new products are found or the slices run dry (deep search, needs the option below); 300 to 500 is typical for a common word. Categories stop at 20.",
            "default": 60
          },
          "maxProductsPerShop": {
            "title": "Products per shop",
            "minimum": 1,
            "maximum": 60,
            "type": "integer",
            "description": "Most products delivered for one shop. Taobao's shop page shows up to 60.",
            "default": 60
          },
          "useResidentialProxy": {
            "title": "Retry refused deep search pages on residential proxy",
            "type": "boolean",
            "description": "Deep search pages are tried once on datacenter proxy; when Taobao refuses them they are tried again on a residential proxy, at no extra cost to you. Off: deep search stays on datacenter and returns fewer products when Taobao refuses it.",
            "default": true
          },
          "maxProducts": {
            "title": "Products in all",
            "minimum": 1,
            "maximum": 20000,
            "type": "integer",
            "description": "The run stops once this many products are delivered.",
            "default": 1000
          },
          "minPrice": {
            "title": "Lowest price (CNY)",
            "minimum": 0,
            "type": "integer",
            "description": "Leave out products below this price in yuan (the promo price when there is one). Products left out are never charged."
          },
          "maxPrice": {
            "title": "Highest price (CNY)",
            "minimum": 0,
            "type": "integer",
            "description": "Leave out products above this price in yuan. Products left out are never charged."
          },
          "onlyNewProducts": {
            "title": "Only products not delivered before",
            "type": "boolean",
            "description": "For schedules: remember every product this input delivered and deliver only new ones next time. Products seen before are skipped and never charged. The memory is kept per set of keywords, categories and items.",
            "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}