Pipispy APIEnglish

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

店铺 Meta 广告资料库最长运营广告文案列表接口

接口信息

  • 接口名称: 获取店铺最长运营广告文案列表
  • 请求方法: POST
  • 接口地址: /open-api/v1/data
  • 接口路径: /v3/api/open/ppspy/pp-stores/ad-content/longest-run
  • 接口描述: 获取指定店铺在Meta广告资料库中运营时间最长的广告文案列表,包括广告内容、媒体素材(图片/视频/轮播)、投放天数等信息,帮助分析店铺的长期稳定投放的广告素材
  • 价格说明: 免费

请求头:

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

请求参数

请求结构

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

请求体参数 (params 对象)

参数名 类型 必填 描述
id String 是 店铺唯一标识ID,为13位字符串(例如:c2d5b2547218a),对应店铺榜单列表接口返回结果中的 store_id 字段
order_by String 否 排序字段。可选值:active_days-按投放天数排序,ad_started_at-按广告开始时间排序。默认值:active_days
direction String 否 排序方式。可选值:desc-降序(从大到小/从新到旧),asc-升序(从小到大/从旧到新)。默认值:desc
page_size Long 否 每页记录数,指定单页返回的广告数量。默认值:20
current_page Long 否 当前页码,页码从1开始。默认值:1

请求示例

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/ad-content/longest-run",
    "params": {
        "id": "c2d5b2547218a",
        "order_by": "active_days",
        "direction": "desc",
        "page_size": 20,
        "current_page": 1
    }
  }'

响应参数

响应体结构

{
  "code": 200,
  "message": "success",
  "data": {
    "current_page": 1,
    "data": [],
    "first_page_url": "",
    "from": 1,
    "is_logged_in": false,
    "last_page": 1,
    "last_page_url": "",
    "next_page_url": null,
    "path": "",
    "per_page": 20,
    "prev_page_url": null,
    "to": 20,
    "total": 100
  },
  "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)

字段名 类型 描述
current_page Long 当前页码
data Array 广告内容列表
first_page_url String 第一页的URL地址
from Long 起始记录位置(当前页第一条记录在总结果集中的位置)
is_logged_in Boolean 用户是否已登录,用于标识数据权限状态
last_page Long 最后一页的页码(总页数)
last_page_url String 最后一页的URL地址
next_page_url String 下一页的URL地址,如果没有下一页则为null
path String API请求路径
per_page Long 每页记录数
prev_page_url String 上一页的URL地址,如果没有上一页则为null
to Long 结束记录位置(当前页最后一条记录在总结果集中的位置)
total Long 总记录数

广告内容字段 (AdContent)

字段名 类型 描述
id String 广告唯一标识ID
source_ad_id String 原始广告ID(来源平台的广告唯一标识)
ad_content String 广告文案内容
media_format Long 媒体格式类型。1-单图,2-单视频,3-轮播
images Array 图片素材列表,当 media_format=1 时有值
videos Array 视频素材列表,当 media_format=2 时有值
cards Array 轮播卡片列表,当 media_format=3 时有值
ad_started_at Long 广告开始投放时间,Unix时间戳(秒级)
active_days Long 广告投放天数(从开始到现在或结束的天数)
ad_status Long 广告状态。1-活跃投放中,2-不活跃,3-下架
ad_content_md5 String 广告内容的MD5哈希值,用于标识相同内容的广告

图片素材字段 (Image)

字段名 类型 描述
url String 图片资源URL地址
width Long 图片宽度(像素)
height Long 图片高度(像素)

视频素材字段 (Video)

字段名 类型 描述
url String 视频资源URL地址
width Long 视频宽度(像素)
height Long 视频高度(像素)
duration Double 视频时长(秒)
cover_url String 视频封面图URL地址

轮播卡片字段 (Card)

字段名 类型 描述
url String 卡片媒体资源URL地址(图片或视频)
width Long 媒体宽度(像素)
height Long 媒体高度(像素)
duration Double 视频时长(秒),仅当 media_type=1 时有值
cover_url String 视频封面图URL地址,仅当 media_type=1 时有值
media_type Long 媒体类型。1-视频,2-图片

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": "ad_001",
        "source_ad_id": "123456789012345",
        "ad_content": "Shop now and get 50% off! Limited time offer. Free shipping on orders over $50.",
        "media_format": 2,
        "images": [],
        "videos": [
          {
            "url": "https://example.com/video/ad_video_001.mp4",
            "width": 1080,
            "height": 1920,
            "duration": 15.5,
            "cover_url": "https://example.com/cover/ad_cover_001.jpg"
          }
        ],
        "cards": [],
        "ad_started_at": 1680000000,
        "active_days": 180,
        "ad_status": 1,
        "ad_content_md5": "a1b2c3d4e5f6g7h8i9j0"
      },
      {
        "id": "ad_002",
        "source_ad_id": "123456789012346",
        "ad_content": "New arrivals! Check out our latest collection.",
        "media_format": 3,
        "images": [],
        "videos": [],
        "cards": [
          {
            "url": "https://example.com/image/card_001.jpg",
            "width": 1080,
            "height": 1080,
            "duration": null,
            "cover_url": null,
            "media_type": 2
          },
          {
            "url": "https://example.com/video/card_002.mp4",
            "width": 1080,
            "height": 1080,
            "duration": 10,
            "cover_url": "https://example.com/cover/card_002.jpg",
            "media_type": 1
          }
        ],
        "ad_started_at": 1685000000,
        "active_days": 120,
        "ad_status": 1,
        "ad_content_md5": "b2c3d4e5f6g7h8i9j0k1"
      },
      {
        "id": "ad_003",
        "source_ad_id": "123456789012347",
        "ad_content": "Best seller! Don't miss out.",
        "media_format": 1,
        "images": [
          {
            "url": "https://example.com/image/ad_image_001.jpg",
            "width": 1200,
            "height": 628
          }
        ],
        "videos": [],
        "cards": [],
        "ad_started_at": 1690000000,
        "active_days": 90,
        "ad_status": 0,
        "ad_content_md5": "c3d4e5f6g7h8i9j0k1l2"
      }
    ],
    "first_page_url": "https://api.example.com/ads?page=1",
    "from": 1,
    "is_logged_in": false,
    "last_page": 5,
    "last_page_url": "https://api.example.com/ads?page=5",
    "next_page_url": "https://api.example.com/ads?page=2",
    "path": "https://api.example.com/ads",
    "per_page": 20,
    "prev_page_url": null,
    "to": 20,
    "total": 100
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "success": true,
  "fail": false
}

错误码说明

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