{
  "openapi": "3.0.1",
  "info": {
    "title": "Taobao Products Scraper 淘宝 天猫: Best Sellers, Prices, Shops",
    "description": "Scrape Taobao and Tmall (淘宝 天猫) best sellers by keyword or category: full title, price in CNY, promo price, shop, category, image and selling points. Add item details (ships from, seller scores, shop age) or look items up by id. No login, no cookies. Pay per product.",
    "version": "0.1",
    "x-build-id": "ePPufIsk4JcJ4kOBX"
  },
  "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. 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=), or category page links. Each line is sorted into keywords, categories and items for you. The links themselves are never opened: the actor reads the id or word from them and uses the www.taobao.com/list/ 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"
            }
          },
          "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 seller's description, service and logistics scores, shop open date, shop size, payment methods and a recent review. 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": 60,
            "type": "integer",
            "description": "Most products delivered for one keyword or category. Taobao shows at most 20 best sellers and 40 top rated per word, so 60 is the ceiling.",
            "default": 60
          },
          "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}