Product List Interface
API Information
- 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 |