PPSPYAPI Platform
中文 / EN
文档/广告库/接口参考
接口参考

广告列表 API

POST/open-api/v1/advertisements/search
每获取一条记录扣除2积分·api.ppspy.com
数据与监控消耗规则

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

请求头

AUTHORIZATIONAuthorization: {API Key}
CONTENT-TYPEapplication/json
ACCEPTapplication/json

请求示例

cURL
curl --location --request POST 'https://api.ppspy.com/open-api/v1/advertisements/search' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: {API Key}' \
--data-raw '{
    "per_page": 2,
    "with_ad_status_group": "",
    "search_after": ""
}'

请求参数 59 项

按参数标注的位置传入请求。

参数 类型 说明
body
body · 可选
object | none
» extend_keywords
body · 可选
[object] 关键字搜索 | none
»» field
body · 必填
string 搜索的字段 | 可选值：all-全部，ad_content-广告文案，landing_pages-落地页URL，advertiser_name-广告主名字，product_name-产品名字。
»» value
body · 必填
string 搜索的内容 | none
»» logic_operator
body · 必填
string 逻辑运算符 | 可选值：and，or。
» exclude_keywords
body · 可选
[object] 排除关键字 | none
»» field
body · 必填
string 搜索的字段 | 可选值：all-全部，ad_content-广告文案，landing_pages-落地页URL，advertiser_name-广告主名字，product_name-产品名字。
»» value
body · 必填
string 搜索的内容 | none
»» logic_operator
body · 必填
string 逻辑运算符 | 可选值：and，or。
» source_ad_id
body · 可选
[string] 广告创意ID | none
» source_advertiser_id
body · 可选
string 广告主的主页ID | none
» advertiser_id
body · 可选
string 广告主ID | none
» first_discovered_at_start
body · 可选
integer 广告入库时间（开始） | 时间戳：秒。
» first_discovered_at_end
body · 可选
integer 广告入库时间（结束） | 时间戳：秒。
» last_discovered_at_start
body · 可选
integer 广告最后更新时间（开始） | 时间戳：秒。
» last_discovered_at_end
body · 可选
integer 广告最后更新时间（结束） | 时间戳：秒。
» country
body · 可选
[string] 地区 | none
» language
body · 可选
[string] 语言 | none
» ad_audience_reach_start
body · 可选
integer 覆盖人数（开始） | none
» ad_audience_reach_end
body · 可选
integer 覆盖人数（结束） | none
» ad_cost_start
body · 可选
number 广告花费（开始） | 单位：美元。
» ad_cost_end
body · 可选
number 广告花费（结束） | 单位：美元。
» adset_count_start
body · 可选
integer 广告组数（开始） | none
» adset_count_end
body · 可选
integer 广告组数（结束） | none
» ad_forecast
body · 可选
[integer] AI分数 | 可选值：1-测品阶段，2-上升阶段，3-盈利阶段。
» media_format
body · 可选
[integer] 媒体格式 | 可选值：1-视频，2-图片，3-轮播图。
» video_duration_start
body · 可选
integer 视频时长（开始） | 单位：秒。
» video_duration_end
body · 可选
integer 视频时长（结束） | 单位：秒。
» e_commerce_platform
body · 可选
[string] 电商平台 | none
» ad_started_at_start
body · 可选
integer 广告创建时间（开始） | 时间戳：秒。
» ad_started_at_end
body · 可选
integer 广告创建时间（结束） | 时间戳：秒。
» latest_actived_at_start
body · 可选
integer 广告最后活跃时间（开始） | 时间戳：秒。
» latest_actived_at_end
body · 可选
integer 广告最后活跃时间（开始） | 时间戳：秒。
» active_days_start
body · 可选
integer 广告时长（开始） | none
» active_days_end
body · 可选
integer 广告时长（结束） | none
» button_type
body · 可选
string 广告按钮的类型 | none
» button_text
body · 可选
[string] 广告按钮的文案 | none
» ad_status
body · 可选
[integer] 广告状态 | 可选值：1-投放中，2-已停止，3-已下架。
» ad_platform
body · 可选
[string] 广告平台 | 可选值：FACEBOOK，INSTAGRAM，AUDIENCE_NETWORK，MESSENGER，THREADS。
» landing_page_type
body · 可选
[integer] 落地页面属性 | 可选值：1-产品落地页，2-Collection落地页，3-其他。
» related_product_ids
body · 可选
[string] 广告产品ID | none
» product_category_id
body · 可选
[string] 产品分类 | none
» product_price_usd_start
body · 可选
number 产品价格（开始） | 单位：美元。
» product_price_usd_end
body · 可选
number 产品价格（结束） | 单位：美元。
» product_creation_time_start
body · 可选
integer 产品创建时间（开始） | 时间戳：秒。
» product_creation_time_end
body · 可选
integer 产品创建时间（结束） | 时间戳：秒。
» product_ad_count_start
body · 可选
integer 产品素材数（开始） | none
» product_ad_count_end
body · 可选
integer 产品素材数（结束） | none
» related_store_ids
body · 可选
[string] 广告店铺ID | none
» store_ad_count_start
body · 可选
integer 店铺素材数（开始） | none
» store_ad_count_end
body · 可选
integer 店铺素材数（结束） | none
» advertiser_ad_count_start
body · 可选
integer 店铺素材数（开始） | none
» advertiser_ad_count_end
body · 可选
integer 店铺素材数（结束） | none
» order_by
body · 可选
string 排序字段 | 可选值：ad_started_at-广告创建，adset_count-广告组数，ad_audience_reach-覆盖人数，last_discovered_at-广告最后时间，ad_cost-广告花费，advertiser_ad_count-店铺素材数，product_price_usd-产品价格(USD)，product_ad_count-产品广告素材数，product_creation_time-产品创建时间，active_days-活跃天数。
» direction
body · 可选
string 排序方式 | 可选值：desc-降序，asc-升序。
» page
body · 可选
integer 页码 | 最小值等于1。
» per_page
body · 可选
integer 分页大小 | 取值范围1-100。
» with_ad_status_group
body · 可选
string 返回广告状态的数量统计 | none
» search_after
body · 可选
string 深度翻页的游标 | 如果需要使用该方式，第一页也需要传该参数，值为空字符串即可

返回示例

返回示例 · JSON
{
    "code": 200,
    "message": "success",
    "data": {
        "current_page": 1,
        "data": [
            {
                "id": "00f5f0c2b0ce40761647d7a5d7e75513",
                "advertiser_id": "3090fedf58920c291647d7a5d7e75513",
                "source_ad_id": "1105227591029056",
                "ad_source": 1,
                "ad_content": "🔥 Enjoy 30% OFF! 🔥 Elevate the kitchen experience with the 360° Touch Sensor Faucet – where sleek design meets unmatched convenience. Tap 'Shop Now' to grab it before the offer ends!",
                "ad_link": "https://www.facebook.com/ads/library/?id=1105227591029056",
                "first_discovered_at": 1731337040,
                "last_discovered_at": 1731337040,
                "country": [
                    "other"
                ],
                "language": "en",
                "adset_count": 2,
                "ad_forecast": 1,
                "media_format": 1,
                "images": [],
                "videos": [
                    {
                        "url": "https://fb-cdn.pipiads.com/videos/37a439989b2f6519b00b84a662776863.mp4",
                        "width": 720,
                        "height": 1280,
                        "duration": 22,
                        "cover_url": "https://fb-cdn.pipiads.com/images/c41d740f3cf32a0845e37d178f25da8c.png"
                    }
                ],
                "cards": [],
                "e_commerce_platform": "shopify",
                "ad_started_at": 1730880000,
                "ad_ended_at": 1730880000,
                "latest_actived_at": 1730880000,
                "active_days": 1,
                "button_type": "SHOP_NOW",
                "ad_status": 1,
                "ad_platform": [
                    "FACEBOOK",
                    "INSTAGRAM",
                    "AUDIENCE_NETWORK",
                    "MESSENGER"
                ],
                "landing_page_type": 3,
                "landing_pages": [
                    "https://thetrendygenie.com/products/aquaflex-3-in-1-touch-360-waterfall-kitchen-faucet?_pos=2&_sid=4ae83932e&_ss=r"
                ],
                "related_product_ids": null,
                "e_commerce_types": null,
                "related_store_ids": null,
                "store_adset_count": null,
                "ad_audience": null,
                "ad_audience_reach": null,
                "ad_cost": null,
                "button_text": "Shop now",
                "ad_title": "⭐⭐⭐⭐⭐4.8/5",
                "advertiser": {
                    "id": "3090fedf58920c291647d7a5d7e75513",
                    "source_advertiser_id": "341566439037032",
                    "name": "The Trendy Genie",
                    "like_count": 4248,
                    "ad_count": 5,
                    "profile_picture_url": "https://fb-cdn.pipiads.com/images/35f750aa7026188e51f447e6572e9c07.png",
                    "source_advertiser_link": "https://facebook.com/61559353875301",
                    "adset_count": 7,
                    "e_commerce_platform": "shopify",
                    "ad_country": [
                        "other"
                    ],
                    "user_blocked": 2,
                    "ads_library_link": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&is_targeted_country=false&media_type=all&search_type=page&view_all_page_id=341566439037032"
                },
                "store": null,
                "products": [],
                "user_collected": 2
            },
            {
                "id": "06791ffeb1266589614c026fc1b67094",
                "advertiser_id": "6963d214a28ad4e5614c026fc1b67094",
                "source_ad_id": "449661834809540",
                "ad_source": 1,
                "ad_content": "You’re a shining star!💫 Get yourself something special using code SINGLES for an extra 11% off hair care, styling tools, and Value Sets. The Singles Day Sale ends 11/12/24.",
                "ad_link": "https://www.facebook.com/ads/library/?id=449661834809540",
                "first_discovered_at": 1731337037,
                "last_discovered_at": 1731337037,
                "country": [
                    "other"
                ],
                "language": "en",
                "adset_count": 1,
                "ad_forecast": 1,
                "media_format": 2,
                "images": [
                    {
                        "url": "https://fb-cdn.pipiads.com/images/c0a551aac5a6e65a8956d77be7b3740c.png",
                        "width": 1080,
                        "height": 1350
                    }
                ],
                "videos": [],
                "cards": [],
                "e_commerce_platform": "shopify",
                "ad_started_at": 1730880000,
                "ad_ended_at": 1730880000,
                "latest_actived_at": 1730880000,
                "active_days": 1,
                "button_type": "SHOP_NOW",
                "ad_status": 1,
                "ad_platform": [
                    "FACEBOOK",
                    "INSTAGRAM",
                    "AUDIENCE_NETWORK",
                    "MESSENGER"
                ],
                "landing_page_type": 3,
                "landing_pages": [
                    "http://t.langehair.com/SHJME"
                ],
                "related_product_ids": null,
                "e_commerce_types": null,
                "related_store_ids": null,
                "store_adset_count": null,
                "ad_audience": null,
                "ad_audience_reach": null,
                "ad_cost": null,
                "button_text": "Shop now",
                "ad_title": "The Singles Day Sale!💫",
                "advertiser": {
                    "id": "6963d214a28ad4e5614c026fc1b67094",
                    "source_advertiser_id": "588069391390106",
                    "name": "L'ange",
                    "like_count": 1174217,
                    "ad_count": 7,
                    "profile_picture_url": "https://fb-cdn.pipiads.com/images/c40e505f672b7377d1e5dd03207fa80d.png",
                    "source_advertiser_link": "https://facebook.com/getlange",
                    "adset_count": 14,
                    "e_commerce_platform": "shopify",
                    "ad_country": [
                        "other",
                        "US",
                        "FR"
                    ],
                    "user_blocked": 2,
                    "ads_library_link": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&is_targeted_country=false&media_type=all&search_type=page&view_all_page_id=588069391390106"
                },
                "store": null,
                "products": [],
                "user_collected": 2
            }
        ],
        "last_page": 8096,
        "per_page": 2,
        "to": 2,
        "total": 16191,
        "ad_status_group": {
            "ad_status_all": 16191,
            "ad_status_1": 15993,
            "ad_status_2": 11,
            "ad_status_3": 187
        },
        "search_after": [
            1730880000,
            "06791ffeb1266589614c026fc1b67094"
        ],
        "has_more": true
    },
    "credits": {
        "remaining_credits": 745,
        "consumed_credits": 0,
        "total_credits": 745
    }
}
文档中的示例数据

返回数据结构

名称 类型 必选 约束 中文名 说明
» code integer true none 业务状态码 none
» message string true none 响应的消息 none
» data object true none 响应的数据 none
»» current_page integer true none 当前页码 none
»» data [object] true none 数据列表 none
»»» id string true none 广告ID none
»»» source_ad_id string true none 广告创意ID none
»»» country [string]¦null true none 地区 none
»»» adset_count integer true none 广告组数 none
»»» ad_audience_reach integer¦null true none 覆盖人数 none
»»» ad_cost number¦null true none 广告花费 none
»»» ad_ended_at integer¦null true none 广告结束时间 时间戳：秒。
»»» ad_started_at integer¦null true none 广告创建时间 时间戳：秒。
»»» latest_actived_at integer¦null true none 广告最后活跃时间 时间戳：秒。
»»» first_discovered_at integer¦null true none 广告入库时间 时间戳：秒。
»»» last_discovered_at integer true none 广告最后更新时间 时间戳：秒。
»»» ad_content string¦null true none 广告文案 none
»»» active_days integer¦null true none 活跃天数 none
»»» landing_pages [string]¦null true none 落地页URL none
»»» ad_status integer¦null true none 广告状态 可选值：1-投放中，2-已停止，3-已下架。
»»» ad_forecast integer¦null true none AI分数 none
»»» ad_platform [string]¦null true none 广告平台 none
»»» ad_audience object¦null true none 覆盖&受众 none
»»»» total_reach integer true none 覆盖人数 none
»»»» gender_audience string¦null true none 群体 none
»»»» age_audience object true none 受众的年龄 none
»»»»» min integer¦null true none 最小的年龄 none
»»»»» max integer¦null true none 最大的年龄 none
»»»» details [object] true none 受众地区明细 none
»»»»» country string true none 受众地区 none
»»»»» total_reach integer true none 覆盖人数 none
»»»»» age_gender_breakdowns [object] true none 受众明细 none
»»»»»» age_range string¦null true none 年龄段 none
»»»»»» male integer¦null true none 男性的数量 none
»»»»»» female integer¦null true none 女性的数量 none
»»»»»» unknown integer¦null true none 其它的数量 none
»»» language string¦null true none 语言 none
»»» media_format integer¦null true none 媒体格式 none
»»» button_type string¦null true none 广告按钮的类型 none
»»» landing_page_type integer¦null true none 落地页面属性 none
»»» products [object]¦null true none 产品列表 none
»»»» id string true none none
»»»» name string true none 产品名字 none
»»»» price number true none 产品价格 none
»»»» price_usd number true none 产品价格（美元） none
»»»» ad_count integer true none 产品广告素材数 none
»»»» category_id string¦null true none 分类ID none
»»»» category_name string¦null true none 分类名称 none
»»»» creation_time integer¦null true none 创建时间 none
»»»» image_url string¦null true none 产品图片 none
»»»» ad_started_at integer true none 广告开始时间 none
»»»» ad_ended_at integer true none 广告结束时间 none
»»»» ad_cost number¦null true none 广告花费 单位：美元。
»»»» total_revenue number¦null true none 产品的收入 单位：美元。
»»»» ad_cost_ratio number¦null true none 产品在这个广告的花费的比例 取值范围：0~1。
»»»» currency string¦null true none 货币 none
»»»» source_product_link string true none 产品链接 none
»»» advertiser object¦null true none 广告主 none
»»»» id string true none 广告主ID none
»»»» source_advertiser_id string true none 广告主的主页ID none
»»»» name string true none 广告主的名字 none
»»»» ad_count integer true none 广告主的素材数 none
»»»» like_count integer¦null true none 广告主的点赞数 none
»»»» profile_picture_url string¦null true none 广告主头像的链接 none
»»»» source_advertiser_link string¦null true none 广告主的主页链接 none
»»»» adset_count integer¦null true none 广告主的广告组数 none
»»»» e_commerce_platform string¦null true none 电商平台 none
»»»» ad_country [string] true none 投放国家 none
»»»» user_blocked integer true none 是否已屏蔽 1-是，2-否。
»»»» ads_library_link string true none 广告主的广告库链接 none
»»» images [object] true none 图片列表 none
»»»» url string true none 图片的链接 none
»»»» width integer¦null true none 图片的宽度 none
»»»» height integer¦null true none 图片的高度 none
»»» videos [object] true none 视频列表 none
»»»» url string true none 视频的链接 none
»»»» cover_url string¦null true none 视频的封面图链接 none
»»»» width integer¦null true none 视频的宽度 none
»»»» height integer¦null true none 视频的高度 none
»»»» duration integer¦null true none 视频的时长 单位：秒。
»»» cards [object] true none 轮播图 none
»»»» media_type integer true none 媒体类型 可选值：1-视频，2-图片。
»»»» url string true none 视频/图片的链接 none
»»»» cover_url string¦null true none 视频的封面图链接 none
»»»» width integer¦null true none 视频/图片的宽度 none
»»»» height integer¦null true none 视频/图片的高度 none
»»»» duration integer¦null true none 视频的时长 单位：秒。
»»» store object¦null true none 广告店铺 none
»»»» id string true none 广告店铺ID none
»»»» name string true none 店铺名称 none
»»»» ad_count integer true none 店铺素材数 none
»»»» e_commerce_platform string¦null true none 电商平台 none
»»»» e_commerce_types [integer]¦null true none 电商类型 可选值：1-Dropshipping，2-Print on demand (POD)，3-Cash/collect on delivery (COD)，4-Digital products。
»»»» logo_url string¦null true none 店铺logo none
»»»» source_store_link string¦null true none 店铺链接 none
»»» user_collected integer true none 是否已收藏 可选值：1-未收藏，2-已收藏。
»»» button_text string¦null true none 广告按钮的文案 none
»»» ad_title string¦null true none 广告标题 none
»» last_page integer true none 最后一页的页码 none
»» per_page integer true none 分页大小 none
»» total integer true none 总数据量 none
»» ad_status_group object¦null false none 广告状态的数量统计 请求参数中设置了with_ad_status_group才会返回。
»»» ad_status_all integer true none 全部 none
»»» ad_status_1 integer true none 投放中的数量 none
»»» ad_status_2 integer true none 已停止的数量 none
»»» ad_status_3 integer true none 已下架的数量 none
»» search_after [any] false none 深度翻页的游标 请求参数中设置了search_after才会返回。
»» has_more boolean false none 是否有下一页 请求参数中设置了search_after才会返回。
» credits object true none Credits 信息 当前 API 请求对应的 credits 信息
»» remaining_credits integer true none 剩余 credits 本次请求后剩余的 credits 数量
»» consumed_credits integer true none 消耗 credits 本次请求消耗的 credits 数量
»» total_credits integer true none 总 credits 当前 credits 类型的总数量
原始接口信息与服务地址

Base URLs

  • 生产环境: https://api.ppspy.com

接口信息

  • 接口名称: 广告列表
  • 请求方法: POST
  • 接口地址: /open-api/v1/advertisements/search
  • 价格说明: 每获取一条记录扣除2积分
GET查询当前积分/open-api/v1/creditsGETShopify店铺列表/open-api/v1/shopGETShopify店铺详情/open-api/v1/shop/{id}GET店铺流量列表/open-api/v1/shop/traffic-shopGET单商品店铺列表/open-api/v1/shop/single-product-shopGET店铺主题模版库/open-api/v1/shop/theme-shopGETShopify产品列表/open-api/v1/productGETShopify畅销产品列表/open-api/v1/bestsellersPOST广告列表/open-api/v1/advertisements/searchGET广告详情/open-api/v1/advertisements/{id}POST广告店铺列表/open-api/v1/ad-stores/searchGET广告店铺详情/open-api/v1/ad-stores/{id}GET广告店铺的落地页统计/open-api/v1/ad-stores/landing-pages-ad-countGET店铺的广告趋势/open-api/v1/ad-stores/analysisGET店铺的投放分析/open-api/v1/ad-stores/deep-analysisGET店铺的广告文案 最多使用/open-api/v1/ad-stores/ad-contentGET店铺的广告文案 最长运营/open-api/v1/ad-stores/ad-content-longest-runGET店铺的广告主/open-api/v1/ad-stores/advertisersPOST广告产品列表/open-api/v1/ad-products/searchGET广告产品详情/open-api/v1/ad-products/{id}POST创建分组/open-api/v1/ad-monitor-groupsGET分组列表/open-api/v1/ad-monitor-groupsPUT编辑分组/open-api/v1/ad-monitor-groups/{id}DELETE删除分组/open-api/v1/ad-monitor-groups/{id}POST搜索广告主/open-api/v1/ad-monitor-task/search-fb-ads-advertiser
来自现有接口目录与文档 · 支持接口名称和地址搜索