# TikTok Ultra Product Search (`datamagnet/tiktok-ultra-product-search`) Actor Collect TikTok Shop product listings by keyword, region, price, and sort order for easy market research. - **URL**: https://apify.com/datamagnet/tiktok-ultra-product-search.md - **Developed by:** [Datamagnet](https://apify.com/datamagnet) (community) - **Categories:** E-commerce, Automation, Social media - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing from $7.00 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. 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 Ultra Product Search Find products on TikTok Shop in a fast, easy way and keep your results organized for review. Use it to explore product listings, compare prices, and spot trending items in your chosen region. ### What you get - Product title in plain language - Current price and original price when available - Discount details and promotion labels - Seller name and shop details - Product rating and sales volume - Shipping origin and delivery badges - Search paging details for moving through more results - Result status showing whether more items are available - Filter-friendly output for sorting and narrowing results ### How to use 1. Sign up for the marketplace and open this tool. 2. Set your search words and choose the region you want. 3. Adjust optional settings like sorting, price range, live products, or cash-on-delivery support. 4. Run the search and review the returned product list. 5. Download the results and use them in your spreadsheet, report, or internal workflow. ### Inputs | Field | Required | Plain-English description | |---|---:|---| | sk | Yes | The words you want to search for, such as a product name or keyword. | | region | Yes | The country or market to search in. Supported values include GB, ID, IE, US, DE, JP, IT, FR, MY, MX, ES, BR, SG, TH, PH, and VN. | | count | No | How many results you want returned at one time. | | sort_type | No | How to order results: cheapest first, most expensive first, best sellers, or most relevant. | | price_range | No | A minimum and maximum price to focus on, written like 0,100. | | offset | No | Where to start in the result list when moving to the next page. | ### Output The results come back as a list of entries and search details. - code: Shows whether the search was successful. - message: A short status message. - data: The main search information and product results. - section_cursor: A page marker used to continue browsing more results. - page_state: Tells you the current state of the page. - has_more: Indicates whether more products are available. - cursor: The next position to use when continuing. - log_pb: Search record details used for tracking the returned set. - global_doodle_config: Search settings and page features shown during the search. - backtrace: Internal search flow information. - is_hit_cache: Shows whether the response came from stored results. - is_non_personalized_search: Indicates whether the results were personalized. - last_search_pid_list: The product IDs from the last returned page. - return_to_server_content: Additional paging and filter details for the next request. - server_perf_info: Timing and performance details from the search. - filter_origin_search_id: The original search reference used for filtering. - body: The visual result sections, including filters, sort options, and product cards. - style: Display styling details. - pendent_layer: Floating widgets such as vouchers or survey prompts. - requestId: A unique identifier for the request. Inside body, you will usually see: - sort bar options such as relevance, best sellers, and price - filter options like COD, live, price range, shipping location, categories, and ratings - product cards showing the title, price, rating, sales, seller, and shipping origin Each product card may include: - product title - product price - original price - discount percentage - rating score - sold count - seller name - shipping location - badges such as free shipping, flash sale, or new user offers ### Use cases - Compare product prices across TikTok Shop listings in a chosen market. - Track best-selling or highly rated products for market research. - Build a shortlist of trending products for merchandising or sourcing. - Monitor promotions, discounts, and shipping offers for competitive review. # Actor input Schema ## `sk` (type: `string`): What product should be searched? For example: "Notebook" or "wireless headphones". ## `region` (type: `string`): Choose the marketplace region for the search. For example: "MY" for Malaysia or "US" for the United States. ## `count` (type: `integer`): How many items should the actor request from the API? For example: 10 or 50. ## `sort_type` (type: `string`): Choose how results should be ordered. For example: "PRICE_ASC" for lowest price first or "RELEVANCE" for best matches. ## `price_range` (type: `string`): Optional price filter in the format min,max. For example: "0,100" to keep results between 0 and 100. ## `offset` (type: `integer`): Skip the first results and start later. For example: 0 for the beginning or 10 to skip the first ten items. ## Actor input object example ```json { "sk": "Notebook", "region": "MY", "count": 10, "sort_type": "1", "price_range": "0,100", "offset": 0 } ```` # Actor output Schema ## `results` (type: `string`): Formatted table view with labeled columns — ideal for reviewing data in Apify Console ## `rawData` (type: `string`): Unformatted JSON items exactly as collected from the API — use this for programmatic processing # 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 = { "sk": "Notebook", "region": "MY", "count": 10, "price_range": "0,100", "offset": 0 }; // Run the Actor and wait for it to finish const run = await client.actor("datamagnet/tiktok-ultra-product-search").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 = { "sk": "Notebook", "region": "MY", "count": 10, "price_range": "0,100", "offset": 0, } # Run the Actor and wait for it to finish run = client.actor("datamagnet/tiktok-ultra-product-search").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 '{ "sk": "Notebook", "region": "MY", "count": 10, "price_range": "0,100", "offset": 0 }' | apify call datamagnet/tiktok-ultra-product-search --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=datamagnet/tiktok-ultra-product-search", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "TikTok Ultra Product Search", "description": "Collect TikTok Shop product listings by keyword, region, price, and sort order for easy market research.", "version": "1.0", "x-build-id": "ByxNlGJFxQR93vTuc" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/datamagnet~tiktok-ultra-product-search/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-datamagnet-tiktok-ultra-product-search", "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/datamagnet~tiktok-ultra-product-search/runs": { "post": { "operationId": "runs-sync-datamagnet-tiktok-ultra-product-search", "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/datamagnet~tiktok-ultra-product-search/run-sync": { "post": { "operationId": "run-sync-datamagnet-tiktok-ultra-product-search", "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": [ "sk" ], "properties": { "sk": { "title": "Search keyword", "type": "string", "description": "What product should be searched? For example: \"Notebook\" or \"wireless headphones\"." }, "region": { "title": "Region", "enum": [ "GB", "ID", "IE", "US", "DE", "JP", "IT", "FR", "MY", "MX", "ES", "BR", "SG", "TH", "PH", "VN" ], "type": "string", "description": "Choose the marketplace region for the search. For example: \"MY\" for Malaysia or \"US\" for the United States.", "default": "MY" }, "count": { "title": "Number of results to collect", "minimum": 1, "maximum": 100, "type": "integer", "description": "How many items should the actor request from the API? For example: 10 or 50.", "default": 10 }, "sort_type": { "title": "Sort order", "enum": [ "1", "2", "3", "4" ], "type": "string", "description": "Choose how results should be ordered. For example: \"PRICE_ASC\" for lowest price first or \"RELEVANCE\" for best matches.", "default": "1" }, "price_range": { "title": "Price range", "type": "string", "description": "Optional price filter in the format min,max. For example: \"0,100\" to keep results between 0 and 100.", "default": "0,100" }, "offset": { "title": "Start from result number", "minimum": 0, "maximum": 10000, "type": "integer", "description": "Skip the first results and start later. For example: 0 for the beginning or 10 to skip the first ten items.", "default": 0 } } }, "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 } } } } } } } } } } ```