Pipispy APIEnglish

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

创建监控任务

本文档介绍如何通过广告主账号创建监控任务。创建监控任务支持以下四种方式:

方式 参数名 说明 示例
1. 广告主ID facebook_page_id_list 通过广告主搜索接口获取 ["614178972053891"]
2. 广告主链接 facebook_page_url_list 直接输入 Facebook 广告主主页链接 ["https://www.facebook.com/example"]
3. 公共主页编号 facebook_public_page_number_list 输入 Facebook 公共主页编号 ["123456789"]
4. 店铺/网站链接 facebook_shop_url_list 输入店铺、网站或落地页链接 ["https://example.com"]

优先级说明: 如果同时提交多个参数,系统按以下优先级使用: facebook_page_id_list > facebook_page_url_list > facebook_public_page_number_list > facebook_shop_url_list


接口一:广告主搜索

接口信息

  • 接口名称: 广告主搜索
  • 请求方法: POST
  • 接口地址: open-api/v1/monitor/data
  • 接口路径: /v3/api/ad-monitor-task/search-fb-ads-advertiser
  • 接口描述: 根据关键词搜索广告主信息,返回匹配的广告主列表。用户可以根据返回的 facebook_page_id 创建监控任务。
  • 价格说明: 免费

请求头:

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

请求参数

请求结构

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

请求体参数 (params 对象)

参数名 类型 必填 描述
name String 是 广告主名称关键词

请求示例

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/search-fb-ads-advertiser",
    "params": {
      "name": "example"
    }
  }'

响应参数

响应体结构

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "facebook_page_id": "714739975064116",
        "name": "Example Advertiser",
        "avatar_url": "https://example.com/avatar.jpg",
        "category": "Digital creator",
        "country": null
      }
    ]
  },
  "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[].facebook_page_id string 广告主ID,用于创建监控任务
data[].name string 广告主名称
data[].avatar_url string 广告主头像
data[].category string 类别
data[].country string 国家

接口二:创建监控任务

接口信息

  • 接口名称: 创建监控任务
  • 请求方法: POST
  • 接口地址: open-api/v1/monitor/data
  • 接口路径: /v3/api/ad-monitor-task/create-monitor-task
  • 接口描述: 批量创建广告主或店铺/网站的监控任务,支持四种输入方式,并返回每个任务的创建结果。
  • 价格说明: 每成功创建一个监控任务,将扣除1积分

请求头:

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

请求参数

请求结构

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

请求体参数 (params 对象)

参数名 类型 必填 描述
facebook_page_id_list array[string] 否 广告主ID列表(可通过广告主搜索接口获取)
facebook_page_url_list array[string] 否 广告主主页链接列表
facebook_public_page_number_list array[string] 否 公共主页编号列表
facebook_shop_url_list array[string] 否 店铺/网站/落地页链接列表

注意事项:

  1. 以上四个参数不能全为 null 或空列表,至少需要提供一个
  2. 每次最多可添加 50 个监控对象
  3. 如果同时提交多个参数,系统按优先级使用: facebook_page_id_list > facebook_page_url_list > facebook_public_page_number_list > facebook_shop_url_list

请求示例

方式1:通过广告主ID创建(推荐)

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/create-monitor-task",
    "params": {
      "facebook_page_id_list": ["614178972053891", "714739975064116"]
    }
  }'

方式2:通过广告主链接创建

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/create-monitor-task",
    "params": {
      "facebook_page_url_list": ["https://www.facebook.com/example"]
    }
  }'

方式3:通过公共主页编号创建

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/create-monitor-task",
    "params": {
      "facebook_public_page_number_list": ["123456789"]
    }
  }'

方式4:通过店铺/网站链接创建

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/create-monitor-task",
    "params": {
      "facebook_shop_url_list": ["https://example.com"]
    }
  }'

响应参数

响应体结构

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "task_id": "1005",
      "facebook_page_id": "614178972053891",
      "facebook_page_url": null,
      "facebook_public_page_number": null,
      "facebook_shop_url": null,
      "error_message": null
    }
  ],
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 1,
  "fail": false,
  "success": true
}

响应字段说明

字段名 类型 描述
code Integer 响应状态码,200 表示成功
message String 响应消息
data Array 响应数据(任务创建结果列表)
version String API 版本
timestamp String 响应时间戳
sign String 响应签名
success Boolean 请求是否成功
fail Boolean 请求是否失败

响应结果信息字段

字段名 类型 描述
task_id string 监控任务ID
facebook_page_id string 广告主ID
facebook_page_url string 广告主链接
facebook_public_page_number string 公共主页编号
facebook_shop_url string 店铺/网站链接
error_message string 错误信息(如有)

错误码说明

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