Pipispy APIEnglish

广告产品榜单列表接口

接口信息

  • 接口名称: 获取广告产品榜单列表
  • 请求方法: POST
  • 接口地址: /open-api/v1/data
  • 接口路径: /v3/api/open/rank/ad-product/list
  • 接口描述: 根据过滤条件获取广告产品榜单列表信息，支持分页
  • 价格说明: 获取一条数据结果消耗1 credit

请求头:

  • Content-Type: application/json
  • Accept: application/json

请求参数

请求结构

参数名 类型 描述 示例 必填 默认值
key
string
用户申请的外部 api 请求 key
"your_api_key_here"
是
uri
string
接口路径
"/v3/api/open/rank/ad-product/list"
是
params
object
接口入参对象
见参数列表
是

请求体参数 (params 对象)

参数名 类型 必填 描述
current_page
Integer
是
当前页码，分页查询的当前页数，从 1 开始
page_size
Integer
是
每页大小，分页查询的每页记录数
sort_key
String
是
排序字段：count_growth-播放量增长，growth_rate-增长率，video_count-广告数
sort_type
String
是
排序类型：desc-降序，asc-升序
time
Integer
是
时间：日期开始的零点时间，如天则传当日零点，周则传当周开始零点，月则传当月开始零点
type
Integer
是
时间类型：1-日榜，2-周榜，3-月榜
count_growth_max
Double
否
点赞数，数据增长最大值（播放量增长），用于筛选增长量不超过指定值的产品
count_growth_min
Double
否
点赞数，数据增长最小值（播放量增长），用于筛选增长量不低于指定值的产品
growth_rate_max
Double
否
增长率，数据增长比例最大值，用于筛选增长率不超过指定值的产品
growth_rate_min
Double
否
增长率，数据增长比例最小值，用于筛选增长率不低于指定值的产品
plat_type
Integer
否
平台类型：0-全平台，1-TikTok，2-Facebook
region
String
否
国家/地区，投放地区，多个用逗号分隔

请求示例

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/rank/ad-product/list",
    "params": {
      "current_page": 1,
      "page_size": 20,
      "sort_key": "count_growth",
      "sort_type": "desc",
      "time": 1,
      "type": 1,
      "count_growth_min": 1000,
      "count_growth_max": 1000000,
      "growth_rate_min": 0.1,
      "growth_rate_max": 1.0,
      "plat_type": 1,
      "region": "US,CA,GB"
    }
  }'

响应参数

响应体结构

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [],
    "page": {}
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 20,
  "success": true,
  "fail": false
}

响应字段说明

字段名 类型 描述
code
Integer
响应状态码，200 表示成功
message
String
响应消息
data
Object
响应数据
data.data
Array
产品榜单列表
data.page
Object
分页信息
version
String
API 版本
timestamp
String
响应时间戳（可为空）
sign
String
响应签名（可为空）
remaining_credits
Long
当前请求后的剩余可用积分
consumed_credits
Long
本次请求消耗的积分
success
Boolean
请求是否成功
fail
Boolean
请求是否失败

产品榜单信息字段

字段名 类型 描述
id
String
产品唯一标识 ID
image
String
产品主图片 URL
title
String
产品标题
currency
String
产品价格货币类型
price
Double
产品价格
usd_price
Double
产品美元价格
min_cpm
Double
最小 CPM（千次展示成本），可为空
max_cpm
Double
最大 CPM（千次展示成本），可为空
count_growth
Long
数据增长量（播放量增长）
video_count
Long
视频数量
growth_rate
Double
增长率
is_collection
Boolean
是否已收藏
platform
String
平台标识（如："shopify"、"shopline"）

分页信息字段

字段名 类型 描述
total_count
Long
总记录数
page_count
Long
总页数
current_page
Long
当前页码
page_size
Long
每页记录数
is_next
Boolean
是否有下一页

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "id": "67a2d72695f8665640581129",
        "image": "https://cdn-product.pipispy.com/pimg_7560a46afc0d626f9f70.png",
        "title": "Hermès Avalon Throw Blanket",
        "currency": "USD",
        "price": 149.99,
        "platform": "shopify",
        "usd_price": 149.99,
        "count_growth": 175621,
        "video_count": 14,
        "growth_rate": 0.2957,
        "is_collection": false
      },
      {
        "id": "674bf2ec6b331c3c04ad0a9a",
        "image": "https://cdn-product.pipispy.com/pimg_a15c12f7d699c40dc6d5.jpg",
        "title": "Compression Backpack",
        "currency": "INR",
        "price": 9499.0,
        "platform": "shopify",
        "usd_price": 110.8,
        "count_growth": 44047,
        "video_count": 6,
        "growth_rate": 3.0072,
        "is_collection": false
      },
      {
        "id": "65c024af7ffbbd340830304e",
        "image": "https://cdn-product.pipispy.com/pimg_603e433b11adfc4d1107.jpg",
        "title": "Furry Dino Bear | Handmade Jointed Teddy Bear Gift-Getahug",
        "currency": "USD",
        "price": 12.98,
        "platform": "shopline",
        "usd_price": 12.98,
        "min_cpm": 864.23,
        "max_cpm": 3467.1,
        "count_growth": 33316,
        "video_count": 5,
        "growth_rate": 0.011,
        "is_collection": false
      }
    ],
    "page": {
      "total_count": 101654,
      "page_count": 5083,
      "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
}

错误码说明

错误码 描述
200
成功
400
请求参数错误
500
服务器内部错误

注意事项

  1. 页码参数从 1 开始
  2. 排序字段支持多种选项：count_growth、growth_rate、video_count
  3. 时间范围筛选支持多种预定义时间段
  4. 平台筛选支持 TikTok 和 Facebook 平台
  5. 地区参数支持多个地区用逗号分隔
  6. 增长率以百分比值计算
  7. min_cpm 和 max_cpm 字段可能为空值（null），表示该产品暂无 CPM 数据
  8. platform 字段显示具体的电商平台名称，如"shopify"、"shopline"等
  9. 响应中的 version 字段表示 API 版本，timestamp 和 sign 字段目前为 null
  10. success 和 fail 字段用于标识请求处理状态