# 产品列表接口 ## 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 | #### 请求案例 ```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/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" } }' ``` ### 响应 #### 响应体结构 ```json { "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 | 是否有下一页 | #### 响应案例 ```json { "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 | 服务器内部错误 |