接口参考

广告店铺列表 API

POST/open-api/v1/ad-stores/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/ad-stores/search' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: {API Key}' \
--data-raw '{
    "page": 1,
    "per_page": 2
}'

请求参数 41 项

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

参数	类型	说明
body body · 可选	object	\| none
» extend_keywords body · 可选	[object]	关键词搜索 \| none
»» field body · 必填	string	搜索的字段 \| 可选值：all-全部，store_name-店铺名称，store_link-店铺URL，advertiser_name-广告主名称，product_name-产品名称。
»» value body · 必填	string	搜索的内容 \| none
»» logic_operator body · 必填	string	逻辑运算符 \| 可选值：and，or。
» exclude_keywords body · 可选	[object]	排除关键字 \| none
»» field body · 必填	string	搜索的字段 \| 可选值：all-全部，store_name-店铺名称，store_link-店铺URL，advertiser_name-广告主名称，product_name-产品名称。
»» value body · 必填	string	搜索的内容 \| none
»» logic_operator body · 必填	string	逻辑运算符 \| 可选值：and，or。
» e_commerce_platform body · 可选	[string]	电商平台 \| none
» ad_status body · 可选	integer	广告状态 \| 可选值：1-活跃中，2-已停止。
» category_ids body · 可选	[string]	产品分类ID \| none
» ad_country body · 可选	[string]	广告投放国家 \| none
» ad_product_count_start body · 可选	integer	广告产品数（开始） \| none
» ad_product_count_end body · 可选	integer	广告产品数（结束） \| none
» language body · 可选	[string]	店铺语言 \| none
» month_visits_start body · 可选	integer	店铺月流量（开始） \| none
» month_visits_end body · 可选	integer	店铺月流量（结束） \| none
» advertiser_count_start body · 可选	integer	广告主数量（开始） \| none
» advertiser_count_end body · 可选	integer	广告主数量（结束） \| none
» active_adset_count_start body · 可选	integer	活跃广告组数（开始） \| none
» active_adset_count_end body · 可选	integer	活跃广告组数（结束） \| none
» adset_count_start body · 可选	integer	总广告组数（开始） \| none
» adset_count_end body · 可选	integer	总广告组数（结束） \| none
» ad_count_start body · 可选	integer	广告素材数（开始） \| none
» ad_count_end body · 可选	integer	广告素材数（结束） \| 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	广告花费（结束） \| 单位：美元。
» active_days_start body · 可选	integer	广告天数（开始） \| none
» active_days_end body · 可选	integer	广告天数（结束） \| none
» ad_started_at_start body · 可选	integer	广告开始时间（开始） \| 时间戳：秒。
» ad_started_at_end body · 可选	integer	广告开始时间（结束） \| 时间戳：秒。
» ad_ended_at_start body · 可选	integer	广告结束时间（开始） \| 时间戳：秒。
» ad_ended_at_end body · 可选	integer	广告结束时间（结束） \| 时间戳：秒。
» order_by body · 可选	string	排序字段 \| 可选值：ad_started_at-广告开始时间，month_visits-店铺月流量，active_adset_count-活跃广告组数，adset_count-总广告组数，ad_count-广告素材数，ad_audience_reach-覆盖人数，ad_cost-广告花费，active_days-广告天数，ad_ended_at-广告结束时间。
» direction body · 可选	string	排序方式 \| 可选值：desc-降序，asc-升序。
» page body · 可选	integer	页码 \| 最小值等于1。
» per_page body · 可选	integer	分页大小 \| 取值范围1-100。
» ids body · 可选	[string]	广告店铺ID \| none

返回示例

返回示例 · JSON

{
    "code": 200,
    "message": "success",
    "data": {
        "current_page": 2,
        "data": [
            {
                "id": "3da0b54f87306bebc81196bcf8cdba02",
                "name": "bloery",
                "logo_url": null,
                "e_commerce_platform": "shopify",
                "source_store_link": "https://bloery.com",
                "source_store_domain": "e0fefd-f3.myshopify.com",
                "ad_product_count": 0,
                "month_visits": null,
                "ad_country": [],
                "ad_status": 1,
                "adset_count": 1,
                "active_ad_count": 1,
                "inactive_ad_count": 0,
                "removed_ad_count": 0,
                "ad_count": 1,
                "ad_audience_reach": 0,
                "ad_cost": 0,
                "active_days": 1,
                "ad_started_at": 1728370800,
                "ad_ended_at": 1728370800,
                "advertiser_count": 1,
                "active_adset_count": 1,
                "new_advertisements": [
                    {
                        "id": "257fe7826750a7c6ddfc2977c27658a9",
                        "media_format": 1,
                        "images": [],
                        "videos": [
                            {
                                "url": "https://fb-cdn.pipiads.com/videos/f5974b833b4959cca9c1ca3552b6a39a.mp4",
                                "width": 720,
                                "height": 1280,
                                "duration": 6,
                                "cover_url": "https://fb-cdn.pipiads.com/images/49a2336296f1d09c872d2d078bf14fff.png"
                            }
                        ],
                        "cards": []
                    }
                ],
                "advertisers": [
                    {
                        "id": "095ee5d9bf6b0b4bddfc2977c27658a9",
                        "name": "Bloery",
                        "profile_picture_url": "https://fb-cdn.pipiads.com/images/06df50c2211137e09471ad37030c195b.png",
                        "category_name": null,
                        "like_count": 13,
                        "creation_time": null,
                        "ad_platform": [
                            "FACEBOOK",
                            "INSTAGRAM",
                            "AUDIENCE_NETWORK",
                            "MESSENGER"
                        ],
                        "ad_source": 1,
                        "source_advertiser_id": "383656001491233",
                        "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=383656001491233"
                    }
                ],
                "new_ad_products": [],
                "user_collected": 2
            },
            {
                "id": "ad07cd980178cd704dc9d44127671606",
                "name": "Clothes By Locker Room",
                "logo_url": null,
                "e_commerce_platform": "shopify",
                "source_store_link": "https://clothesbylockerroom.com",
                "source_store_domain": "clothe-by-locker-room.myshopify.com",
                "ad_product_count": 0,
                "month_visits": null,
                "ad_country": [
                    "CY",
                    "HU",
                    "SE",
                    "DK",
                    "PL",
                    "MF",
                    "ES",
                    "BE",
                    "FI",
                    "HR",
                    "IT",
                    "GR",
                    "FR",
                    "RO",
                    "MT",
                    "IE",
                    "GP",
                    "MQ",
                    "SI",
                    "SK",
                    "RE",
                    "DE",
                    "LV",
                    "EE",
                    "LT",
                    "GF",
                    "CZ",
                    "LU",
                    "AT",
                    "NL",
                    "PT",
                    "YT"
                ],
                "ad_status": 1,
                "adset_count": 1,
                "active_ad_count": 1,
                "inactive_ad_count": 0,
                "removed_ad_count": 0,
                "ad_count": 1,
                "ad_audience_reach": 1499,
                "ad_cost": 5.57,
                "active_days": 10,
                "ad_started_at": 1727420400,
                "ad_ended_at": 1728284400,
                "advertiser_count": 1,
                "active_adset_count": 1,
                "new_advertisements": [
                    {
                        "id": "4f9e5f10413e34a6776f43b1e58454a1",
                        "media_format": 1,
                        "images": [],
                        "videos": [
                            {
                                "url": "https://fb-cdn.pipiads.com/videos/21ed36eda7b38e985b2d25f360a44f11.mp4",
                                "width": 720,
                                "height": 1280,
                                "duration": 17,
                                "cover_url": "https://fb-cdn.pipiads.com/images/2d7e701ef3e181fe813e82fcf93af22d.png"
                            }
                        ],
                        "cards": []
                    },
                    {
                        "id": "fe7982e1a0d240c1776f43b1e58454a1",
                        "media_format": 1,
                        "images": [],
                        "videos": [
                            {
                                "url": "https://fb-cdn.pipiads.com/videos/bcdc68074bd480599546b0fce6512019.mp4",
                                "width": 720,
                                "height": 1280,
                                "duration": 20,
                                "cover_url": "https://fb-cdn.pipiads.com/images/35c1a93632d7d7c9cd7dda8cab7e813c.png"
                            }
                        ],
                        "cards": []
                    }
                ],
                "advertisers": [
                    {
                        "id": "23fa8af45a444946776f43b1e58454a1",
                        "name": "Locker Room",
                        "profile_picture_url": "https://fb-cdn.pipiads.com/images/1f1d15605fa8a92c2ac68fefbbf285c0.png",
                        "category_name": null,
                        "like_count": 79576,
                        "creation_time": null,
                        "ad_platform": [
                            "FACEBOOK",
                            "INSTAGRAM",
                            "AUDIENCE_NETWORK",
                            "MESSENGER"
                        ],
                        "ad_source": 1,
                        "source_advertiser_id": "202544936445217",
                        "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=202544936445217"
                    }
                ],
                "new_ad_products": [],
                "user_collected": 2
            }
        ],
        "last_page": 1199,
        "per_page": 1,
        "total": 1199
    },
    "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
»»» name	string	true	none	店铺名称	none
»»» logo_url	string¦null	true	none	店铺logo	none
»»» e_commerce_platform	string	true	none	电商系统	none
»»» source_store_link	string	true	none	店铺链接	none
»»» source_store_domain	string	true	none	店铺域名	none
»»» ad_product_count	integer¦null	true	none	广告产品数量	none
»»» month_visits	integer¦null	true	none	店铺月流量	none
»»» ad_country	[string]	true	none	广告投放国家	none
»»» ad_status	integer	true	none	广告状态	可选值：1-活跃中，2-已停止。
»»» adset_count	integer	true	none	总广告组数	none
»»» active_ad_count	integer	true	none	活跃广告数	none
»»» inactive_ad_count	integer	true	none	不活跃的广告数	none
»»» removed_ad_count	integer	true	none	已下架的广告数	none
»»» ad_count	integer	true	none	总广告数	none
»»» ad_audience_reach	integer¦null	true	none	覆盖人数	none
»»» ad_cost	number¦null	true	none	广告花费	单位：美元。
»»» active_days	integer	true	none	广告天数	none
»»» ad_started_at	integer	true	none	广告开始时间	时间戳：秒。
»»» ad_ended_at	integer	true	none	广告结束时间	时间戳：秒。
»»» advertisers	[object]¦null	true	none	关联的广告主	none
»»»» 广告主信息	object¦null	false	none	广告主信息	none
»»»»» id	string	true	none		none
»»»»» name	string	true	none	广告主名称	none
»»»»» profile_picture_url	string¦null	true	none	广告主头像	none
»»»»» category_name	string¦null	true	none	广告主类别	none
»»»»» like_count	integer¦null	true	none	广告主点赞数	none
»»»»» creation_time	integer¦null	true	none	广告主创建时间	none
»»»»» ad_platform	[string]	true	none	广告平台	none
»»»»» ads_library_link	string	true	none	广告主的广告库链接	none
»»» new_ad_products	[object]	true	none	最新的广告产品	none
»»»» id	string	true	none	产品ID	none
»»»» store_id	string	true	none	店铺ID	none
»»»» image_url	string¦null	true	none	产品主图	none
»»» new_advertisements	[object]	true	none	最新的广告	none
»»»» id	string	true	none	广告ID	none
»»»» media_format	integer	true	none	媒体格式	可选值：1-视频，2-图片，3-轮播图。
»»»» 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	视频的时长	单位：秒。
»»» user_collected	integer	true	none	是否已收藏	可选值：1-未收藏，2-已收藏。
»»» advertiser_count	integer¦null	true	none	广告主数量	none
»»» active_adset_count	integer	true	none	活跃广告组数	none
»» last_page	integer	true	none	最后一页的页码	none
»» per_page	integer	true	none	分页大小	none
»» total	integer	true	none	总数据量	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

接口信息

接口名称: 广告店铺列表
请求方法: POST
接口地址: /open-api/v1/ad-stores/search
价格说明: 每获取一条记录扣除2积分