Product List Interface
- API Name: Get Product List
- Request Method: POST
- API Address:
/open-api/v1/data
- Interface Path:
/v3/api/open/ad-product/list
- Interface Description: Query product list data
- 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/ad-product/list" |
Yes |
|
| params |
object |
Interface parameter object |
See parameter list below |
Yes |
|
Parameter List (params object)
| Parameter Name |
Type |
Description |
Example |
Required |
Default |
| plat_type |
number |
Platform type (0:all, 1:tiktok, 2:facebook) |
1 |
No |
|
| keyword |
string |
Search keyword |
"garden" |
No |
|
| search_type |
number |
Search type (1:product title, 2:product description, 3:advertiser URL, 4:advertiser name, 5:product keyword) |
1 |
No |
|
| category |
string |
Category, multiple separated by commas |
"cat1,cat2" |
No |
|
| region |
string |
Country/region, multiple separated by commas |
"US,HK" |
No |
|
| play_count_min |
number |
Minimum ad play count |
100 |
No |
|
| play_count_max |
number |
Maximum ad play count |
10000 |
No |
|
| digg_count_min |
number |
Minimum like count |
10 |
No |
|
| digg_count_max |
number |
Maximum like count |
1000 |
No |
|
| digg_play_rate_min |
number |
Minimum like rate |
0.01 |
No |
|
| digg_play_rate_max |
number |
Maximum like rate |
0.1 |
No |
|
| comment_count_min |
number |
Minimum comment count |
5 |
No |
|
| comment_count_max |
number |
Maximum comment count |
500 |
No |
|
| cpm_max |
number |
only plat_type=1, Ad Spend |
5 |
No |
|
| cpm_min |
number |
only plat_type=1, Ad Spend |
500 |
No |
|
| share_count_min |
number |
Minimum share count |
5 |
No |
|
| share_count_max |
number |
Maximum share count |
500 |
No |
|
| video_count_min |
number |
Minimum ad count |
1 |
No |
|
| video_count_max |
number |
Maximum ad count |
100 |
No |
|
| put_day_min |
number |
Minimum delivery days |
1 |
No |
|
| put_day_max |
number |
Maximum delivery days |
30 |
No |
|
| create_time_start |
number |
Product creation time start (timestamp) |
1709654400 |
No |
|
| create_time_end |
number |
Product creation time end (timestamp) |
1709827199 |
No |
|
| tiktok_time_start |
number |
Ad start date, first found time start (timestamp) |
1709654400 |
No |
|
| tiktok_time_end |
number |
Ad start date, first found time end (timestamp) |
1709827199 |
No |
|
| latest_found_time_start |
number |
Ad end date, latest found time start (timestamp) |
1710864000 |
No |
|
| latest_found_time_end |
number |
Ad end date, latest found time end (timestamp) |
1711036799 |
No |
|
| price_min |
number |
Product price (USD), minimum price |
100 |
No |
|
| price_max |
number |
Product price (USD), maximum price |
10000 |
No |
|
| currency |
string |
Currency, multiple separated by commas |
"USD,JPY" |
No |
|
| platform |
string |
Platform identifier, multiple separated by commas, shopify, woocommerce, shoplazza, magento, wix, shopline, squarespace, shopyy |
"squarespace,shopyy" |
No |
|
| popular_person_count_min |
number |
only plat_type=1, Minimum influencer count |
1 |
No |
|
| popular_person_count_max |
number |
only plat_type=1, Maximum influencer count |
100 |
No |
|
| root_path |
string |
Advertiser name |
"example.com" |
No |
|
| id |
string |
Product ID, multiple separated by commas |
"id1,id2" |
No |
|
| after_id |
string |
Pagination cursor ID (for deep pagination) |
"cursor_id" |
No |
|
| after_key |
string |
Pagination cursor key (for deep pagination) |
"cursor_key" |
No |
|
| sort |
string |
Sort field: 0-Start Date, 1-End Date, 2-Product Creation Date, 3-Price(USD), 4-Number of ads, 5-Impressions, 6-Likes, 7-Durations |
"create_time" |
No |
|
| sort_type |
string |
Sort type (asc:ascending, desc:descending) |
"desc" |
No |
|
| store_id |
string |
Store unique identifier ID, a 13-character string (e.g.: c2d5b2547218a), corresponds to the store_id field in the store ranking list interface response |
"664c85ef6947b" |
No |
|
| time |
number |
Time range (1:yesterday, 7:last 7 days, 30:last 30 days, 90:last 90 days) |
7 |
No |
|
| current_page |
number |
Current page number |
1 |
Yes |
1 |
| page_size |
number |
Page size |
10 |
Yes |
10 |
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/ad-product/list",
"params": {
"plat_type": 1,
"keyword": "garden",
"search_type": 1,
"region": "US",
"current_page": 1,
"page_size": 12,
"sort": "create_time",
"sort_type": "desc",
"play_count_min": 500,
"play_count_max": 3000000,
"digg_count_min": 50,
"digg_count_max": 75000,
"put_day_min": 2,
"put_day_max": 50,
"tiktok_time_start": 1709654400,
"tiktok_time_end": 1709827199,
"latest_found_time_start": 1710864000,
"latest_found_time_end": 1711036799,
"price_min": 1000,
"price_max": 50000,
"currency": "USD"
}
}'
Response
Response Body Structure
{
"code": 200,
"message": "success",
"data": {
"data": [
// Product data list
],
"page": {
// Pagination information
}
},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 20,
"success": true,
"fail": false
}
Response Field Description
Main Response Fields
| Field Name |
Type |
Description |
| data |
array[object] |
Product data list |
| page |
object |
Pagination information |
| version |
string |
API version |
| timestamp |
number/null |
Response timestamp |
| sign |
string/null |
Response signature |
| remaining_credits |
number |
Current remaining available credits after this request |
| consumed_credits |
number |
Credits consumed by this request |
| success |
boolean |
Whether the request was successful |
| fail |
boolean |
Whether the request failed |
Product Data Fields (data)
| Field Name |
Type |
Description |
| id |
string |
Product unique identifier ID |
| title |
string |
Product title |
| image |
string |
Product main image URL |
| price |
number |
Product price |
| currency |
string |
Product price currency type |
| tiktok_time |
number |
TikTok platform first discovery timestamp |
| found_time |
number |
TikTok platform first discovery timestamp |
| latest_found_time |
number |
TikTok platform latest discovery timestamp |
| play_count |
number |
TikTok platform play count |
| digg_count |
number |
TikTok platform like count |
| digg_play_rate |
number |
TikTok platform like play ratio |
| comment_count |
number |
TikTok platform comment count |
| share_count |
number |
TikTok platform share count |
| video_count |
number |
TikTok platform video count |
| is_collection |
boolean |
Whether already collected |
| platform |
string |
Product platform identifier |
| usd_price |
number |
Product USD price |
| put_days |
number |
TikTok platform delivery days |
| ad_platform_list |
array |
Ad platform list (e.g., tiktok, facebook) |
| facebook_data_count |
number |
Facebook platform data count |
| facebook_digg_count |
number |
Facebook platform like count |
| facebook_found_time |
number |
Facebook platform first discovery timestamp |
| facebook_latest_found_time |
number |
Facebook platform latest discovery timestamp |
| facebook_put_days |
number |
Facebook platform delivery days |
| all_data_count |
number |
All platform data count |
| all_digg_count |
number |
All platform like count |
| all_found_time |
number |
All platform first discovery timestamp |
| all_latest_found_time |
number |
All platform latest discovery timestamp |
| all_put_days |
number |
All platform delivery days |
| all_share_count |
number |
All platform share count |
| facebook_share_count |
number |
Facebook platform share count |
| all_comment_count |
number |
All platform comment count |
| facebook_comment_count |
number |
Facebook platform comment count |
| popular_person_count |
number |
Influencer count |
| create_time |
number |
Product creation timestamp |
| sort_id |
string |
Sort ID (for pagination sorting) |
Page Object Fields (page)
| Field Name |
Type |
Description |
| total_count |
number |
Total number of records |
| page_count |
number |
Total number of pages |
| current_page |
number |
Current page number |
| page_size |
number |
Page size |
| is_next |
boolean |
Whether there is next page |
Response Example
{
"code": 200,
"message": "success",
"data": {
"data": [
{
"id": "686d15677f259f583406b6dd",
"title": "Advanced Hair Growth Roll-On Serum",
"image": "https://cdn-product.pipispy.com/pimg_9665c6afa75fcb8787ef.png",
"price": 30.0,
"currency": "USD",
"tiktok_time": 1751979367,
"found_time": 0,
"latest_found_time": 1752200748,
"play_count": 0,
"digg_count": 5,
"digg_play_rate": 0.0,
"comment_count": 0,
"share_count": 0,
"video_count": 1,
"is_collection": false,
"platform": "shopify",
"usd_price": 30.0,
"put_days": 3,
"ad_platform_list": ["facebook"],
"facebook_data_count": 1,
"facebook_digg_count": 5,
"facebook_found_time": 1751979367,
"facebook_latest_found_time": 1752200748,
"facebook_put_days": 3,
"all_data_count": 1,
"all_digg_count": 5,
"all_found_time": 1751979367,
"all_latest_found_time": 1752200748,
"all_put_days": 3,
"all_share_count": 1,
"facebook_share_count": 1,
"all_comment_count": 0,
"facebook_comment_count": 0,
"popular_person_count": 0,
"create_time": 1751551334,
"sort_id": "14748630090094"
}
],
"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 Codes
| Error Code |
Description |
| 400 |
Bad Request - Invalid parameters |
| 401 |
Unauthorized - Invalid API key |
| 500 |
Internal Server Error |