# TikTok Shop Search Scraper (`fetch_cat/tiktok-shop-search-scraper`) Actor

Search public TikTok Shop products in the United States. Export prices, sellers, ratings, sales data, variants, stock and product media.

- **URL**: https://apify.com/fetch\_cat/tiktok-shop-search-scraper.md
- **Developed by:** [Hanna Nosova](https://apify.com/fetch_cat) (community)
- **Categories:** E-commerce, Social media
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.60 / 1,000 tiktok shop product saveds

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/actors/running/actors-in-store.md#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 Search Scraper

Search public TikTok Shop products by keyword in the United States, or browse public US category URLs. Export structured product, price, seller, rating, sales and media data for product discovery, pricing research and catalog monitoring.

Use this TikTok Shop product search API to export TikTok Shop products into datasets, spreadsheets, JSON, or downstream catalog workflows. It is built for ecommerce analysts, marketplace sellers, agencies, and developers who need repeatable product discovery across supported markets.

### Who is it for?

- **Marketplace sellers** researching products, prices, shops, ratings, and public sales signals.
- **Ecommerce analysts** comparing assortments and promotions in the US TikTok Shop market.
- **Developers and agencies** feeding structured search results into dashboards, databases, and automations through API or MCP.

### Example input

```json
{
  "searchQueries": ["water bottles"],
  "categoryUrls": ["https://shop.tiktok.com/us/c/water-bottles/600048"],
  "maxItemsPerQuery": 10,
  "maxPagesPerQuery": 2,
  "country": "US",
  "includeProductDetails": true
}
```

### Example output

```json
{
  "productId": "1731726912824578262",
  "title": "HydroPal 32oz Motivational Sports Water Bottle - BPA-Free, Drop-Resistant, Food-Safe PP Plastic, Time Markers, Leak-Proof, Fruit Strainer, Carrying Strap for Active Sports & Workouts",
  "productUrl": "https://shop.tiktok.com/us/pdp/hydropal-32oz-water-bottle-with-time-markers-straw/1731726912824578262",
  "price": 7.75,
  "currency": "USD",
  "sellerName": "HydroPal",
  "rating": 4.8,
  "reviewCount": 271,
  "soldCount": 2014,
  "rank": 1,
  "page": 1,
  "searchQuery": "water bottles",
  "country": "US"
}
```

### What data can you export?

| Field | Description |
|---|---|
| `productId` | Stable TikTok Shop product ID |
| `title` | Product title |
| `productUrl` | Canonical public product URL |
| `description` | Public product description when detail enrichment succeeds |
| `category` | Primary public product category |
| `categories` | Public product category hierarchy |
| `variants` | Public SKU IDs, names, property pairs, available stock, status, price, original price, and currency |
| `totalStock` | Sum of known public SKU available quantities; `null` when quantities are unavailable |
| `images`, `videos` | Public product media URLs |
| `price` | Current search-card price |
| `currency` | Price currency |
| `originalPrice` | Original price when a promotion exposes it |
| `discountText` | Public promotion or discount label |
| `sellerId` | Public seller ID |
| `sellerName` | Shop name |
| `sellerUrl` | Public shop URL when present |
| `rating` | Product rating |
| `reviewCount` | Number of reviews |
| `soldCount` | Public sold count |
| `soldText` | Source sales label |
| `imageUrl` | Primary product image |
| `videoUrl` | Bound product video when present |
| `brandName` | Brand name when present |
| `skuMinPrice` | Lowest SKU price when present |
| `skuMaxPrice` | Highest SKU price when present |
| `shippingFee` | Shipping-fee estimate shown to the Actor's anonymous session; not a destination guarantee |
| `deliveryMinDays`, `deliveryMaxDays` | Delivery-window estimate shown to the anonymous session; not a destination guarantee |
| `shopRating`, `shopSoldCount`, `shopFollowersCount` | Public shop summary metadata |
| `detailEnriched` | Whether ID-matched public product details were added |
| `rank` | Deduplicated rank within the keyword or category |
| `page` | Result page number |
| `sourceType` | Whether the row came from `keyword` or `category` mode |
| `searchQuery` | Exact keyword that produced the row, or `null` for category rows |
| `categoryUrl`, `categoryId`, `categoryName` | Target-bound category attribution, or `null` for keyword rows |
| `country` | Verified TikTok Shop market |
| `scrapedAt` | UTC extraction timestamp |

### Input settings

| Setting | Description | Default |
|---|---|---|
| `searchQueries` | Optional product keywords | `['water bottles']` |
| `categoryUrls` | Optional public US TikTok Shop category URLs | `[]` |
| `maxItemsPerQuery` | Maximum unique products per keyword | `10` |
| `maxPagesPerQuery` | Maximum pages per keyword | `2` |
| `country` | Keyword-search market: `US` | `US` |
| `includeProductDetails` | Attempt ID-matched public US enrichment | `true` |
| `proxyConfiguration` | US residential proxy; an explicit proxy country must be US | US residential |

### Ready-to-run examples

Open a public example to inspect its input, run it, or reuse it as a task:

- [Export US TikTok Shop water bottles](https://apify.com/fetch_cat/tiktok-shop-search-scraper/examples/browse-us-water-bottles-category)
- [Search US TikTok Shop products](https://apify.com/fetch_cat/tiktok-shop-search-scraper/examples/search-us-tiktok-shop-products)

**Quick product sample**

```json
{"searchQueries":["running shoes"],"maxItemsPerQuery":10,"country":"US"}
```

**Compare multiple niches**

```json
{"searchQueries":["phone cases","desk lamps","travel bags"],"maxItemsPerQuery":50,"maxPagesPerQuery":3,"country":"US"}
```

**Browse a US category**

```json
{"searchQueries":[],"categoryUrls":["https://shop.tiktok.com/us/c/water-bottles/600048"],"maxItemsPerQuery":30,"maxPagesPerQuery":2,"country":"US"}
```

### Pricing

Pay per event: one `start` charge for run initialization, then an `item` charge for each unique product result saved. Optional detail enrichment has no separate charge event. See the [Pricing tab](https://apify.com/fetch_cat/tiktok-shop-search-scraper/pricing) for account-visible rates.

### Tips and limits

- Start with 10–30 products per keyword, then scale after reviewing the output.
- Results reflect the public US market at run time and can change. Prices are reported in USD when the source exposes them.
- Category URLs are supported only with `country: "US"`.
- Public video fields and other sparse optional fields are not guaranteed.
- Other country values are rejected and never replaced with US inventory.
- Missing optional values remain `null`; the Actor does not invent seller or regional metadata.
- Duplicate product IDs within a keyword are removed automatically.
- A query may return fewer rows than requested when the public search has no more unique products.

### API usage

**cURL**

```bash
curl -X POST 'https://api.apify.com/v2/acts/fetch_cat~tiktok-shop-search-scraper/runs?token=YOUR_APIFY_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"searchQueries":["water bottles"],"maxItemsPerQuery":10,"country":"US"}'
```

**JavaScript**

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('fetch_cat/tiktok-shop-search-scraper').call({
  searchQueries: ['water bottles'],
  maxItemsPerQuery: 10,
  country: 'US',
});
console.log(`Dataset: ${run.defaultDatasetId}`);
```

**Python**

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('fetch_cat/tiktok-shop-search-scraper').call(run_input={
    'searchQueries': ['water bottles'],
    'maxItemsPerQuery': 10,
    'country': 'US',
})
print(f"Dataset: {run['defaultDatasetId']}")
```

Use from MCP at `https://mcp.apify.com/?tools=fetch_cat/tiktok-shop-search-scraper` or call the Actor through the Apify API client.

### FAQ

#### Does it require a TikTok login?

No. It collects public TikTok Shop search results.

#### Which markets are supported?

This release independently verifies keyword search in `US`. Other country values are rejected rather than silently returning US inventory.

#### Can I search several keywords or categories?

Yes. Provide up to 20 combined `searchQueries` and `categoryUrls`; each row includes exact keyword or category attribution.

#### How can I search and export TikTok Shop products?

Enter one or more product keywords, choose a supported market, and run the Actor. Export the resulting dataset as JSON, CSV, Excel, or another format supported by Apify.

#### Can I run a TikTok Shop search scraper through API or MCP?

Yes. Use the cURL, JavaScript, or Python examples above, or connect through Apify MCP with the Actor-specific tools URL.

#### Why are some optional fields null?

TikTok Shop does not expose every field for every product. For the verified US detail route, an unavailable public product page can fall back to TikTok Shop’s public product-detail JSON response in the same anonymous session. That response may provide variants, stock, prices, descriptions and images without category breadcrumbs or shop aggregates. When enrichment cannot be completed, the Actor preserves the independently useful search row and sets `detailEnriched` to `false`. Stable IDs, titles, URLs, query binding, country, rank, page, and scrape time remain available.

### Related Actors

- [TikTok Shop Product Reviews](https://apify.com/vistics/tiktok-shop-product-reviews) for public buyer feedback on known products
- [TikTok Sound Scraper](https://apify.com/fetch_cat/tiktok-sound-scraper) for public sound metadata
- [TikTok Video Scraper](https://apify.com/fetch_cat/tiktok-video-scraper) for public video metadata
- [TikTok Profile Scraper](https://apify.com/fetch_cat/tiktok-profile-scraper) for public creator profiles
- [TikTok Comments Scraper](https://apify.com/fetch_cat/tiktok-comments-scraper) for public video discussions

### Support

Open an issue on the Actor page with the input, expected behavior, and a run link. Do not include passwords, cookies, or private account data.

# Actor input Schema

## `searchQueries` (type: `array`):

Product keywords for the independently verified US TikTok Shop market. Search results are checked against the requested market.

## `categoryUrls` (type: `array`):

Optional public US category URLs, usable only with country US, such as https://shop.tiktok.com/us/c/water-bottles/600048.

## `maxItemsPerQuery` (type: `integer`):

Maximum unique products saved for each keyword. The source may return fewer matching products; this is a cap, not a guaranteed count.

## `maxPagesPerQuery` (type: `integer`):

Maximum result pages fetched for each keyword.

## `country` (type: `string`):

The independently verified TikTok Shop keyword-search market. Other markets are not supported by this release; category URLs are US-only.

## `proxyConfiguration` (type: `object`):

US residential proxy. If no proxy country is supplied, the Actor uses US. A supplied proxy country must be US.

## `includeProductDetails` (type: `boolean`):

Attempt ID-matched public US description, variants, stock, media, shipping and shop metadata. A valid search row survives unavailable optional details.

## Actor input object example

```json
{
  "searchQueries": [
    "water bottles"
  ],
  "categoryUrls": [],
  "maxItemsPerQuery": 10,
  "maxPagesPerQuery": 2,
  "country": "US",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  },
  "includeProductDetails": true
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

# 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 = {
    "searchQueries": [
        "water bottles"
    ],
    "categoryUrls": [],
    "maxItemsPerQuery": 10,
    "maxPagesPerQuery": 2,
    "country": "US",
    "includeProductDetails": true
};

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

# Prepare the Actor input
run_input = {
    "searchQueries": ["water bottles"],
    "categoryUrls": [],
    "maxItemsPerQuery": 10,
    "maxPagesPerQuery": 2,
    "country": "US",
    "includeProductDetails": True,
}

# Run the Actor and wait for it to finish
run = client.actor("fetch_cat/tiktok-shop-search-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "searchQueries": [
    "water bottles"
  ],
  "categoryUrls": [],
  "maxItemsPerQuery": 10,
  "maxPagesPerQuery": 2,
  "country": "US",
  "includeProductDetails": true
}' |
apify call fetch_cat/tiktok-shop-search-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,fetch_cat/tiktok-shop-search-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/X2eHJZFtcalOf71zc/builds/aBtGDE3s7cI3AYdqD/openapi.json