# TikTok Shop Scraper — Products & Categories (`herus13/tiktok-shop-scraper`) Actor Scrape TikTok Shop products from any category page or product URL. Auto-solves the slide captcha. Supports 12 storefronts (VN, US, UK, ID, MY, TH, PH, SG, GB, JP, MX, BR) — region follows your proxy's exit IP. Returns title, price, rating, sold count, image, URL. - **URL**: https://apify.com/herus13/tiktok-shop-scraper.md - **Developed by:** [bootforge](https://apify.com/herus13) (community) - **Categories:** Automation, E-commerce, Lead generation - **Stats:** 3 total users, 2 monthly users, 72.7% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $12.00 / 1,000 products 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 a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.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/platform/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 Product Scraper **Scrape TikTok Shop products at scale** — title, price, original price, discount, seller, rating, sold count, images, full category breadcrumbs — by **keyword search** or **direct product URL**, across **10 storefronts** (US, GB, VN, TH, PH, MY, SG, JP, MX, BR). Auto-solves the slide CAPTCHA. No external services required. > Looking to scrape every product in a category, or auto-walk a region's sitemap? Use the **TikTok Shop Category Scraper** actor instead. This actor is focused on product-level extraction. ### Quick start Search by keyword (US only): ```json { "search_terms": ["wireless earbuds", "silk pillowcase"], "region": "US", "max_results": 100, "proxy": {"useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"], "apifyProxyCountry": "US"} } ```` Or scrape specific products by URL (any region): ```json { "product_urls": [ "https://shop.tiktok.com/vn/pdp/1733366003108907003", "https://shop.tiktok.com/us/pdp/wireless-bluetooth-earbuds/1729851384162063155" ], "region": "VN", "proxy": {"useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"], "apifyProxyCountry": "VN"} } ``` ### Sample output ```json { "product_id": "1729851384162063155", "title": "Wireless Bluetooth Earbuds — Noise-Cancelling", "price": 18.81, "original_price": 31.36, "discount_percent": 40.0, "currency": "$", "seller_id": "8646942781315453747", "seller_name": "SPRISE", "rating": 3.3, "review_count": 0, "sold_count": 88, "main_image": "https://p16-oec-general-useast5.ttcdn-us.com/...", "product_url": "https://shop.tiktok.com/us/pdp/.../1729851384162063155", "category_path": [ {"id": "601450", "name": "Beauty & Personal Care"} ], "region": "US", "scraped_at": "2026-05-03T08:22:00+00:00" } ``` Enable `scrape_product_details` (or pass `product_urls` directly) for full description, detail-page images, and the complete multi-level category breadcrumb. **What enrichment buys you:** | Field | Search-only ($0.005) | + PDP enrichment ($0.012) | |---|---|---| | `title`, `price`, `original_price`, `discount_percent`, `currency` | ✅ | ✅ (re-read from PDP, sometimes fresher) | | `seller_id`, `seller_name` | ✅ | ✅ | | `rating`, `review_count`, `sold_count` | ✅ | ✅ | | `main_image`, `image_urls` | 1 thumbnail | full gallery (up to 20 images) | | `category_path` | `[]` (search isn't category-scoped) | full multi-level breadcrumb root → leaf | | `description` | — | ✅ full product copy | | `detail_images` | — | ✅ | | `variants[]`, `stock_total`, `video_urls`, `seller_followers/rating/response_rate` | — | best-effort (depends on PDP variant; may be `None`) | **TL;DR: enable enrichment when you need description, full image gallery, or full breadcrumb. Otherwise shallow ($0.005) is enough — price/seller/sold/rating are already populated from the search SSR.** ### Inputs | Field | Description | |---|---| | `search_terms` | Keywords to search (**US only** — other markets 404 the search URL) | | `product_urls` | Direct PDP URLs: `https://shop.tiktok.com/{region}/pdp/{id}` — any region | | `region` | One of: US, GB, VN, TH, PH, MY, SG, JP, MX, BR. Must match your proxy's exit country | | `max_results` | Cap per search term (default 100, max 1000). Ignored for `product_urls` (always 1 each) | | `scrape_product_details` | Add full PDP enrichment for search results (description, detail images, full breadcrumb) | | `proxy` | Apify residential by default; raw URLs supported (BrightData / Oxylabs / SmartProxy) | | `browser_endpoint` | Optional: WSS URL for a remote anti-detect browser (BrightData, BrowserBase) | > ℹ️ **Match your proxy country to `region`.** TikTok blocks with `code:10000` if browser locale and IP disagree. The actor probes the proxy IP and aligns Camoufox's locale + timezone + geolocation automatically — but the proxy still has to land in a real country. ### Pricing (Pay Per Event) | Event | USD | |---|---| | Actor start (per GB memory) | $0.002 | | Shallow product (search result) | $0.005 | | Detailed product (PDP enrichment / `product_urls`) | $0.012 | | Typical run (default 2 GB) | Cost | |---|---| | 100 products from search (shallow) | ~$0.50 | | 1,000 products from search (shallow) | ~$5 | | 1,000 products with PDP enrichment | ~$12 | | 100 products via `product_urls` (always detailed) | ~$1.20 | Every product is captured by a real anti-detect browser session and every CAPTCHA is solved (~5–25 s of compute). There is no cheaper pure-HTTP path for TikTok Shop. **Currently the cheapest pay-per-result TikTok Shop scraper on Apify Store with a working CAPTCHA solver.** The most-reviewed competitor (4.5★, 651 users) charges $15 per 1,000 products with no CAPTCHA handling. Cheaper alternatives ($2–4 / 1,000) are rated under 2★ and broken. ### Why this actor - **Working CAPTCHA solver** — pure-OpenCV slide-puzzle with humanized mouse trajectories. No third-party captcha service. - **SSR-first extraction** — pulls the structured product list from the page's `__MODERN_ROUTER_DATA__` JSON, so seller IDs, original prices, discount percentages, and category IDs are all populated (not "Unknown"). - **Geo-aligned fingerprint** — pre-flight IP probe sets browser locale + timezone + geolocation to match the proxy's exit country, dodging TikTok's `code:10000` block. - **Graceful fallback** — if the bundled browser gets gated, plug in a BrightData Scraping Browser WSS URL via `browser_endpoint`. Existing TikTok Shop actors on Apify Store are unmaintained or rated <2 ★. This one ships. ### Markets *not* supported - **FR** — mobile-app only since March 2025; no public web Shop. `shop.tiktok.com/fr` returns `code:10000` even with a French VPN. - **ID** — TikTok ID Shop redirects to `shop-id.tokopedia.com` (Tokopedia merger). Different scraper required. ### FAQ **Why is search US-only?** Only `shop.tiktok.com/us/s?q=...` works as a web URL. Other regions 404 the search endpoint or redirect to non-shop surfaces. For non-US regions, scrape by `product_urls` directly. **`category_path` format?** List of `{id, name}` ordered root → leaf. `id` is stable for cross-region joins, `name` is the page's localized display string. Search-only results carry just the route's category (often single-element); PDP enrichment fills the full multi-level breadcrumb. **Reviews?** v1.1. Aggregate `rating` and `sold_count` ship today. **Want to scrape categories instead?** Use the **TikTok Shop Category Scraper** actor — it walks category URLs and the per-region sitemap. This actor stays focused on product-level extraction (search + direct PDP). **Outside Apify?** The underlying `tiktok-shop-scraper` Python package ships with a Typer CLI and FastAPI server (`POST /scrape`). The Apify wrapper is a thin layer. ### Related Actors Building a full data pipeline? Pair this actor with our other scrapers — same proxy config format, same Pydantic-validated output, all open source. #### Lead generation - **[LinkedIn Profile Scraper](https://apify.com/herus13/linkedin-profile-scraper)** — Scrape LinkedIn profiles via your li\_at cookie. Structured fields, full experience history, optional email/phone/contact enrichment. - **[Google Maps Business & Contact Scraper](https://apify.com/herus13/google-maps-scraper)** — Scrape Google Maps businesses with emails, phone numbers, reviews, images, social links. 24 fields per business. #### Lead generation / Hiring - **[LinkedIn Jobs Scraper](https://apify.com/herus13/linkedin-jobs-scraper)** — Scrape LinkedIn job listings with 30 fields per job — company enrichment, salary, recruiter info, full description. No login required. # Actor input Schema ## `search_terms` (type: `array`):

Keywords to search on the TikTok Shop storefront. Each term opens https://shop.tiktok.com/us/s?q={keyword} in an anti-detect browser, scrolls to load matches, and yields every visible product card.

Examples: wireless earbuds, silk pillowcase, kbeauty serum

Region support: web keyword search currently works only on US. Other regions either 404 the search URL or redirect to non-shop surfaces — for those, use Product URLs directly. (Browse-by-category is handled by a separate actor.)

## `product_urls` (type: `array`):

Direct product detail-page (PDP) URLs. Always returns the full detail enrichment (description, image gallery, full breadcrumb).

URL pattern: https://shop.tiktok.com/{region}/pdp/{product_id}

Use this when you already have product IDs (from a previous run, an affiliate feed, or competitor research).

## `region` (type: `string`):

TikTok Shop storefront for the proxy/exit IP. Must match your residential proxy's exit country — the actor probes the proxy IP and aligns the browser's locale, timezone, and geolocation automatically, but the proxy still has to land in a supported country. TikTok returns {"code":10000} on a mismatch.

Note: FR has no web Shop (mobile-app only); ID redirects to Tokopedia and is not supported.

## `max_results` (type: `integer`):

Cap on products yielded per search term (or per Product URL, where it always equals 1). The scraper scrolls the SERP in batches; raising this triggers more scrolls.

Default 100. Hard cap 1000 — TikTok's SERP typically exhausts at 200–500 cards regardless of how high you set this.

## `scrape_product_details` (type: `boolean`):

For each product yielded by a search term, fetch its full detail page (description, full image gallery, complete category breadcrumb). Adds one browser fetch per product and is billed at the higher PPE rate. Already implied for Product URLs.

## `max_concurrency` (type: `integer`): How many product detail fetches run in parallel. Higher is faster but more likely to trigger rate-limiting. ## `browser_endpoint` (type: `string`):

Optional WebSocket URL of a remote CDP-compatible browser (Bright Data Scraping Browser, BrowserBase, etc.). Use as a fallback if the bundled Camoufox + captcha solver still gets blocked from the Apify proxy.

Example (Bright Data): wss://brd-customer-XXX-zone-scraping_browser:PWD@brd.superproxy.io:9222

## `proxy` (type: `object`):

Required. TikTok Shop blocks unauthenticated traffic from many countries with a login wall. Use Apify residential proxy with US or GB (well-covered) or your own residential proxy (BrightData, Oxylabs, SmartProxy via raw_urls). Apify's VN / SEA pools are best-effort and often route via EU — which fails.

## Actor input object example ```json { "search_terms": [ "wireless earbuds" ], "region": "US", "max_results": 100, "scrape_product_details": false, "max_concurrency": 3, "proxy": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "US" } } ``` # Actor output Schema ## `results` (type: `string`): List of TikTok Shop products with title, price, rating, sold count, image, and product URL # 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 = { "search_terms": [ "wireless earbuds" ], "proxy": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "US" } }; // Run the Actor and wait for it to finish const run = await client.actor("herus13/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 = { "search_terms": ["wireless earbuds"], "proxy": { "useApifyProxy": True, "apifyProxyGroups": ["RESIDENTIAL"], "apifyProxyCountry": "US", }, } # Run the Actor and wait for it to finish run = client.actor("herus13/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 '{ "search_terms": [ "wireless earbuds" ], "proxy": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "US" } }' | apify call herus13/tiktok-shop-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=herus13/tiktok-shop-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "TikTok Shop Scraper — Products & Categories", "description": "Scrape TikTok Shop products from any category page or product URL. Auto-solves the slide captcha. Supports 12 storefronts (VN, US, UK, ID, MY, TH, PH, SG, GB, JP, MX, BR) — region follows your proxy's exit IP. Returns title, price, rating, sold count, image, URL.", "version": "0.1", "x-build-id": "OQY5J3o0r04oqJjU2" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/herus13~tiktok-shop-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-herus13-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/herus13~tiktok-shop-scraper/runs": { "post": { "operationId": "runs-sync-herus13-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/herus13~tiktok-shop-scraper/run-sync": { "post": { "operationId": "run-sync-herus13-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", "properties": { "search_terms": { "title": "Search Terms", "type": "array", "description": "

Keywords to search on the TikTok Shop storefront. Each term opens https://shop.tiktok.com/us/s?q={keyword} in an anti-detect browser, scrolls to load matches, and yields every visible product card.

Examples: wireless earbuds, silk pillowcase, kbeauty serum

Region support: web keyword search currently works only on US. Other regions either 404 the search URL or redirect to non-shop surfaces — for those, use Product URLs directly. (Browse-by-category is handled by a separate actor.)

", "items": { "type": "string" } }, "product_urls": { "title": "Product URLs", "type": "array", "description": "

Direct product detail-page (PDP) URLs. Always returns the full detail enrichment (description, image gallery, full breadcrumb).

URL pattern: https://shop.tiktok.com/{region}/pdp/{product_id}

Use this when you already have product IDs (from a previous run, an affiliate feed, or competitor research).

", "items": { "type": "string" } }, "region": { "title": "Region", "enum": [ "US", "GB", "VN", "TH", "PH", "MY", "SG", "JP", "MX", "BR" ], "type": "string", "description": "

TikTok Shop storefront for the proxy/exit IP. Must match your residential proxy's exit country — the actor probes the proxy IP and aligns the browser's locale, timezone, and geolocation automatically, but the proxy still has to land in a supported country. TikTok returns {\"code\":10000} on a mismatch.

Note: FR has no web Shop (mobile-app only); ID redirects to Tokopedia and is not supported.

", "default": "US" }, "max_results": { "title": "Max Results", "minimum": 1, "maximum": 1000, "type": "integer", "description": "

Cap on products yielded per search term (or per Product URL, where it always equals 1). The scraper scrolls the SERP in batches; raising this triggers more scrolls.

Default 100. Hard cap 1000 — TikTok's SERP typically exhausts at 200–500 cards regardless of how high you set this.

", "default": 100 }, "scrape_product_details": { "title": "Scrape Product Details", "type": "boolean", "description": "

For each product yielded by a search term, fetch its full detail page (description, full image gallery, complete category breadcrumb). Adds one browser fetch per product and is billed at the higher PPE rate. Already implied for Product URLs.

", "default": false }, "max_concurrency": { "title": "Max Concurrent Requests", "minimum": 1, "maximum": 10, "type": "integer", "description": "How many product detail fetches run in parallel. Higher is faster but more likely to trigger rate-limiting.", "default": 3 }, "browser_endpoint": { "title": "Remote Browser Endpoint (CDP)", "type": "string", "description": "

Optional WebSocket URL of a remote CDP-compatible browser (Bright Data Scraping Browser, BrowserBase, etc.). Use as a fallback if the bundled Camoufox + captcha solver still gets blocked from the Apify proxy.

Example (Bright Data): wss://brd-customer-XXX-zone-scraping_browser:PWD@brd.superproxy.io:9222

" }, "proxy": { "title": "Proxy Configuration", "type": "object", "description": "

Required. TikTok Shop blocks unauthenticated traffic from many countries with a login wall. Use Apify residential proxy with US or GB (well-covered) or your own residential proxy (BrightData, Oxylabs, SmartProxy via raw_urls). Apify's VN / SEA pools are best-effort and often route via EU — which fails.

" } } }, "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 } } } } } } } } } } ```