产品列表接口
API 信息
- API 名称: 获取产品列表
- 请求方法: POST
- API 地址:
/open-api/v1/data
- 接口路径:
/v3/api/open/ad-product/list
- 接口描述: 查询产品列表数据
- 价格说明: 获取一条数据结果消耗1 credit
请求头设置:
- Content-Type: application/json
- Accept: application/json
请求参数
请求结构
| 参数名称 |
类型 |
描述 |
示例 |
必填 |
默认值 |
| key |
string |
用户申请的外部 API 请求 key |
"your_api_key_here" |
是 |
|
| uri |
string |
接口 URI 路径 |
"/v3/api/open/product/list" |
是 |
|
| params |
object |
接口参数对象 |
见下方参数列表 |
是 |
|
参数列表 (params 对象)
| 参数名称 |
类型 |
描述 |
示例 |
必填 |
默认值 |
| plat_type |
number |
平台类型 (0:全部, 1:tiktok, 2:facebook) |
1 |
否 |
|
| keyword |
string |
搜索关键词 |
"garden" |
否 |
|
| search_type |
number |
搜索类型 (1:产品标题, 2:产品描述, 3:广告主URL, 4:广告主名, 5:产品关键词) |
1 |
否 |
|
| category |
string |
分类,多个用逗号分隔 |
"cat1,cat2" |
否 |
|
| region |
string |
国家/地区,多个用逗号分隔 |
"US,HK" |
否 |
|
| play_count_min |
number |
最小广告播放数 |
100 |
否 |
|
| play_count_max |
number |
最大广告播放数 |
10000 |
否 |
|
| digg_count_min |
number |
最小点赞数 |
10 |
否 |
|
| digg_count_max |
number |
最大点赞数 |
1000 |
否 |
|
| digg_play_rate_min |
number |
最小点赞率 |
0.01 |
否 |
|
| digg_play_rate_max |
number |
最大点赞率 |
0.1 |
否 |
|
| comment_count_min |
number |
最小评论数 |
5 |
否 |
|
| comment_count_max |
number |
最大评论数 |
500 |
否 |
|
| cpm_max |
number |
only plat_type=1,广告花费 |
5 |
No |
|
| cpm_min |
number |
only plat_type=1,广告花费 |
500 |
No |
|
| share_count_min |
number |
最小分享数 |
5 |
否 |
|
| share_count_max |
number |
最大分享数 |
500 |
否 |
|
| video_count_min |
number |
最小广告数量 |
1 |
否 |
|
| video_count_max |
number |
最大广告数量 |
100 |
否 |
|
| put_day_min |
number |
最小投放天数 |
1 |
否 |
|
| put_day_max |
number |
最大投放天数 |
30 |
否 |
|
| create_time_start |
number |
产品创建时间起始值(时间戳) |
1709654400 |
否 |
|
| create_time_end |
number |
产品创建时间结束值(时间戳) |
1709827199 |
否 |
|
| tiktok_time_start |
number |
广告开始日期, 首次发现时间起始值(时间戳) |
1709654400 |
否 |
|
| tiktok_time_end |
number |
广告开始日期, 首次发现时间结束值(时间戳) |
1709827199 |
否 |
|
| latest_found_time_start |
number |
广告结束日期,最新发现时间起始值(时间戳) |
1710864000 |
否 |
|
| latest_found_time_end |
number |
广告结束日期,最新发现时间结束值(时间戳) |
1711036799 |
否 |
|
| price_min |
number |
产品价格(USD),最小价格 |
100 |
否 |
|
| price_max |
number |
产品价格(USD),最大价格 |
10000 |
否 |
|
| currency |
string |
货币单位,多个用逗号分隔 |
"USD,JPY" |
否 |
|
| platform |
string |
平台标识,多个用逗号分隔,shopify、woocommerce、shoplazza、magento、wix、shopline、squarespace、shopyy |
"squarespace,shopyy" |
否 |
|
| popular_person_count_min |
number |
only plat_type=1,最小红人数量 |
1 |
否 |
|
| popular_person_count_max |
number |
only plat_type=1,最大红人数量 |
100 |
否 |
|
| root_path |
string |
广告主名 |
"example.com" |
否 |
|
| id |
string |
产品 ID,多个用逗号分隔 |
"id1,id2" |
否 |
|
| after_id |
string |
分页游标 ID(用于深度分页) |
"cursor_id" |
否 |
|
| after_key |
string |
分页游标键值(用于深度分页) |
"cursor_key" |
否 |
|
| sort |
string |
排序字段 0-总开始时间,1-总结束时间,2-产品创建时间,3-产品价格(USD),4-总广告数,5-广告播放,6-总点赞数,7-总投放天数 |
"create_time" |
否 |
|
| sort_type |
string |
排序类型 (asc:升序, desc:降序) |
"desc" |
否 |
|
| store_id |
string |
店铺唯一标识ID,为13位字符串(例如:c2d5b2547218a),对应店铺榜单列表接口返回结果中的 store_id 字段 |
"664c85ef6947b" |
否 |
|
| time |
number |
时间范围 (1:昨天, 7:近7天, 30:近30天, 90:近90天) |
7 |
否 |
|
| current_page |
number |
当前页码 |
1 |
是 |
1 |
| page_size |
number |
每页大小 |
10 |
是 |
10 |
请求案例
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"
}
}'
响应
响应体结构
{
"code": 200,
"message": "success",
"data": {
"data": [
// 产品数据列表
],
"page": {
// 分页信息
}
},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 20,
"success": true,
"fail": false
}
响应字段说明
主要响应字段
| 字段名称 |
类型 |
描述 |
| data |
array[object] |
产品数据列表 |
| page |
object |
分页信息 |
| version |
string |
API 版本 |
| timestamp |
number/null |
响应时间戳 |
| sign |
string/null |
响应签名 |
| remaining_credits |
Long |
当前请求后的剩余可用积分 |
| consumed_credits |
Long |
本次请求消耗的积分 |
| success |
boolean |
请求是否成功 |
| fail |
boolean |
请求是否失败 |
产品数据字段 (data)
| 字段名称 |
类型 |
描述 |
| id |
string |
产品唯一标识 ID |
| title |
string |
产品标题 |
| image |
string |
产品主图片 URL |
| price |
number |
产品价格 |
| currency |
string |
产品价格货币类型 |
| tiktok_time |
number |
TikTok 平台首次发现时间戳 |
| found_time |
number |
TikTok 平台首次发现时间戳 |
| latest_found_time |
number |
TikTok 平台最新发现时间戳 |
| play_count |
number |
TikTok 平台播放量 |
| digg_count |
number |
TikTok 平台点赞数 |
| digg_play_rate |
number |
TikTok 平台点赞播放比 |
| comment_count |
number |
TikTok 平台评论数 |
| share_count |
number |
TikTok 平台分享数 |
| video_count |
number |
TikTok 平台视频数量 |
| is_collection |
boolean |
是否已收藏 |
| platform |
string |
产品平台标识 |
| usd_price |
number |
产品美元价格 |
| put_days |
number |
TikTok 平台投放天数 |
| ad_platform_list |
array |
广告平台列表(如:tiktok, facebook) |
| facebook_data_count |
number |
Facebook 平台数据数量 |
| facebook_digg_count |
number |
Facebook 平台点赞数 |
| facebook_found_time |
number |
Facebook 平台首次发现时间戳 |
| facebook_latest_found_time |
number |
Facebook 平台最新发现时间戳 |
| facebook_put_days |
number |
Facebook 平台投放天数 |
| all_data_count |
number |
全平台数据数量 |
| all_digg_count |
number |
全平台点赞数 |
| all_found_time |
number |
全平台首次发现时间戳 |
| all_latest_found_time |
number |
全平台最新发现时间戳 |
| all_put_days |
number |
全平台投放天数 |
| all_share_count |
number |
全平台分享数 |
| facebook_share_count |
number |
Facebook 平台分享数 |
| all_comment_count |
number |
全平台评论数 |
| facebook_comment_count |
number |
Facebook 平台评论数 |
| popular_person_count |
number |
达人数量 |
| create_time |
number |
产品创建时间戳 |
| sort_id |
string |
排序 ID(用于分页排序) |
分页信息字段 (page)
| 字段名称 |
类型 |
描述 |
| total_count |
number |
总记录数 |
| page_count |
number |
总页数 |
| current_page |
number |
当前页码 |
| page_size |
number |
每页大小 |
| is_next |
boolean |
是否有下一页 |
响应案例
{
"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
}
错误码
| 错误码 |
描述 |
| 400 |
请求错误 - 无效参数 |
| 401 |
未授权 - 无效 API 密钥 |
| 500 |
服务器内部错误 |