Pipispy APIEnglish

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

店铺广告 Meta 广告资料库投放趋势分析接口

接口信息

  • 接口名称: 店铺广告 Meta 广告资料库投放趋势分析接口
  • 请求方法: POST
  • 接口地址: /open-api/v1/data
  • 接口路径: /v3/api/open/ppspy/pp-stores/analysis/ad-trend
  • 接口描述: 获取指定店铺在Meta广告资料库中的广告投放趋势数据,包括活跃广告数、广告总数、新增广告数的历史变化趋势
  • 价格说明: 免费

请求头:

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

请求参数

请求结构

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

请求体参数 (params 对象)

参数名 类型 必填 描述
id String 是 店铺唯一标识ID,为13位字符串(例如:c2d5b2547218a),对应店铺榜单列表接口返回结果中的 store_id 字段
start_time Long 是 查询的开始时间,Unix时间戳(秒级)。用于指定统计的起始日期
end_time Long 是 查询的结束时间,Unix时间戳(秒级)。用于指定统计的结束日期。建议时间范围不要超过90天以获得最佳性能

请求示例

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/ppspy/pp-stores/analysis/ad-trend",
    "params": {
        "id": "c2d5b2547218a",
        "start_time": 1700000000,
        "end_time": 1707776000
    }
  }'

响应参数

响应体结构

{
  "code": 200,
  "message": "success",
  "data": {
    "active_ad_count_history": [],
    "ad_count_history": [],
    "ad_started_history": [],
    "is_logged_in": false
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "success": true,
  "fail": false
}

响应字段说明

字段名 类型 描述
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.data)

字段名 类型 描述
active_ad_count_history Array 活跃广告数历史变化数据,记录每天活跃投放中的广告数量。活跃广告是指在当天仍在投放状态的广告
ad_count_history Array 广告总数历史变化数据,记录每天累计的广告总数量。这是一个累积值,包含所有历史广告(活跃+已停止)
ad_started_history Array 新增广告数历史变化数据,记录每天新开始投放的广告数量。表示当天首次上线的新广告
is_logged_in Boolean 用户是否已登录,用于标识数据权限状态

历史数据项字段 (HistoryItem)

active_ad_count_history、ad_count_history、ad_started_history 数组中的每个元素包含以下字段:

字段名 类型 描述
date String 统计日期,格式为 yyyy-MM-dd(例如:2024-01-15)
count Long 该日期对应的数量值。根据所属数组不同,分别表示:活跃广告数、广告总数或新增广告数

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "active_ad_count_history": [
      {
        "date": "2024-01-01",
        "count": 125
      },
      {
        "date": "2024-01-02",
        "count": 138
      },
      {
        "date": "2024-01-03",
        "count": 145
      }
    ],
    "ad_count_history": [
      {
        "date": "2024-01-01",
        "count": 1500
      },
      {
        "date": "2024-01-02",
        "count": 1523
      },
      {
        "date": "2024-01-03",
        "count": 1548
      }
    ],
    "ad_started_history": [
      {
        "date": "2024-01-01",
        "count": 15
      },
      {
        "date": "2024-01-02",
        "count": 23
      },
      {
        "date": "2024-01-03",
        "count": 25
      }
    ],
    "is_logged_in": false
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "success": true,
  "fail": false
}

错误码说明

错误码 描述
200 成功
400 请求参数错误
401 未授权
403 权限不足
500 服务器内部错误