Pipispy API中文

Data usage rules: 1. Obtaining a data result consumes 1 data. Obtaining more detailed information about a data result does not consume data. 2. Ad Tracker: Each monitoring session costs $1/month. Each monitoring session is valid for one month and automatically expires after one month. Deleting a monitoring session does not restore the monitoring session, so please delete with caution. Monitoring sessions can be accessed at any time and are unlimited.

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 Information

  • 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

Pagination Info Fields (page)

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:

  1. Image Submission: /v3/api/open/ai-search/image/submit or /v3/api/open/ai-search/image/submit/image-url
  2. Processing Status Query: /v3/api/open/ai-search/image/status
  3. Result Summary: /v3/api/open/ai-search/image/resultSummary
  4. Ad Search: /v3/api/open/ai-search/image/search4/ad/search
  5. Product Search: /v3/api/open/ai-search/image/product/search
  6. Store Search: /v3/api/open/ai-search/image/root-path/search
  7. TikTok Product Search: /v3/api/open/ai-search/image/tiktok-product/search
  8. TikTok Shop Search (This API): /v3/api/open/ai-search/image/tiktok-shop/search

Usage Notes

  1. 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
  2. Keyword Search: Supports searching by shop name, shop description, and other dimensions
  3. Region Filtering: Supports filtering by shop target region
  4. Sales Data: Supports filtering by sales volume, GMV, sales trend, and other sales metrics
  5. Ad Data: Supports filtering by ad play count, ad count, ad spend, and other ad metrics
  6. Shop Type: Supports filtering by delivery method (cross-border/local) and product type (brand/retailer)
  7. Time Range: Use time parameter to get shop data within specified time range
  8. Influencer Marketing: Supports filtering by influencer count to understand shop's influencer marketing situation
  9. Price Filtering: Supports filtering shops by average selling price