接口参考

广告详情 API

GET/open-api/v1/advertisements/{id}

·api.ppspy.com

数据与监控消耗规则

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

请求头

AUTHORIZATIONAuthorization: {API Key}

CONTENT-TYPEapplication/json

ACCEPTapplication/json

请求示例

cURL

curl --location --request GET 'https://api.ppspy.com/open-api/v1/advertisements/e0b433132cf6dbafb09243e4b5fc5fe1' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: {API Key}'

请求参数 1 项

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

参数	类型	说明
id path · 必填	string	广告ID \|

返回示例

返回示例 · JSON

{
    "code": 200,
    "message": "success",
    "data": {
        "advertisement": {
            "id": "e0b433132cf6dbafb09243e4b5fc5fe1",
            "advertiser_id": "ed20f6b1d42e31d1b09243e4b5fc5fe1",
            "source_ad_id": "4123806491240834",
            "ad_source": 1,
            "ad_content": "Tired of tanning products that dry out or irritate your skin? Decadence by BeautiEdit changes everything. It’s a luxurious gradual tanning cream that nourishes your skin while adding a radiant gradual glow. \n\nNo streaks, No fuss just a nourishing, hydrated glow to your skin. \n\nMake tanning part of your skin-care routine, try Decadence by Lorraine Keane Today!",
            "ad_link": "https:\/\/www.facebook.com\/ads\/library\/?id=4123806491240834",
            "first_discovered_at": 1754591870,
            "last_discovered_at": 1754591870,
            "country": [
                "GB",
                "IE"
            ],
            "language": "en",
            "adset_count": 4,
            "ad_forecast": 1,
            "media_format": 1,
            "images": [],
            "videos": [
                {
                    "url": "https:\/\/fb-cdn.ppspy.com\/videos\/87d2d6c5c900e5ff035aabc106c8ceaf.mp4",
                    "width": 720,
                    "height": 1280,
                    "duration": 25.633333333333333,
                    "cover_url": "https:\/\/fb-cdn.ppspy.com\/images\/a73b21b9cc50258ba82bdc20d6915943.png"
                }
            ],
            "cards": [],
            "e_commerce_platform": "shopify",
            "ad_started_at": 1754550000,
            "ad_ended_at": 1754550000,
            "latest_actived_at": 1754550000,
            "active_days": 1,
            "button_type": "SHOP_NOW",
            "ad_status": 1,
            "ad_platform": [
                "FACEBOOK",
                "INSTAGRAM",
                "AUDIENCE_NETWORK",
                "MESSENGER",
                "THREADS"
            ],
            "landing_page_type": 1,
            "landing_pages": [
                "https:\/\/www.beautiedit.co.uk\/products\/decadence-by-lorraine-keane"
            ],
            "related_product_ids": [
                "80a48db50a11fbcaf2d7255e126a510d"
            ],
            "e_commerce_types": null,
            "related_store_ids": [
                "e591b0461e390666f2d7255e126a510d"
            ],
            "store_adset_count": null,
            "ad_audience": {
                "details": [
                    {
                        "country": "IE",
                        "total_reach": 13,
                        "age_gender_breakdowns": [
                            {
                                "male": 0,
                                "female": 0,
                                "unknown": 1,
                                "age_range": "18-24"
                            },
                            {
                                "male": 0,
                                "female": 3,
                                "unknown": 0,
                                "age_range": "25-34"
                            },
                            {
                                "male": 0,
                                "female": 4,
                                "unknown": 0,
                                "age_range": "35-44"
                            },
                            {
                                "male": 0,
                                "female": 24,
                                "unknown": 1,
                                "age_range": "45-54"
                            },
                            {
                                "male": 1,
                                "female": 30,
                                "unknown": 2,
                                "age_range": "55-64"
                            },
                            {
                                "male": 0,
                                "female": 13,
                                "unknown": 0,
                                "age_range": "65+"
                            }
                        ]
                    },
                    {
                        "country": "GB",
                        "total_reach": 1,
                        "age_gender_breakdowns": [
                            {
                                "male": 0,
                                "female": 1,
                                "unknown": 0,
                                "age_range": "45-54"
                            },
                            {
                                "male": 0,
                                "female": 1,
                                "unknown": 0,
                                "age_range": "65+"
                            }
                        ]
                    }
                ],
                "total_reach": 80,
                "age_audience": {
                    "max": 65,
                    "min": 18
                },
                "gender_audience": "All"
            },
            "ad_audience_reach": 80,
            "ad_cost": 1.56,
            "ad_caption": "www.beautiedit.co.uk",
            "ad_title": "Hydrate, Nourish, and Radiate your skin",
            "ad_link_description": null,
            "button_text": "Shop now",
            "advertiser": {
                "id": "ed20f6b1d42e31d1b09243e4b5fc5fe1",
                "source_advertiser_id": "105480794477709",
                "name": "BeautiEdit",
                "like_count": 4053,
                "ad_count": 602,
                "profile_picture_url": "https:\/\/fb-cdn.ppspy.com\/images\/596132196b0f1eea5f1783d36d94854e.png",
                "source_advertiser_link": "https:\/\/facebook.com\/BeautiEdit",
                "adset_count": 999,
                "e_commerce_platform": "shopify",
                "ad_country": [
                    "IE",
                    "GB",
                    "other",
                    "LT",
                    "CY",
                    "ES",
                    "FR",
                    "PL",
                    "BG",
                    "PT",
                    "EE",
                    "IT",
                    "GR",
                    "JP"
                ],
                "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=105480794477709",
                "user_blocked": 2
            },
            "size": "9:16",
            "clarity": "FHD",
            "aspect_ratio": "720x1280",
            "products": [
                {
                    "id": "80a48db50a11fbcaf2d7255e126a510d",
                    "store_id": "e591b0461e390666f2d7255e126a510d",
                    "name": "Decadence by Lorraine Keane **Limited Edition**",
                    "source_product_link": "https:\/\/www.beautiedit.com\/products\/decadence-by-lorraine-keane",
                    "currency": "EUR",
                    "price": 30,
                    "price_usd": 34.91,
                    "ad_count": 19,
                    "category_id": "62739ba438365b2f72048ec9",
                    "creation_time": 1668601826,
                    "images": [
                        "images\/pimg_de334c56ff3495f861da.png",
                        "images\/pimg_ce254c9085fdbc6d341b.png",
                        "images\/pimg_9ca2dad76211178d0ec8.png",
                        "images\/pimg_e526af57cf7a09cc281a.png",
                        "images\/pimg_1180eabe98c0101e1abc.png"
                    ],
                    "ad_cost": 436.86,
                    "category": {
                        "id": "62739ba438365b2f72048ec9",
                        "name_en": "Beauty & Health"
                    },
                    "image_url": "https:\/\/fb-cdn.ppspy.com\/images\/pimg_de334c56ff3495f861da.png",
                    "category_name": "Beauty & Health"
                }
            ],
            "store": {
                "id": "e591b0461e390666f2d7255e126a510d",
                "name": "BeautiEdit",
                "ad_count": 599,
                "e_commerce_platform": "shopify",
                "e_commerce_types": null,
                "logo_url": "http:\/\/www.beautiedit.com\/cdn\/shop\/files\/fav.png?v=1667884772&width=180",
                "source_store_link": "https:\/\/www.beautiedit.com",
                "category_ids": [
                    "62739ba438365b2f72048ec9"
                ],
                "categories": [
                    {
                        "id": "62739ba438365b2f72048ec9",
                        "name_en": "Beauty & Health",
                        "name_zh": "美容与健康"
                    }
                ]
            },
            "user_collected": 2
        },
        "ads_history": {
            "adset_count": {
                "timeline": [
                    {
                        "date": "2025-08-07",
                        "count": 4
                    }
                ]
            },
            "ad_cost": {
                "timeline": [
                    {
                        "date": "2025-08-07",
                        "count": 1.56
                    }
                ]
            }
        }
    },
    "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
»» advertisement	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	广告花费	单位：美元。
»»» 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分数	可选值：1-测品阶段，2-上升阶段，3-盈利阶段。
»»» 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	群体	可选值：Women、All、Men、空（null）。
»»»» 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	媒体格式	可选值：1-视频，2-图片，3-轮播图。
»»» button_type	string¦null	true	none	广告按钮的类型	none
»»» landing_page_type	integer¦null	true	none	落地页面属性	可选值：1-产品落地页，2-Collection落地页，3-其他。
»»» products	[object]¦null	true	none	产品列表	none
»»»» id	string	true	none	产品ID	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	创建时间	时间戳：秒。
»»»» image_url	string¦null	true	none	产品图片	none
»»»» currency	string¦null	true	none	货币	none
»»»» source_product_link	string	true	none	产品链接	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	电商类型	none
»»»» logo_url	string¦null	true	none	店铺logo	none
»»»» source_store_link	string¦null	true	none	店铺链接	none
»»»» categories	[object]¦null	true	none	店铺分类	none
»»»»» id	string	true	none	产品分类ID	none
»»»»» name_en	string	true	none	分类的英文名称	none
»»»»» name_zh	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
»»»» user_blocked	integer	true	none	是否已屏蔽	1-是，2-否。
»»»» ad_country	[string]	true	none	广告投放国家	none
»»»» 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	视频的时长	单位：秒。
»»» ad_caption	string¦null	true	none	广告描述	none
»»» ad_title	string¦null	true	none	广告标题	none
»»» ad_link_description	string¦null	true	none	广告链接描述	none
»»» ad_link	string¦null	true	none	广告链接	none
»»» user_collected	integer	true	none	是否已收藏	可选值：1-未收藏，2-已收藏。
»»» button_text	string¦null	true	none	广告按钮的文案	none
»»» size	string¦null	true	none	尺寸比例	none
»»» clarity	string¦null	true	none	清晰度	none
»»» aspect_ratio	string¦null	true	none	分辨率	none
»» ads_history	object	true	none	广告历史	none
»»» adset_count	object	true	none	广告组数	none
»»»» timeline	[object]	true	none	时间轴	none
»»»»» date	string	true	none	日期	UTC时间。
»»»»» count	number	true	none	数量	none
»»» ad_cost	object	true	none	广告花费	none
»»»» timeline	[object]	true	none	时间轴	none
»»»»» date	string	true	none	日期	UTC时间。
»»»»» count	number	true	none	花费	单位：美元。
» 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

接口信息

接口名称: 广告详情
请求方法: GET
接口地址: /open-api/v1/advertisements/{id}
使用限制：使用本接口前，请先通过广告列表接口获取 id，并在有效期内使用，过期请重新获取，否则接口会返回403002