# 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 ```bash 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 ```json { "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 ```json { "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 |