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.

TikTok Shop List API

API Information

  • API Name: Get TikTok Shop Store List
  • Request Method: POST
  • API URL: /open-api/v1/data
  • Interface URI path: /v3/api/open/tiktok-shop/shop/list
  • Description: Get TikTok shop store list information based on filter conditions
  • Pricing: Retrieving one data result consumes 1 credit

Request Headers:

  • Content-Type: application/json
  • Accept: application/json

Request Parameters

Request Structure

Parameter Name Type Description Example Required Default
key string User's external API request key "your_api_key_here" Yes
uri string Interface URI path "/v3/api/open/tiktok-shop/shop/list" Yes
params object Interface parameter object See parameter list below Yes

Request Body Parameters (params object)

Parameter Name Type Required Description
avg_price_usd_max Double No Average Price(USD), Maximum average product price in USD, used to filter shops with average USD price not exceeding specified value
avg_price_usd_min Double No Average Price(USD), Minimum average product price in USD, used to filter shops with average USD price not below specified value
categorize String No Category, Third-level category ID, used to filter shops by category
cpm_max Double No Maximum ad cost (CPM), used to filter shops with ad cost not exceeding specified value
cpm_min Double No Minimum ad cost (CPM), used to filter shops with ad cost not below specified value
current_page Integer No Current page number, pagination query current page, starting from 1
delivery String No Delivery method, overseas-cross-border delivery, local-local delivery
found_time_end Long No End time of first ad discovery (timestamp), used to filter shops first discovered within specified time range
found_time_start Long No Start time of first ad discovery (timestamp), used to filter shops first discovered within specified time range
gmv_max Double No GMV, Maximum sales volume (GMV), used to filter shops with sales volume not exceeding specified value
gmv_min Double No GMV, Minimum sales volume (GMV), used to filter shops with sales volume not below specified value
goods_count_max Long No Number of Products, Maximum number of goods, used to filter shops with goods count not exceeding specified value
goods_count_min Long No Number of Products, Minimum number of goods, used to filter shops with goods count not below specified value
is_managed Boolean No Whether it's a fully managed shop, false-not fully managed shop, true-fully managed shop
keyword String No Search keyword, used for fuzzy search by shop name, description, etc.
last_found_time_end Long No End time of last ad discovery (timestamp), used to filter shops last discovered within specified time range
last_found_time_start Long No Start time of last ad discovery (timestamp), used to filter shops last discovered within specified time range
page_size Integer No Page size, number of records per page for pagination query
person_count_max Long No Influencers, Maximum number of influencers, used to filter shops with influencer count not exceeding specified value
person_count_min Long No Influencers, Minimum number of influencers, used to filter shops with influencer count not below specified value
play_count_max Long No Ad Impressions, Maximum play count/ad impressions, used to filter shops with play count not exceeding specified value
play_count_min Long No Ad Impressions, Minimum play count/ad impressions, used to filter shops with play count not below specified value
product_type String No Product type, brand-brand, retail-retailer
region String No Country/region, used to filter shops by region
sales_trend Integer No Sales trend, 1-Increase, 0-Stable, -1-Decrease
sales_volume_max Long No Sold, Maximum sales volume, used to filter shops with sales volume not exceeding specified value
sales_volume_min Long No Sold, Minimum sales volume, used to filter shops with sales volume not below specified value
sort Integer No Sort field, 1-last ad time, 2-first ad time, 3-sold, 4-GMV, 5-impression, 6-ad spend, 7-ads, 8-influencers, 9-Number of Products, 10-Average Price
sort_type String No Sort type, asc-ascending, desc-descending
time Long No Time range, 0-all, 1-yesterday, 7-last 7 days, 30-last 30 days, 90-last 90 days
video_count_max Long No Maximum ad count, used to filter shops with ad count not exceeding specified value
video_count_min Long No Minimum ad count, used to filter shops with ad count not below specified value

Request Example

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/tiktok-shop/shop/list",
    "params": {
      "current_page": 1,
      "page_size": 20,
      "sort": 3,
      "sort_type": "desc",
      "time": 30,
      "keyword": "fashion accessories",
      "region": "US",
      "avg_price_usd_min": 10.0,
      "avg_price_usd_max": 100.0,
      "sales_volume_min": 1000,
      "product_type": "brand"
    }
  }'

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

Field Name Type Description
code Integer Response status code, 200 indicates success
message String Response message
data Object Response data
data.data Array Shop list
data.page Object Pagination information
version String API version
timestamp Long Response timestamp (null in this case)
sign String Response signature (null in this case)
remaining_credits Long Current remaining available credits after this request
consumed_credits Long Credits consumed by this request
success Boolean Whether the request was successful
fail Boolean Whether the request failed

Shop Information Fields

Field Name Type Description
id String Shop unique identifier ID
image String Shop main image URL
title String Shop title
sales_volume Long Shop sales volume
score Double Shop rating
shop_name String Shop name
video_count Long Number of ad videos
categorize Array Shop category information list (third-level categories)
region Array Shop target region list
play_count Long Play count/ad impressions
share_count Long Share count
found_time Long First discovery time (timestamp)
last_found_time Long Last discovery time (timestamp)
insert_time Long Data insertion time (timestamp)
update_time Long Data update time (timestamp)
min_cpm Double Minimum ad cost (CPM)
max_cpm Double Maximum ad cost (CPM)
currency String Currency type
shop_id String Shop ID
is_collection Boolean Whether it's collected
shop_image String Shop image URL
sales_trend Integer Sales trend, 1-growth, 0-stable, -1-decline
sales_trend_data Array Sales trend data list
gmv Double Sales volume (GMV)
is_in_marketplace Boolean Whether it's a marketplace shop
is_managed Boolean Whether it's a fully managed shop
person_count Long Number of influencers
gmv_usd Double Sales volume in USD (GMV USD)
goods_count Long Number of goods
goods_ad_count String Number of ad goods
best_selling_goods Array Best-selling goods list
avg_price Double Average price (local currency)
avg_price_usd Double Average price in USD
product_type Array Product type list, brand-Brand, retail-Retailer
delivery Array Shop Type, method list, overseas-Cross-border Shop, local-Local shop

Category Information Fields (categorize array)

Field Name Type Description
_id String Category ID
name_zh String Category name in Chinese
name_vi String Category name in Vietnamese
name_th String Category name in Thai
name_pt String Category name in Portuguese
name_ja String Category name in Japanese
name_id String Category name in Indonesian
name_en String Category name in English

Sales Trend Data Fields (sales_trend_data array)

Field Name Type Description
day Long Date timestamp
sales_volume Long Sales volume for that day

Best Selling Goods Fields (best_selling_goods array)

Field Name Type Description
product_id String Product ID
image String Product image URL
sales_volume Long Product sales volume
Page Object Fields (page)
Field Name Type Description
total_count Long Total number of records
page_count Long Total number of pages
current_page Long Current page number
page_size Long Page size
is_next Boolean Whether there is next page

Response Example

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "id": "7495432992748505937",
        "image": "https://im.pipispy.com/shops/images/5ecdf34a797edc74.png",
        "title": "ZOOONE NATURE",
        "sales_volume": 484186,
        "score": 4.3,
        "shop_name": "ZOOONE NATURE",
        "video_count": 3157,
        "categorize": [
          {
            "_id": "700650",
            "name_zh": "保健食品",
            "name_vi": "Thực phẩm bổ sung sức khỏe",
            "name_th": "อาหารเสริมเพื่อสุขภาพ",
            "name_pt": "Vitamins, Minerals & Wellness Supplements",
            "name_ja": "Vitamins, Minerals & Wellness Supplements",
            "name_id": "Suplemen Kesehatan",
            "name_en": "Vitamins, Minerals & Wellness Supplements"
          }
        ],
        "region": ["US"],
        "play_count": 203301212,
        "share_count": 254734,
        "found_time": 1701638465,
        "last_found_time": 1752199606,
        "insert_time": 1702748197,
        "update_time": 1752199633,
        "min_cpm": 695290.15,
        "max_cpm": 2787259.62,
        "currency": "USD",
        "shop_id": "7495432992748505937",
        "is_collection": false,
        "shop_image": "https://im.pipispy.com/shops/images/5ecdf34a797edc74.png",
        "sales_trend": -1,
        "sales_trend_data": [
          {
            "day": 1744300800,
            "sales_volume": 3565
          }
        ],
        "gmv": 12908398.76,
        "is_in_marketplace": true,
        "is_managed": true,
        "person_count": 280,
        "gmv_usd": 12908398.76,
        "goods_count": 24,
        "goods_ad_count": "25",
        "best_selling_goods": [
          {
            "product_id": "1730501450773467985",
            "image": "https://im.pipispy.com/products/images/9f33b35307396d27.png",
            "sales_volume": 190407
          }
        ],
        "avg_price": 26.66,
        "avg_price_usd": 26.66,
        "product_type": ["brand", "retail"],
        "delivery": ["local"]
      }
    ],
    "page": {
      "total_count": 10000,
      "page_count": 500,
      "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
500 Server internal error