Image Search - TikTok Shop Search API
Overall Call Flow
1. Submit image (/v3/api/open/ai-search/image/submit or /v3/api/open/ai-search/image/submit/image-url)
↓
2. Wait 10-20 seconds
↓
3. Query processing status (/v3/api/open/ai-search/image/status)
↓
4. Get result summary (/v3/api/open/ai-search/image/resultSummary)
↓
5. Based on summary data, selectively call detailed list APIs:
- Product list: /v3/api/open/ai-search/image/product/search
- Ad list: /v3/api/open/ai-search/image/search4/ad/search
- Store list: /v3/api/open/ai-search/image/root-path/search
- TikTok products: /v3/api/open/ai-search/image/tiktok-product/search
- TikTok shops: /v3/api/open/ai-search/image/tiktok-shop/search (This API)
API Overview
The Image Search TikTok Shop API is used to search for similar TikTok Shop stores based on images. You need to first obtain an image_id through the image submission API, then use this API to query a list of TikTok shops similar to the image.
This API supports rich filtering conditions, including keyword search, region, category, sales volume, price, ad data, and other multi-dimensional filtering to help users accurately locate target shops.
- API Name: Image Search TikTok Shop
- Request Method: POST
- API Address:
/open-api/v1/data
- API Path:
/v3/api/open/ai-search/image/tiktok-shop/search
- API Description: Query similar TikTok shops based on image ID, supports multi-dimensional filtering and sorting
- Pricing: Retrieving one data result consumes 1 credit
Request Headers:
- Content-Type: application/json
- Accept: application/json
Request Parameters
Request Structure
| Parameter |
Type |
Description |
Example |
Required |
Default |
| key |
string |
User's external API request key |
"your_api_key_here" |
Yes |
|
| uri |
string |
API path |
"/v3/api/open/ai-search/image/tiktok-shop/search" |
Yes |
|
| params |
object |
API input parameters |
See parameter list |
Yes |
|
Request Body Parameters (params object)
| Parameter |
Type |
Required |
Description |
| image_id |
String |
Yes |
Image ID, obtained through image submission API. Format: img_ prefix + timestamp |
| current_page |
Integer |
Yes |
Current page number, starting from 1, default is 1 |
| page_size |
Integer |
Yes |
Number of items per page, default is 20 |
| keyword |
String |
No |
Search keyword, enter shop keywords to search, such as shop name, shop description |
| region |
String |
No |
Region, supports region codes like GB/US, see Countries and Regions |
| categorize |
String |
No |
Category ID |
| sales_volume_min |
Long |
No |
Minimum sales volume |
| sales_volume_max |
Long |
No |
Maximum sales volume |
| gmv_min |
Long |
No |
Minimum GMV (sales amount) |
| gmv_max |
Long |
No |
Maximum GMV (sales amount) |
| sales_trend |
Integer |
No |
Sales trend (1: Growing, 0: Stable, -1: Declining) |
| person_count_min |
Integer |
No |
Minimum influencer count |
| person_count_max |
Integer |
No |
Maximum influencer count |
| avg_price_usd_min |
Integer |
No |
Minimum average selling price (USD) |
| avg_price_usd_max |
Integer |
No |
Maximum average selling price (USD) |
| delivery |
String |
No |
Shop type (overseas: Cross-border shipping, local: Local shipping) |
| product_type |
String |
No |
Product type (brand: Brand, retail: Retailer) |
| play_count_min |
Long |
No |
Minimum ad play count (ad impressions) |
| play_count_max |
Long |
No |
Maximum ad play count (ad impressions) |
| cpm_min |
Integer |
No |
Minimum ad spend |
| cpm_max |
Integer |
No |
Maximum ad spend |
| video_count_min |
Long |
No |
Minimum ad count |
| video_count_max |
Long |
No |
Maximum ad count |
| found_time_start |
Long |
No |
First ad discovery time start (Unix timestamp, seconds) |
| found_time_end |
Long |
No |
First ad discovery time end (Unix timestamp, seconds) |
| last_found_time_start |
Long |
No |
Last ad time start (Unix timestamp, seconds) |
| last_found_time_end |
Long |
No |
Last ad time end (Unix timestamp, seconds) |
| time |
Integer |
No |
Time range (0: All, 1: Yesterday, 7: Last 7 days, 30: Last 30 days, 90: Last 90 days). Default: 0 |
| sort |
Integer |
No |
Sort method (1: Last time, 2: Start time, 3: Sales volume, 4: GMV, 5: Ad play count, 6: Ad spend, 7: Ad count, 8: Influencer count, 9: Product count, 10: Average selling price, 11: Image similarity sort (default)) |
| sort_type |
String |
No |
Sort type (desc: Descending, asc: Ascending). Note: This parameter is invalid when sort=11 |
Request Examples
Basic Request Example
Using cURL
curl -X POST "https://www.pipispy.com/open-api/v1/data" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"key": "your_api_key_here",
"uri": "/v3/api/open/ai-search/image/tiktok-shop/search",
"params": {
"image_id": "img_1737532800123456",
"current_page": 1,
"page_size": 20
}
}'
Advanced Filtering Examples
Using Keywords and Region Filtering
curl -X POST "https://www.pipispy.com/open-api/v1/data" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"key": "your_api_key_here",
"uri": "/v3/api/open/ai-search/image/tiktok-shop/search",
"params": {
"image_id": "img_1737532800123456",
"current_page": 1,
"page_size": 20,
"keyword": "fashion store",
"region": "US",
"sales_volume_min": 1000,
"avg_price_usd_min": 10,
"avg_price_usd_max": 100,
"sort": 3,
"sort_type": "desc"
}
}'
Filtering by Sales Trend and Shop Type
curl -X POST "https://www.pipispy.com/open-api/v1/data" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"key": "your_api_key_here",
"uri": "/v3/api/open/ai-search/image/tiktok-shop/search",
"params": {
"image_id": "img_1737532800123456",
"current_page": 1,
"page_size": 20,
"sales_trend": 1,
"delivery": "overseas",
"product_type": "brand",
"gmv_min": 10000,
"time": 30,
"sort": 4
}
}'
Response Parameters
Response Body Structure
{
"code": 200,
"message": "success",
"data": {
"data": [ ... ],
"page": { ... }
},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 20,
"success": true,
"fail": false
}
Response Field Description
Top-level Fields
| Field Name |
Type |
Description |
| code |
Integer |
Response status code, 200 indicates success |
| message |
String |
Response message |
| data |
Object |
Response data, contains data (shop list) and page (pagination info) |
| version |
String |
API version |
| timestamp |
String |
Response timestamp |
| sign |
String |
Response signature |
| remaining_credits |
Long |
Current remaining available credits after this request |
| consumed_credits |
Long |
Credits consumed by this request |
| success |
Boolean |
Whether request succeeded |
| fail |
Boolean |
Whether request failed |
Shop Data Fields (data)
| Field Name |
Type |
Description |
| id |
String |
Shop unique identifier ID |
| image |
String |
Shop main image URL |
| title |
String |
Shop title |
| desc |
String |
Shop description |
| sales_volume |
Long |
Shop sales volume |
| score |
Double |
Shop rating |
| shop_name |
String |
Shop name |
| shop_id |
String |
Shop ID |
| shop_image |
String |
Shop image URL |
| shop_sales_volume |
Long |
Shop sales volume |
| video_count |
Long |
Ad video count |
| categorize |
List<CategoryDTO> |
Shop category info list, see CategoryDTO object description below |
| region |
List<String> |
Shop target region list |
| play_count |
Long |
Play count/ad impressions |
| share_count |
Long |
Share count |
| found_time |
Long |
First discovery time (timestamp, seconds) |
| last_found_time |
Long |
Last discovery time (timestamp, seconds) |
| insert_time |
Long |
Data insertion time (timestamp, seconds) |
| update_time |
Long |
Data update time (timestamp, seconds) |
| min_cpm |
Double |
Minimum ad spend (CPM) |
| max_cpm |
Double |
Maximum ad spend (CPM) |
| currency |
String |
Currency type |
| is_collection |
Boolean |
Whether already collected |
| root_path |
String |
Shop root path (domain) |
| keywords |
List<String> |
Shop keyword list |
| card_found_time |
Long |
Card first discovery time (timestamp, seconds) |
| card_last_found_time |
Long |
Card last discovery time (timestamp, seconds) |
| sales_trend |
Integer |
Sales trend (1: Growing, 0: Stable, -1: Declining) |
| sales_trend_data |
List<SalesTrendData> |
Sales trend data list, see SalesTrendData object description below |
| gmv |
Double |
Sales amount (GMV) |
| gmv_usd |
Double |
USD sales amount (GMV USD) |
| is_in_marketplace |
Boolean |
Whether affiliate shop |
| is_managed |
Boolean |
Whether fully managed shop |
| person_count |
Long |
Influencer count |
| landing_page |
String |
Shop landing page URL |
| goods_count |
Long |
Product count |
| goods_ad_count |
String |
Ad product count |
| best_selling_goods |
List<BestSellingGood> |
Best-selling product list |
| avg_price |
Double |
Average price (local currency) |
| avg_price_usd |
Double |
Average USD price |
| product_type |
List<String> |
Product type list (brand: Brand, retail: Retailer) |
| delivery |
List<String> |
Delivery method list (overseas: Cross-border, local: Local) |
CategoryDTO Object Info
| Field Name |
Type |
Description |
| _id |
String |
Category ID |
| name_zh |
String |
Chinese name |
| name_vi |
String |
Vietnamese name |
| name_th |
String |
Thai name |
| name_pt |
String |
Portuguese name |
| name_ja |
String |
Japanese name |
| name_id |
String |
Indonesian name |
| name_en |
String |
English name |
SalesTrendData Object Info
| Field Name |
Type |
Description |
| day |
Long |
Statistics time (timestamp, seconds) |
| sales_volume |
Long |
Sales volume |
BestSellingGood Object Info
| Field Name |
Type |
Description |
| id |
String |
Product ID |
| image |
String |
Product image URL |
| title |
String |
Product title |
| price |
Double |
Product price |
| sales_volume |
Long |
Product sales volume |
| Field Name |
Type |
Description |
| total_count |
Long |
Total record count |
| page_count |
Long |
Total page count |
| current_page |
Long |
Current page number |
| page_size |
Long |
Page size |
| is_next |
Boolean |
Whether has next page |
Response Examples
{
"code": 200,
"message": "success",
"data": {
"data": [
{
"id": "shop_001",
"image": "https://cdn-shop.pipispy.com/tiktok_shop_001.jpg",
"title": "Fashion Store Official",
"desc": "Premium fashion and accessories",
"sales_volume": 125000,
"score": 4.8,
"shop_name": "Fashion Store Official",
"shop_id": "shop_12345",
"shop_image": "https://cdn-shop.pipispy.com/shop_icon.jpg",
"shop_sales_volume": 125000,
"video_count": 245,
"categorize": [
{
"_id": "cat_001",
"name_en": "Fashion",
"name_zh": "时尚"
}
],
"region": ["US", "GB"],
"play_count": 12345678,
"share_count": 45678,
"found_time": 1700000000,
"last_found_time": 1737532800,
"insert_time": 1700000000,
"update_time": 1737532800,
"min_cpm": 15.5,
"max_cpm": 45.8,
"currency": "USD",
"is_collection": false,
"root_path": "tiktok.com",
"keywords": ["fashion", "clothing", "accessories"],
"card_found_time": 1700086400,
"card_last_found_time": 1737446400,
"sales_trend": 1,
"sales_trend_data": [],
"gmv": 3750000.00,
"gmv_usd": 3750000.00,
"is_in_marketplace": true,
"is_managed": false,
"person_count": 156,
"landing_page": "https://www.tiktok.com/@fashionstore",
"goods_count": 450,
"goods_ad_count": "245",
"best_selling_goods": [
{
"id": "prod_001",
"image": "https://cdn-product.pipispy.com/prod_001.jpg",
"title": "Summer Dress",
"price": 29.99,
"sales_volume": 5000
}
],
"avg_price": 35.50,
"avg_price_usd": 35.50,
"product_type": ["brand"],
"delivery": ["overseas", "local"]
}
],
"page": {
"total_count": 500,
"page_count": 25,
"current_page": 1,
"page_size": 20,
"is_next": true
}
},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 20,
"success": true,
"fail": false
}
Error Code Description
| Error Code |
Description |
| 200 |
Success |
| 400 |
Request parameter error |
| 401 |
Unauthorized - Invalid API key |
| 500 |
Internal server error |
The complete image search TikTok shop flow involves the following APIs:
- Image Submission:
/v3/api/open/ai-search/image/submit or /v3/api/open/ai-search/image/submit/image-url
- Processing Status Query:
/v3/api/open/ai-search/image/status
- Result Summary:
/v3/api/open/ai-search/image/resultSummary
- Ad Search:
/v3/api/open/ai-search/image/search4/ad/search
- Product Search:
/v3/api/open/ai-search/image/product/search
- Store Search:
/v3/api/open/ai-search/image/root-path/search
- TikTok Product Search:
/v3/api/open/ai-search/image/tiktok-product/search
- TikTok Shop Search (This API):
/v3/api/open/ai-search/image/tiktok-shop/search
Usage Notes
- Similarity Sorting: By default (sort=11), shop list is sorted by image similarity, with most similar shops first. Note: When sort=11, sort_type parameter is invalid
- Keyword Search: Supports searching by shop name, shop description, and other dimensions
- Region Filtering: Supports filtering by shop target region
- Sales Data: Supports filtering by sales volume, GMV, sales trend, and other sales metrics
- Ad Data: Supports filtering by ad play count, ad count, ad spend, and other ad metrics
- Shop Type: Supports filtering by delivery method (cross-border/local) and product type (brand/retailer)
- Time Range: Use time parameter to get shop data within specified time range
- Influencer Marketing: Supports filtering by influencer count to understand shop's influencer marketing situation
- Price Filtering: Supports filtering shops by average selling price