# TikTok Shop Product Search (Mobile API) (`cunning_soil/tiktok-shop-product-search-api`) Actor

Search TikTok Shop products by keyword with filters, sorting, pagination, and structured JSON output.

- **URL**: https://apify.com/cunning\_soil/tiktok-shop-product-search-api.md
- **Developed by:** [Rizla Piker](https://apify.com/cunning_soil) (community)
- **Categories:** E-commerce, Automation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 75.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $9.00 / 1,000 search results

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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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 Search (Mobile API)

Search **TikTok Shop products by keyword** using the mobile API response structure. This Actor supports filters, sorting, multi-page pagination, and structured JSON output for market research, competitor discovery, and catalog monitoring.

Run it on [Apify](https://apify.com) for API access, scheduling, integrations, proxy rotation, and run monitoring.

### Why use this Actor?

- **Keyword search:** Find products across TikTok Shop by text query instead of product ID.
- **Filters and sorting:** Price range, LIVE-only, COD-only, and sort by price or best sellers.
- **Pagination built in:** Automatically follows `has_more` pages using `min_time` / `cursor` from the API.
- **Multi-region:** US, UK, EU, SEA, LATAM, and more.
- **Clean output modes:** Readable grouped JSON, compact product rows, or full raw API payloads.

### How to use this Actor

1. Enter a **search query** (required).
2. Pick a **region**.
3. Set **Number of products** (`resultsLimit`) if you want more than 10.
4. Run and download the dataset.

That’s it — pagination is automatic.

### Ready-made examples (published tasks)

Use these pre-configured tasks from the Actor **Examples** tab (or create them in Console):

| Use case | Query | Region | Sort |
| --- | --- | --- | --- |
| US best-selling wireless earbuds | `wireless earbuds` | US | BEST\_SELLERS |
| Vietnam Bluetooth earphones | `tai nghe bluetooth` | VN | BEST\_SELLERS |
| Japan wireless earphones | `ワイヤレスイヤホン` | JP | BEST\_SELLERS |
| Germany shampoo price scan | `shampoo` | DE | PRICE\_ASC (`0,50`) |

See JSON configs in the repo `examples/` folder. How to publish tasks: [Publish your Actor task](https://docs.apify.com/actors/publishing/publish-task).

### Pricing

Pay per event: **$0.01 per search page** (`search_page`, up to 10 products per page). Dataset rows and actor start are priced near zero so cost scales with pages fetched, not product count.

### Input

#### Simplest usage

```json
{
  "query": "wireless earbuds",
  "region": "US"
}
```

#### Get more products

```json
{
  "query": "wireless earbuds",
  "region": "US",
  "resultsLimit": 30
}
```

`resultsLimit: 30` → actor fetches 3 pages automatically (10 products each).

#### Optional filters

```json
{
  "query": "shampoo",
  "region": "DE",
  "resultsLimit": 20,
  "sortType": "BEST_SELLERS",
  "priceRange": "0,50"
}
```

#### Multiple searches (optional)

```json
{
  "query": "wireless earbuds",
  "region": "US",
  "resultsLimit": 10,
  "searchTasks": [
    { "query": "tai nghe bluetooth", "region": "VN" },
    { "query": "ワイヤレスイヤホン", "region": "JP" }
  ]
}
```

When `searchTasks` is set, it overrides the single `query` / `region`.

#### Local-language keyword examples

| Region | Example keyword |
| --- | --- |
| US, GB, PH, SG, IE | `wireless earbuds` |
| DE, FR, IT | `shampoo` |
| ES, MX | `champú` / `audífonos inalámbricos` |
| BR | `fone de ouvido bluetooth` |
| JP | `ワイヤレスイヤホン` |
| VN | `tai nghe bluetooth` |
| TH | `หูฟัง bluetooth` |
| ID, MY | `earbuds bluetooth` |

#### Parameters

| Field | Required | Default | Description |
| --- | --- | --- | --- |
| `query` | Yes\* | — | Search keyword (any language) |
| `region` | No | `US` | Country code |
| `resultsLimit` | No | `10` | How many products to return (1–100). Pages are fetched automatically |
| `sortType` | No | empty | `RELEVANCE`, `BEST_SELLERS`, `PRICE_ASC`, `PRICE_DESC` |
| `priceRange` | No | empty | e.g. `0,50` |
| `live` | No | `false` | LIVE products only |
| `cod` | No | `false` | COD products only |
| `searchTasks` | No | — | Optional batch of `{ "query", "region" }` |
| `outputMode` | No | `formatted_filtered` | Products / Grouped JSON / Raw API |

\*Or provide `searchTasks` instead of `query`.

### Output

You can download the dataset in JSON, CSV, Excel, or other formats from Apify Console.

#### `outputMode: "formatted_filtered"`

One dataset row per product:

```json
{
  "product_id": "1729587132860570285",
  "title": "Wireless Earbuds Pro ...",
  "price": {
    "show_price": "19.99$",
    "sale_price": "19.99",
    "original_price": "29.99",
    "currency": "USD",
    "discount": "33%"
  },
  "image": "https://p16-oec-general-useast5.ttcdn-us.com/...",
  "sales_count": 2120,
  "rating": 4.5,
  "store_info": {
    "name": "Example Store",
    "shop_id": "8647042001333817005"
  },
  "search_id": "20260121074932FBC0E44FF5C76619BE8E"
}
```

#### `outputMode: "full_readable"`

Single grouped record with pagination metadata:

```json
{
  "search_info": {
    "query": "wireless earbuds",
    "region": "US",
    "sortType": "BEST_SELLERS",
    "maxResults": 30
  },
  "pagination": {
    "has_more": true,
    "cursor": 10,
    "min_time": null,
    "pages_fetched": 3
  },
  "total_products": 30,
  "products": []
}
```

#### `outputMode: "raw_response"`

Original API payload (or `{ "pages": [...] }` when multiple pages were fetched).

### Data fields

| Field | Description |
| --- | --- |
| `product_id` | TikTok Shop product ID |
| `title` | Product title |
| `price.show_price` | Display price string |
| `price.sale_price` | Sale price value |
| `price.original_price` | Strikethrough/original price |
| `sales_count` | Sold count when available |
| `rating` | Product rating when available |
| `store_info.name` | Seller/shop name |
| `store_info.shop_id` | Shop ID |
| `image` | Main product image URL |

### Pricing / cost estimation

Each page of 10 products is one upstream request. Cost depends on:

- `resultsLimit` (pages = ceil(resultsLimit / 10))
- Apify compute units for the Actor run

Tip: Start with the default `resultsLimit: 10`, then increase only when you need more.

### Tips and advanced options

- Use `sortType: "PRICE_ASC"` or `"PRICE_DESC"` for price-sorted competitor scans.
- Use `priceRange: "0,25"` to narrow results to a budget band.
- Use local-language keywords for better regional results.
- Use `raw_response` when you need the full mobile search card payload.

### FAQ, disclaimers, and support

- Product fields vary by region, seller, and search context.
- Respect TikTok Shop Terms of Service and applicable laws when using scraped data.
- For custom fields, filters, or bulk keyword workflows, use the **Issues** or **Contact** tab on Apify.

### Publication tips (Apify Store)

1. **Title:** `TikTok Shop Product Search (Mobile API)`
2. **Categories:** `E-commerce`, `Social Media`
3. **SEO keywords:** `tiktok shop search`, `product search`, `tiktok ecommerce`, `keyword search`

# Actor input Schema

## `query` (type: `string`):

Keyword in any language. Examples: wireless earbuds, tai nghe bluetooth, ワイヤレスイヤホン, fone de ouvido bluetooth.

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

TikTok Shop country.

## `resultsLimit` (type: `integer`):

How many products to return. Pagination is handled automatically (10 per page).

## `sortType` (type: `string`):

Optional sort order.

## `priceRange` (type: `string`):

Optional filter, e.g. 0,50

## `live` (type: `boolean`):

Only products from LIVE streams.

## `cod` (type: `boolean`):

Only Cash on Delivery products.

## `searchTasks` (type: `array`):

Run several keyword/region searches in one go. Overrides query/region when set.

## `outputMode` (type: `string`):

Usually leave as Products (one row each).

## Actor input object example

```json
{
  "query": "wireless earbuds",
  "region": "US",
  "resultsLimit": 10,
  "sortType": "",
  "live": false,
  "cod": false,
  "outputMode": "formatted_filtered"
}
```

# Actor output Schema

## `products` (type: `string`):

Dataset items containing TikTok Shop product search results for the requested keyword, filters, and region.

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "query": "wireless earbuds"
};

// Run the Actor and wait for it to finish
const run = await client.actor("cunning_soil/tiktok-shop-product-search-api").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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "query": "wireless earbuds" }

# Run the Actor and wait for it to finish
run = client.actor("cunning_soil/tiktok-shop-product-search-api").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 '{
  "query": "wireless earbuds"
}' |
apify call cunning_soil/tiktok-shop-product-search-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=cunning_soil/tiktok-shop-product-search-api",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/QWNY607GUPeKVNzqI/builds/VqEyTI16WUOIbaIyz/openapi.json