Pipispy APIEnglish

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

获取监控任务列表接口

接口信息

  • 接口名称: 获取监控任务列表接口
  • 请求方法: POST
  • 接口地址: open-api/v1/monitor/data
  • 接口路径: /v3/api/ad-monitor-task/list
  • 接口描述:
    • 查询当前用户的所有监控中的广告任务,支持按关键词、任务类型、国家等条件筛选,支持分页和排序(按开始时间升序/降序),返回任务的基本信息(ID、开始时间、持续时间等)
    • 价格说明: 免费

请求头:

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

请求参数

请求结构

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

请求体参数 (params 对象)

参数名 类型 必填 描述
keyword String 否 监控任务名称关键词
monitor_task_type integer 否 监控任务类型,1:facebook广告主, 2:店铺/网站
country string 否 国家
order_by string 否 排序字段可取值:
started_at(开始监控日期)
ad_total_count(总广告数)
ad_total_active_count(总活跃广告数)
ad_today_count(今日新增广告数)
ad_yesterday_count(昨日新增广告数)
landing_page_total_count(落地页总数)
landing_page_today_count(今日新增落地页)
landing_page_yesterday_count(昨日新增落地页)
product_total_count(总产品数)
product_today_count(今日新增产品)
product_yesterday_count(昨日新增产品)
direction string 否 排序方式: desc(降序), asc(升序)
page integer 否 页码(默认1)
per_page integer 否 分页大小(默认10)

请求示例

curl -X POST "https://www.pipispy.com/open-api/v1/monitor/data" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "key": "your_api_key_here",
    "uri": "/v3/api/ad-monitor-task/list",
    "params": {
        "keyword": "ChicMe",
        "monitor_task_type": 1,
        "order_by": "ad_total_active_count",
        "direction": "desc",
        "page": 1,
        "per_page": 10
    }
  }'

响应参数

响应体结构

{
  "code": 200,
  "message": "success",
  "data": {},
  "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 请求是否失败

搜索结果信息字段

字段名 类型 描述
per_page integer 每页显示的数据条数
total integer 总数据条数
last_page integer 最后一页的页码
current_page integer 当前页码
country string 国家代码
task_id string 任务id
facebook_page_id string fb ads广告主id
facebook_page_id string fb ads广告主id
name string 监控对象名称
category string 广告主展示fb ad library上的类别, 店铺/网站没有
avatar_url string 监控对象头像
started_at integer 开始监控时间,时间戳,单位s
stoped_at integer 监控停止时间,时间戳,单位s
monitor_expire_time integer 监控到期时间,时间戳,单位s
facebook_shop_url string fb ads店铺url
monitor_task_type integer 监控任务类型 1:facebook广告主, 2:店铺/网站
country string 广告主国家(部分有), 店铺国家
ad_total_count integer 总广告数
ad_total_active_count integer 总活跃
ad_today_count integer 今日新增广告数
ad_yesterday_count integer 昨日新增广告数
landing_page_total_count integer 落地页总数
landing_page_today_count integer 今日新增落地页
landing_page_yesterday_count integer 昨日新增落地页
product_total_count integer 总产品数
product_today_count integer 今日新增产品
product_yesterday_count integer 昨日新增产品
latest_ad_data array[object{3}] 最新广告数据
latest_ad_data[].id string 广告id
latest_ad_data[].cover_url string 封面
latest_ad_data[].ad_started_at integer 发布时间时间戳,单位s
latest_ad_data[].duration integer 视频时长(秒)
latest_ad_data[].type integer 广告类型
latest_ad_data[].video_url string 视频广告的URL地址
latest_ad_data[].cards array[object] 广告卡片数组,包含多个广告素材
latest_ad_data[].cards[].width integer 卡片宽度,单位像素
latest_ad_data[].cards[].height integer 卡片高度,单位像素
latest_ad_data[].cards[].type integer 卡片类型(1=视频,2=图片)
latest_ad_data[].cards[].url string 卡片资源URL地址
videos_ad_total_count integer 视频广告总数
cards_ad_total_count integer 卡片广告总数
images_ad_total_count integer 图片广告总数
ad_seven_day_count integer 近7天新增广告数
landing_page_seven_day_count integer 近7天新增落地页数
product_seven_day_count integer 近7天新增产品数
updated_at integer 最后更新时间,时间戳,单位秒
monitored_days integer 已监控天数
status integer 监控状态 1: 监控中, 2: 已取消监控

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "per_page": 1,
    "total": 1,
    "data": [
      {
        "country": "PL",
        "latest_ad_data": [
          {
            "duration": 28,
            "cover_url": "https://cdn.pipidata.com/images/ffa2dbbd8eeaf537f07439410251c81f1505516772fb4eb08eeb1abdfc1169ba.png",
            "cards": [
              {
                "duration": 28,
                "cover_url": "https://cdn.pipidata.com/images/ffa2dbbd8eeaf537f07439410251c81f1505516772fb4eb08eeb1abdfc1169ba.png",
                "width": 720,
                "type": 1,
                "url": "https://cdn.pipidata.com/videos/34006a2c3591e52c0822ed20228f9f15a9e4007738bfebdcf25c3bc393de3ca7.mp4",
                "height": 1280
              },
              {
                "duration": 28,
                "cover_url": "https://cdn.pipidata.com/images/ffa2dbbd8eeaf537f07439410251c81f1505516772fb4eb08eeb1abdfc1169ba.png",
                "width": 720,
                "type": 1,
                "url": "https://cdn.pipidata.com/videos/34006a2c3591e52c0822ed20228f9f15a9e4007738bfebdcf25c3bc393de3ca7.mp4",
                "height": 1280
              },
              {
                "duration": 28,
                "cover_url": "https://cdn.pipidata.com/images/193cab5ca17e4fe71c48d051010d36c1f23fb2304db14eb6ff18438b7f1c4392.png",
                "width": 720,
                "type": 1,
                "url": "https://cdn.pipidata.com/videos/b09f6a2e42674f4707559ac036719510ebd55db607a17e837547eea32f8142bc.mp4",
                "height": 900
              }
            ],
            "video_url": "https://cdn.pipidata.com/videos/34006a2c3591e52c0822ed20228f9f15a9e4007738bfebdcf25c3bc393de3ca7.mp4",
            "id": "1269635651567302",
            "ad_started_at": 1758092400,
            "type": 3
          }
        ],
        "product_seven_day_count": 0,
        "landing_page_yesterday_count": 0,
        "task_id": "68f98898850c5345a4c87e67",
        "product_yesterday_count": 0,
        "videos_ad_total_count": 640,
        "ad_yesterday_count": 0,
        "updated_at": 1761208806,
        "monitor_task_type": 1,
        "product_today_count": 0,
        "ad_total_active_count": 16423,
        "monitored_days": 1,
        "ad_seven_day_count": 0,
        "landing_page_seven_day_count": 0,
        "product_total_count": 0,
        "cards_ad_total_count": 16560,
        "images_ad_total_count": 1063,
        "facebook_page_id": "614178972053891",
        "ad_total_count": 18263,
        "landing_page_today_count": 0,
        "landing_page_total_count": 4305,
        "avatar_url": "https://cdn.pipidata.com/images/fb4225ffd00b4c0317d905cf8392ee01975c8664abd19bb361466200a0a82d5c.png",
        "ad_today_count": 0,
        "name": "ChicMe",
        "started_at": 1761183896,
        "stoped_at":null,
        "monitor_expire_time": 1763821563,
        "category": "Clothing (Brand)",
        "status": 1
      }
    ],
    "last_page": 1,
    "current_page": 1
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "success": true,
  "fail": false
}

错误码说明

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