{
  "openapi": "3.0.1",
  "info": {
    "title": "Taobao & Tmall Scraper — Prices, Shops & Ratings",
    "description": "Get Taobao and Tmall search results and product cards with no login: prices in CNY, shop ratings, category ids, discount type and the latest review. 12 storefronts.",
    "version": "0.1",
    "x-build-id": "k0q6oef02Ym9pfpln"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/blueskyscraper~taobao-tmall-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-blueskyscraper-taobao-tmall-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/blueskyscraper~taobao-tmall-scraper/runs": {
      "post": {
        "operationId": "runs-sync-blueskyscraper-taobao-tmall-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/blueskyscraper~taobao-tmall-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-blueskyscraper-taobao-tmall-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": {
          "mode": {
            "title": "Mode",
            "enum": [
              "search",
              "detail"
            ],
            "type": "string",
            "description": "Search: price, shop, store type, category, buyer review tags and pack size from the title for each result. Product cards: Tmall or Taobao, official store status, category path, coupon flag, shop ratings, review count label and the latest review for items found by search.",
            "default": "search"
          },
          "keywords": {
            "title": "Keywords",
            "type": "array",
            "description": "Keywords for the search mode, in Chinese (狗粮) or English (dog food). Each keyword costs one request per selected storefront and sort order. Leave empty if you only use category ids.",
            "items": {
              "type": "string"
            }
          },
          "itemIds": {
            "title": "Item links or itemIdStr",
            "type": "array",
            "description": "For product cards. Takes a link like https://world.taobao.com/item/<itemIdStr>.htm or the itemIdStr itself. A plain numeric id does not open a card, because Taobao answers with an empty shell: use itemIdStr from a search row.",
            "items": {
              "type": "string"
            }
          },
          "categoryIds": {
            "title": "Category ids (search mode)",
            "type": "array",
            "description": "Taobao storefront categories instead of (or next to) keywords: a link like https://world.taobao.com/category/206507001.htm or the number itself. A product card gives you these ids in frontCategoryIds. With the sort order \"Newest first\" and a previous run's dataset this is the weekly list of new products per category (isNew).",
            "items": {
              "type": "string"
            }
          },
          "includeDetails": {
            "title": "Load product cards for found items",
            "type": "boolean",
            "description": "In the search mode, also load the card of every item found: warehouse, Taobao or Tmall, shop ratings, latest review, all photos. The row is charged as a product card.",
            "default": false
          },
          "splitByBrand": {
            "title": "Split results by brand",
            "type": "boolean",
            "description": "Also search every brand Taobao itself lists for the keyword (up to 24, Taobao's own brand filter). Products found this way get brandId and brandName from Taobao — the brand, never the shop name — and you get more products than one result page. One extra request per brand; rows are charged as usual.",
            "default": false
          },
          "maxReviewsPerItem": {
            "title": "Reviews per product",
            "minimum": 0,
            "maximum": 1000,
            "type": "integer",
            "description": "0 = no reviews. Otherwise up to this many of the newest reviews for every product row, each as its own row (type \"review\") right after the product: rating, text, date, photos, the variant the buyer bought, seller reply. Each review row is charged like one search result. Asked in pages of 20; a last page smaller than 3 reviews is not asked. On the Apify Free plan: up to 20 review rows per run.",
            "default": 0
          },
          "paidSalesAndPages": {
            "title": "Paid search: result pages 2+ and sales labels",
            "type": "boolean",
            "description": "Off by default. Adds Taobao result pages 2, 3… for each keyword and, when the margin allows, the popular sort — the only place where Taobao prints a sales label (月销 / 已售), copied word for word into salesLabel with salesCountAtLeast and a caveat that it is a rounded label, not a count. These rows cost $0.0045 each (event sales-search-item); a product you already got for free that gains a sales label becomes such a row. Available from 24 November 2026, not on the Apify Free plan.",
            "default": false
          },
          "maxPaidSearchPages": {
            "title": "Paid result pages per keyword",
            "minimum": 1,
            "maximum": 50,
            "type": "integer",
            "description": "How many paid pages (from page 2) per keyword. A page that brings fewer than 10 new products stops the paging.",
            "default": 3
          },
          "includeSkuDetails": {
            "title": "Full product cards with SKUs",
            "type": "boolean",
            "description": "Off by default. Every product row gets the full card: all SKUs (variants) as a list inside the product with price and stock each, total stock, exact review count, favourites, 7-day return, and — when Taobao gives them — sales, brand, attributes, weight and coupon price. Works for numeric item ids too. Each such row costs $0.015 (event item-sku-detail) instead of its usual price. Available from 24 November 2026, not on the Apify Free plan.",
            "default": false
          },
          "regions": {
            "title": "Storefronts",
            "type": "array",
            "description": "Overseas Taobao storefronts. Each has its own catalog and display currency; the price in yuan is always there. More storefronts give more unique items, and each one is a separate request.",
            "items": {
              "type": "string",
              "enum": [
                "my",
                "sg",
                "th",
                "jp",
                "kr",
                "au",
                "ph",
                "ca",
                "mo",
                "nz",
                "vn",
                "kh"
              ],
              "enumTitles": [
                "Malaysia (my)",
                "Singapore (sg)",
                "Thailand (th)",
                "Japan (jp)",
                "Korea (kr)",
                "Australia (au)",
                "Philippines (ph)",
                "Canada (ca)",
                "Macau (mo)",
                "New Zealand (nz)",
                "Vietnam (vn)",
                "Cambodia (kh)"
              ]
            },
            "default": [
              "my"
            ]
          },
          "sorts": {
            "title": "Sort orders",
            "type": "array",
            "description": "Taobao gives a logged-out visitor only the first result page (18–20 items) for each request; page 2 is closed. Different sort orders show different items, so several sort orders — plus storefronts and \"Split results by brand\" — are the way to go deeper. With \"Sales (highest first)\" every row gets salesRank: its place in Taobao's sales ranking (a rank, not a sales count).",
            "items": {
              "type": "string",
              "enum": [
                "",
                "sales-des",
                "price-asc",
                "price-desc",
                "new-des",
                "bid-des",
                "total-des"
              ],
              "enumTitles": [
                "Relevance",
                "Sales (highest first)",
                "Price (cheapest first)",
                "Price (most expensive first)",
                "Newest first",
                "By bid",
                "Total score"
              ]
            },
            "default": [
              ""
            ]
          },
          "maxItems": {
            "title": "Max rows",
            "type": "integer",
            "description": "The upper limit on rows. One storefront request gives 18-20 items, so the Actor adds more storefronts and, if you did not choose a sort order, more sort orders until this number is reached.",
            "default": 100
          },
          "previousDatasetId": {
            "title": "Previous run dataset",
            "type": "string",
            "description": "Dataset ID of an earlier run. Adds previousPrice, priceChange, priceChangePercent, priceDirection, daysSincePrevious and isNew to every row, so you see how the price moved between runs."
          },
          "requestDelaySecs": {
            "title": "Delay between requests (seconds)",
            "type": "number",
            "description": "Pause between storefront requests. 0.5 seconds is polite and not slow.",
            "default": 0.5
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Usually not needed. Set it only if a storefront starts refusing your address."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}