# TikTok Shop Scraper — Reviews & Product Finder (`cliffside_calm/tiktok-shop-scraper`) Actor Scrape TikTok Shop product reviews (Vietnam / SEA and more) or find best-selling products by keyword with units sold, price and rating (US). One actor, two modes. - **URL**: https://apify.com/cliffside\_calm/tiktok-shop-scraper.md - **Developed by:** [Smallsoft](https://apify.com/cliffside_calm) (community) - **Categories:** E-commerce, Social media, Lead generation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 review scrapeds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## TikTok Shop Scraper — Reviews & Product Finder Pull TikTok Shop data without a browser, a proxy, or a captcha in sight. One Actor, two jobs, picked with the `mode` input: | Mode | What you get | Storefront | |---|---|---| | `reviews` | Every review for products you already know — rating, text, photos, buyer's variant, verified-purchase flag | Vietnam / SEA, UK, US | | `products` | Best-selling products for a keyword — units sold, price, rating, review count, seller | US | Use `products` to find what is selling, then feed those product IDs into `reviews` to learn *why* people buy it — or why they return it. ### Input Find products by keyword: ```json { "mode": "products", "searchWords": ["labubu", "stanley cup"], "maxProductsPerKeyword": 100 } ```` Scrape reviews for known products: ```json { "mode": "reviews", "productUrls": ["https://shop.tiktok.com/vn/pdp/1736377755182990422"], "region": "VN", "maxReviewsPerProduct": 200, "minRating": 1, "withMediaOnly": false } ``` `productUrls` accepts full `/{region}/pdp/{id}` URLs or bare numeric product IDs. A `max…` of `0` means "everything reachable"; omitting the field uses the default (200 reviews / 100 products), never "unlimited". ### Output One dataset row per record. The dataset has a table view per mode. **`reviews`** — `reviewId`, `productId`, `productName`, `productUrl`, `region`, `rating`, `text`, `reviewDate`, `reviewerName`, `reviewerCountry`, `isVerifiedPurchase`, `isIncentivized`, `hasMedia`, `mediaUrls`, `purchasedVariant`, `subRatings`, `scrapedAt`. **`products`** — `productId`, `title`, `region`, `searchWord`, `priceText`, `priceValue`, `currency`, `originalPriceText`, `soldCount`, `rating`, `reviewCount`, `sellerId`, `sellerName`, `productUrl`, `imageUrl`, `scrapedAt`. Example product row: ```json { "productId": "1730612163263434760", "title": "POP MART THE MONSTERS Let's Checkmate Series", "searchWord": "labubu", "priceText": "$46.99", "priceValue": 46.99, "currency": "USD", "soldCount": 26073, "rating": 4.9, "reviewCount": 4164, "sellerName": "POPMART US SHOP", "productUrl": "https://shop.tiktok.com/us/pdp/..." } ``` ### What this Actor promises — and what it doesn't Straight answers, so you can plan around them. **Reviews are region-aware.** Pass `region`: `VN`, `TH`, `ID`, `MY`, `PH`, `SG`, `GB`, `US`. Vietnam and Southeast Asia are first-class here, not an afterthought. **Keyword search is US-only.** The TikTok Shop search surface only answers for the US storefront; every other region is rejected upstream. `products` mode therefore pins `region` to `US` and tells you if you passed another. VN/SEA products are still reachable in `reviews` mode **by product ID**. **There is no fixed product count per keyword.** Search exposes no page cursor, so the Actor walks the result set, de-duplicates, and stops when a keyword runs dry. Measured on 2026-07-10 with `maxProductsPerKeyword: 0`: | Keyword | Unique products | |---|---| | `iphone 16 case` | 359 | | `stanley cup` | 269 / 280 (two runs) | | `labubu` | 230 / 209 / 195 (three runs) | Expect a couple hundred for a broad keyword, varying by roughly ±10% between runs, because the upstream page composition is not deterministic. Narrow keywords return far fewer. **Use more keywords to widen coverage**, not a bigger `maxProductsPerKeyword`. ### Reliability The upstream data is noisy. The Actor absorbs that instead of passing it to you: - **Transient failures are retried** with backoff, so one hiccup never kills a whole product or keyword. - **Duplicate inputs are dropped.** A PDP URL and its bare ID are the same product; `Labubu` and `labubu` are the same keyword. You are never charged twice for the same row. - **Quotas are never overshot.** Ask for 30 and you get 30, not 40. - **Nothing is truncated silently.** If an internal safety cap stops a run, the log says so and warns that more data may exist. - **Output is incremental.** Rows land in the dataset as they are scraped, so an aborted run still returns everything collected up to that point. ### Pricing Pay per result: you are charged for each row that lands in your dataset, and for nothing else. A run that returns no rows costs you nothing. Set `maxTotalChargeUsd` on the run to cap your spend — the Actor delivers exactly what it charged for and then stops. ### Legal Reviews, prices and product listings on TikTok Shop are public data. This Actor does not access private messages, logged-in-only content, or personal data beyond the display names TikTok itself publishes next to a review. This project is not affiliated with, endorsed by, or sponsored by TikTok or ByteDance. ### Development ```bash npm install npm test # typecheck (src + scripts) + 59 unit tests, zero extra deps npm run build apify push ``` # Actor input Schema ## `mode` (type: `string`): "Product reviews" scrapes reviews for products you already know (works for Vietnam / SEA and other regions). "Find products by keyword" discovers best-selling products with units sold, price and rating (US storefront). ## `productUrls` (type: `array`): Mode "reviews" only. Full /{region}/pdp/{id} URLs or bare numeric product IDs. Up to 500 per run — split larger jobs across runs. ## `region` (type: `string`): Mode "reviews" only. Keyword search always uses the US storefront. ## `maxReviewsPerProduct` (type: `integer`): Mode "reviews" only. Stop after this many reviews per product (0 = all reachable). ## `minRating` (type: `integer`): Mode "reviews" only. Keep reviews with at least this star rating. ## `withMediaOnly` (type: `boolean`): Mode "reviews" only. Keep only reviews that attach media. ## `searchWords` (type: `array`): Mode "products" only. Keywords to search TikTok Shop US for (e.g. "labubu", "stanley cup"). One dataset row per matched product. Up to 100 keywords per run. Yield varies by keyword and between runs — broad keywords returned 170-360 unique products in testing; narrow ones return far fewer. No fixed count is guaranteed. ## `maxProductsPerKeyword` (type: `integer`): Mode "products" only. Stop after this many products per keyword (0 = all reachable). ## Actor input object example ```json { "mode": "reviews", "productUrls": [ "https://shop.tiktok.com/vn/pdp/1736377755182990422" ], "region": "VN", "maxReviewsPerProduct": 200, "minRating": 1, "withMediaOnly": false, "searchWords": [ "labubu" ], "maxProductsPerKeyword": 100 } ``` # Actor output Schema ## `results` (type: `string`): Reviews (reviews mode) or products (products mode) as dataset rows. Switch between the Reviews and Products views in the table. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "productUrls": [ "https://shop.tiktok.com/vn/pdp/1736377755182990422" ], "searchWords": [ "labubu" ] }; // Run the Actor and wait for it to finish const run = await client.actor("cliffside_calm/tiktok-shop-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "productUrls": ["https://shop.tiktok.com/vn/pdp/1736377755182990422"], "searchWords": ["labubu"], } # Run the Actor and wait for it to finish run = client.actor("cliffside_calm/tiktok-shop-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "productUrls": [ "https://shop.tiktok.com/vn/pdp/1736377755182990422" ], "searchWords": [ "labubu" ] }' | apify call cliffside_calm/tiktok-shop-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=cliffside_calm/tiktok-shop-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "TikTok Shop Scraper — Reviews & Product Finder", "description": "Scrape TikTok Shop product reviews (Vietnam / SEA and more) or find best-selling products by keyword with units sold, price and rating (US). One actor, two modes.", "version": "0.1", "x-build-id": "ruf56yvJzbgNHfNGr" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/cliffside_calm~tiktok-shop-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-cliffside_calm-tiktok-shop-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/cliffside_calm~tiktok-shop-scraper/runs": { "post": { "operationId": "runs-sync-cliffside_calm-tiktok-shop-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/cliffside_calm~tiktok-shop-scraper/run-sync": { "post": { "operationId": "run-sync-cliffside_calm-tiktok-shop-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", "required": [ "mode" ], "properties": { "mode": { "title": "What do you want to scrape?", "enum": [ "reviews", "products" ], "type": "string", "description": "\"Product reviews\" scrapes reviews for products you already know (works for Vietnam / SEA and other regions). \"Find products by keyword\" discovers best-selling products with units sold, price and rating (US storefront).", "default": "reviews" }, "productUrls": { "title": "Product URLs or IDs", "maxItems": 500, "type": "array", "description": "Mode \"reviews\" only. Full /{region}/pdp/{id} URLs or bare numeric product IDs. Up to 500 per run — split larger jobs across runs.", "items": { "type": "string" } }, "region": { "title": "Region", "enum": [ "VN", "TH", "ID", "MY", "PH", "SG", "GB", "US" ], "type": "string", "description": "Mode \"reviews\" only. Keyword search always uses the US storefront.", "default": "VN" }, "maxReviewsPerProduct": { "title": "Max reviews per product", "minimum": 0, "type": "integer", "description": "Mode \"reviews\" only. Stop after this many reviews per product (0 = all reachable).", "default": 200 }, "minRating": { "title": "Minimum rating", "minimum": 1, "maximum": 5, "type": "integer", "description": "Mode \"reviews\" only. Keep reviews with at least this star rating.", "default": 1 }, "withMediaOnly": { "title": "Only reviews with photos/videos", "type": "boolean", "description": "Mode \"reviews\" only. Keep only reviews that attach media.", "default": false }, "searchWords": { "title": "Search keywords", "maxItems": 100, "type": "array", "description": "Mode \"products\" only. Keywords to search TikTok Shop US for (e.g. \"labubu\", \"stanley cup\"). One dataset row per matched product. Up to 100 keywords per run. Yield varies by keyword and between runs — broad keywords returned 170-360 unique products in testing; narrow ones return far fewer. No fixed count is guaranteed.", "items": { "type": "string" } }, "maxProductsPerKeyword": { "title": "Max products per keyword", "minimum": 0, "type": "integer", "description": "Mode \"products\" only. Stop after this many products per keyword (0 = all reachable).", "default": 100 } } }, "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 } } }, "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 } } } } } } } } } } ```