Pipispy APIEnglish

数据消耗规则:1. 获取一条数据结果消耗1 数据,获取数据结果的更多数据详情不消耗数据。2. 广告监控: 每次监控 $1 / 月。单个监控有效期为一个月,一个月后自动停止。删除监控不会恢复监控次数,请谨慎删除。监控调用为随时且无限次。

店铺广告投放时间表接口

接口信息

  • 接口名称: 店铺广告投放时间表接口
  • 请求方法: GET
  • 接口地址: /open-api/v1/data
  • 接口路径: /v3/api/open/store/detail/ad-schedule
  • 接口描述:
    • 查询指定店铺在不同平台(TikTok/Facebook)的广告投放时间表数据
    • 按日期统计每天的广告投放数量
    • 支持按时间范围筛选,了解店铺的广告投放节奏
    • 帮助分析店铺的广告投放策略和活跃周期
    • 价格说明: 免费

请求头:

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

请求参数

请求结构

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

请求体参数 (params 对象)

参数名 类型 必填 描述
id string true 店铺 ID 为 13 位字符串(例如:c2d5b2547218a),对应店铺榜单列表接口返回结果中的 store_id 字段
type integer false 平台类型:1-TikTok平台,2-Facebook平台,默认为1
time_start long false 开始时间,时间戳(秒),不传则不限制开始时间
time_end long false 结束时间,时间戳(秒),不传则不限制结束时间

请求示例

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/store/detail/ad-schedule",
    "params": {
      "id": "c2d5b2547218a",
      "type": 1,
      "time_start": 1704067200,
      "time_end": 1706745599
    }
  }'

响应参数

响应体结构

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "day": 1704067200,
        "ad_count": 150
      },
      {
        "day": 1704153600,
        "ad_count": 165
      },
      {
        "day": 1704240000,
        "ad_count": 142
      }
    ]
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "fail": false,
  "success": true
}

响应字段说明

字段名 类型 描述
code Integer 响应状态码,200 表示成功
message String 响应消息
data Object 响应数据
version String API 版本
timestamp String 响应时间戳
sign String 响应签名
remaining_credits Long 当前请求后的剩余可用积分
consumed_credits Long 本次请求消耗的积分
success Boolean 请求是否成功
fail Boolean 请求是否失败

响应结果信息字段

字段名 类型 描述
data Array[Object] 每日投放数据列表

data 数组元素结构(每日投放数据)

字段名 类型 描述
day Long 统计日期,时间戳(秒)
ad_count Long 该日广告投放数量

说明:

  • 数据按日期升序排列,从最早的日期到最新的日期
  • 只返回广告数量大于0的日期数据
  • 根据 type 参数不同,统计的是不同平台的广告数量

响应示例

TikTok 平台数据示例(type=1)

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "day": 1704067200,
        "ad_count": 150
      },
      {
        "day": 1704153600,
        "ad_count": 165
      },
      {
        "day": 1704240000,
        "ad_count": 142
      },
      {
        "day": 1704326400,
        "ad_count": 178
      },
      {
        "day": 1704412800,
        "ad_count": 155
      },
      {
        "day": 1704499200,
        "ad_count": 188
      },
      {
        "day": 1704585600,
        "ad_count": 195
      },
      {
        "day": 1704672000,
        "ad_count": 210
      },
      {
        "day": 1704758400,
        "ad_count": 185
      },
      {
        "day": 1704844800,
        "ad_count": 172
      }
    ]
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "fail": false,
  "success": true
}

Facebook 平台数据示例(type=2)

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "day": 1704067200,
        "ad_count": 85
      },
      {
        "day": 1704153600,
        "ad_count": 92
      },
      {
        "day": 1704240000,
        "ad_count": 78
      },
      {
        "day": 1704326400,
        "ad_count": 95
      },
      {
        "day": 1704412800,
        "ad_count": 88
      },
      {
        "day": 1704499200,
        "ad_count": 102
      },
      {
        "day": 1704585600,
        "ad_count": 110
      },
      {
        "day": 1704672000,
        "ad_count": 98
      },
      {
        "day": 1704758400,
        "ad_count": 105
      },
      {
        "day": 1704844800,
        "ad_count": 92
      }
    ]
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "fail": false,
  "success": true
}

不限时间范围示例(不传 time_start 和 time_end)

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "day": 1672531200,
        "ad_count": 45
      },
      {
        "day": 1672617600,
        "ad_count": 52
      },
      {
        "day": 1672704000,
        "ad_count": 48
      },
      ...
      {
        "day": 1706745600,
        "ad_count": 210
      }
    ]
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "fail": false,
  "success": true
}

错误码说明

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

使用说明

1. 平台类型说明

  • type=1(TikTok平台):

    • 统计店铺在 TikTok 平台每日的广告投放数量
    • 数据来源:TikTok 广告视频数据
  • type=2(Facebook平台):

    • 统计店铺在 Facebook 平台每日的广告投放数量
    • 数据来源:Facebook 广告数据

2. 时间范围

  • time_start 和 time_end 均为可选参数:
    • 如果不传任何时间参数,则返回店铺所有历史投放数据
    • 如果只传 time_start,返回从该时间点到最新的投放数据
    • 如果只传 time_end,返回从最早到该时间点的投放数据
    • 如果都传,返回该时间范围内的投放数据
    • 时间戳单位为秒

3. 数据排序

  • 数据按统计日期(day字段)升序排列
  • 从最早的日期排到最新的日期
  • 便于观察投放趋势的时间演变

4. 数据过滤

  • 只返回广告数量大于0的日期
  • 如果某天没有广告投放,该日期不会出现在结果中
  • 确保返回的都是有效的投放数据