{
  "openapi": "3.0.1",
  "info": {
    "title": "Taobao & Tmall Product Scraper: Search, Category, Shop",
    "description": "Scrape Taobao and Tmall products by keyword, category or shop from Taobao's public catalogue - no login, no browser. Splits each keyword across sort orders, price bands and brands to return hundreds of unique products, with clean CNY prices, USD conversion, shop scores and search/sales ranks.",
    "version": "0.1",
    "x-build-id": "VZx5mgWfuztu9bjd9"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/kyungminlee~taobao-catalog-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-kyungminlee-taobao-catalog-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/kyungminlee~taobao-catalog-scraper/runs": {
      "post": {
        "operationId": "runs-sync-kyungminlee-taobao-catalog-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/kyungminlee~taobao-catalog-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-kyungminlee-taobao-catalog-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": "Search keywords",
            "type": "array",
            "description": "Products to search for, one keyword per line. Chinese keywords give by far the best results (e.g. `机械键盘`, `手机壳`, `连衣裙`); common English words (`keyboard`, `iphone case`) also work, many English phrases do not. You can also paste a `www.taobao.com/list/product/<keyword>.htm` URL.",
            "items": {
              "type": "string"
            }
          },
          "categoryIds": {
            "title": "Category IDs",
            "type": "array",
            "description": "Optional. Taobao category IDs (e.g. `110210` for keyboards) or `www.taobao.com/list/category/<id>.htm` URLs. The `categoryId` field of any product in the output is such an ID. A category page lists 20 products (up to about 100 when sort orders are available for your proxy).",
            "items": {
              "type": "string"
            }
          },
          "shopIds": {
            "title": "Shop IDs",
            "type": "array",
            "description": "Optional. Taobao shop IDs (the `shopId` field of any product), `www.taobao.com/list/dianpu/<id>.htm` URLs, `shop<id>.taobao.com` URLs or any link containing `shopId=<id>`. Store links that show a name instead (like `brand.tmall.com`) cannot be used - search the store name as a keyword first and copy the `shopId` from any product row. Returns the up to 60 products on the shop's catalogue page plus the shop's service and delivery scores.",
            "items": {
              "type": "string"
            }
          },
          "maxItemsPerQuery": {
            "title": "Max products per query",
            "minimum": 1,
            "maximum": 5000,
            "type": "integer",
            "description": "Maximum number of unique products to return for each keyword, category or shop. One Taobao catalogue page shows only 20-40 products and has no next page, so larger numbers are reached through brand and attribute refinements (see below). A keyword typically yields a few hundred to about 1,000 unique products; categories about 20 and shops up to 60 (more when sort orders are available).",
            "default": 100
          },
          "refineByBrand": {
            "title": "Widen coverage with brands",
            "type": "boolean",
            "description": "Keywords only. Also search `<brand> <keyword>` for up to 30 brands that Taobao lists for the keyword (most listings first). Each refined keyword adds up to 40 new products. Products found this way are marked in `foundBy`, e.g. `brand: 罗技`.",
            "default": true
          },
          "refineByAttribute": {
            "title": "Widen coverage with attribute values",
            "type": "boolean",
            "description": "Keywords only. After the brands, also search `<value> <keyword>` for up to 30 attribute values Taobao lists for the keyword (for example switch types `青轴`, `红轴` for keyboards). Marked in `foundBy`, e.g. `attribute: 青轴`.",
            "default": true
          },
          "splitByPriceBands": {
            "title": "Use sort orders and price bands when available",
            "type": "boolean",
            "description": "Taobao honours sort and price-range parameters only for some client regions (not for US IPs, which Apify Proxy uses by default). When the Actor detects that they work for your proxy, it also queries every sort order and automatically chosen CNY price bands. Has no effect otherwise.",
            "default": true
          },
          "minPrice": {
            "title": "Min price (CNY)",
            "minimum": 0,
            "type": "integer",
            "description": "Optional. Only return products priced at or above this many yuan (CNY). Products outside the range are dropped and not charged."
          },
          "maxPrice": {
            "title": "Max price (CNY)",
            "minimum": 1,
            "type": "integer",
            "description": "Optional. Only return products priced at or below this many yuan (CNY). Products outside the range are dropped and not charged."
          },
          "convertPricesTo": {
            "title": "Convert prices to",
            "enum": [
              "USD",
              "EUR",
              "GBP",
              "JPY",
              "KRW",
              "HKD",
              "SGD",
              "AUD",
              "CAD",
              "NZD",
              "MYR",
              "THB",
              "PHP",
              "IDR",
              "INR",
              "CHF",
              "SEK",
              "NOK",
              "DKK",
              "PLN",
              "CZK",
              "HUF",
              "RON",
              "TRY",
              "ILS",
              "ZAR",
              "BRL",
              "MXN",
              "ISK",
              "NONE"
            ],
            "type": "string",
            "description": "Adds `priceConverted` in this currency next to the original CNY `price`, using the European Central Bank's daily reference rate (free, official; loaded once per run). Choose `NONE` to skip.",
            "default": "USD"
          },
          "deduplicateAcrossQueries": {
            "title": "De-duplicate across queries",
            "type": "boolean",
            "description": "If the same product matches several keywords, categories or shops, return (and charge) it only once - for the first query that found it.",
            "default": true
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Apify Proxy (datacenter) is used by default; the proxy session (IP) rotates every 30 requests and after any blocked response. The catalogue usually works without a proxy too.",
            "default": {
              "useApifyProxy": true
            }
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}