API REFERENCE

Ad Store List API

POST/open-api/v1/ad-stores/search

Each record retrieved deducts 2 credits·api.ppspy.com

Data and monitoring usage rules

Points Consumption Rules: 1. Retrieving a Shopify data result consumes 1 data, while retrieving an ad library data result consumes 2 data. Retrieving additional data details for a data result does not consume data. 2. Ad monitoring and sales monitoring: Each monitoring session costs $1/month. Each monitoring session is valid for one month and automatically expires after one month. Deleting a monitoring session does not restore the monitoring session, so please delete with caution. Monitoring sessions can be accessed at any time and are unlimited.

Request headers

AUTHORIZATIONAuthorization: {API Key}

CONTENT-TYPEapplication/json

ACCEPTapplication/json

Request example

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
}'

Request parameters 41 fields

Pass each parameter in its specified location.

Parameter	Type	Description
body body · optional	object	\| -
» extend_keywords body · optional	[object]	Keyword Search \| -
»» field body · required	string	Search Field \| Options: `all`-All fields, `store_name`-Store name, `store_link`-Store URL, `advertiser_name`-Advertiser name, `product_name`-Product name.
»» value body · required	string	Search Value \| -
»» logic_operator body · required	string	Logical Operator \| Options: `and`, `or`
» exclude_keywords body · optional	[object]	Exclude Keywords \| -
»» field body · required	string	Search Field \| Options: `all`-All fields, `store_name`-Store name, `store_link`-Store URL, `advertiser_name`-Advertiser name, `product_name`-Product name.
»» value body · required	string	Search Value \| -
»» logic_operator body · required	string	Logical Operator \| Options: `and`, `or`
» e_commerce_platform body · optional	[string]	E-commerce Platform \| -
» ad_status body · optional	integer	Ad Status \| Options: `1`-Active, `2`-Stopped.
» category_ids body · optional	[string]	Product Category ID \| -
» ad_country body · optional	[string]	Target Country \| -
» ad_product_count_start body · optional	integer	Ad Products Count (Min) \| -
» ad_product_count_end body · optional	integer	Ad Products Count (Max) \| -
» language body · optional	[string]	Store Language \| -
» month_visits_start body · optional	integer	Monthly Visits (Min) \| -
» month_visits_end body · optional	integer	Monthly Visits (Max) \| -
» advertiser_count_start body · optional	integer	Advertisers Count (Min) \| -
» advertiser_count_end body · optional	integer	Advertisers Count (Max) \| -
» active_adset_count_start body · optional	integer	Active Ad Groups (Min) \| -
» active_adset_count_end body · optional	integer	Active Ad Groups (Max) \| -
» adset_count_start body · optional	integer	Total Ad Groups (Min) \| -
» adset_count_end body · optional	integer	Total Ad Groups (Max) \| -
» ad_count_start body · optional	integer	Ad Creatives Count (Min) \| -
» ad_count_end body · optional	integer	Ad Creatives Count (Max) \| -
» ad_audience_reach_start body · optional	integer	Audience Reach (Min) \| -
» ad_audience_reach_end body · optional	integer	Audience Reach (Max) \| -
» ad_cost_start body · optional	number	Ad Spend (Min) \| In USD
» ad_cost_end body · optional	number	Ad Spend (Max) \| In USD
» active_days_start body · optional	integer	Active Days (Min) \| -
» active_days_end body · optional	integer	Active Days (Max) \| -
» ad_started_at_start body · optional	integer	Ad Start Time (Min) \| Unix timestamp (seconds).
» ad_started_at_end body · optional	integer	Ad Start Time (Max) \| Unix timestamp (seconds).
» ad_ended_at_start body · optional	integer	Ad End Time (Min) \| Unix timestamp (seconds).
» ad_ended_at_end body · optional	integer	Ad End Time (Max) \| Unix timestamp (seconds).
» order_by body · optional	string	Sort Field \| Options: `ad_started_at`, `month_visits`, `active_adset_count`, `adset_count`, `ad_count`, `ad_audience_reach`, `ad_cost`, `active_days`, `ad_ended_at`.
» direction body · optional	string	Sort Order \| Options: `desc`-Descending, `asc`-Ascending.
» page body · optional	integer	Page Number \| Min value: 1.
» per_page body · optional	integer	Items per Page \| Range: 1-100.
» ids body · optional	[string]	Ad Store IDs \| -

Response example

Response · 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
    }
}

Example data from the existing documentation

Response structure

Name	Type	Required	Constraints	Display Name	Description
» code	integer	true	none	Status Code	-
» message	string	true	none	Response Message	-
» data	object	true	none	Response Data	-
»» current_page	integer	true	none	Current Page	-
»» data	[object]	true	none	Data List	-
»»» id	string	true	none	Ad Store ID	-
»»» name	string	true	none	Store Name	-
»»» logo_url	string¦null	true	none	Store Logo	-
»»» e_commerce_platform	string	true	none	E-commerce Platform	-
»»» source_store_link	string	true	none	Store URL	-
»»» source_store_domain	string	true	none	Store Domain	-
»»» ad_product_count	integer¦null	true	none	Advertised Products Count	-
»»» month_visits	integer¦null	true	none	Monthly Visits	-
»»» ad_country	[string]	true	none	Target Countries	-
»»» ad_status	integer	true	none	Ad Status	`1`-Active, `2`-Stopped.
»»» adset_count	integer	true	none	Total Ad Groups	-
»»» active_ad_count	integer	true	none	Active Ads Count	-
»»» inactive_ad_count	integer	true	none	Inactive Ads Count	-
»»» removed_ad_count	integer	true	none	Removed Ads Count	-
»»» ad_count	integer	true	none	Total Ads Count	-
»»» ad_audience_reach	integer¦null	true	none	Audience Reach	-
»»» ad_cost	number¦null	true	none	Ad Spend	In USD
»»» active_days	integer	true	none	Active Days	-
»»» ad_started_at	integer	true	none	Ad Start Time	Unix timestamp (seconds).
»»» ad_ended_at	integer	true	none	Ad End Time	Unix timestamp (seconds).
»»» advertisers	[object]¦null	true	none	Linked Advertisers	-
»»»» advertiser_info	object¦null	false	none	Advertiser Details	-
»»»»» id	string	true	none	Advertiser ID	-
»»»»» name	string	true	none	Advertiser Name	-
»»»»» profile_picture_url	string¦null	true	none	Profile Picture	-
»»»»» category_name	string¦null	true	none	Category	-
»»»»» like_count	integer¦null	true	none	Likes Count	-
»»»»» creation_time	integer¦null	true	none	Created At	-
»»»»» ad_platform	[string]	true	none	Ad Platforms	-
»»»»» ads_library_link	string	true	none	Ads Library Link	-
»»» new_ad_products	[object]	true	none	Newest Advertised Products	-
»»»» id	string	true	none	Product ID	-
»»»» store_id	string	true	none	Store ID	-
»»»» image_url	string¦null	true	none	Product Image	-
»»» new_advertisements	[object]	true	none	Latest Ads	-
»»»» id	string	true	none	Ad ID	-
»»»» media_format	integer	true	none	Media Format	`1`-Video, `2`-Image, `3`-Carousel.
»»»» images	[object]	true	none	Images	-
»»»»» url	string	true	none	Image URL	-
»»»»» width	integer¦null	true	none	Width (px)	-
»»»»» height	integer¦null	true	none	Height (px)	-
»»»» videos	[object]	true	none	Videos	-
»»»»» url	string	true	none	Video URL	-
»»»»» cover_url	string¦null	true	none	Thumbnail URL	-
»»»»» width	integer¦null	true	none	Width (px)	-
»»»»» height	integer¦null	true	none	Height (px)	-
»»»»» duration	integer¦null	true	none	Duration	Seconds.
»»»» cards	[object]	true	none	Carousel Cards	-
»»»»» media_type	integer	true	none	Media Type	`1`-Video, `2`-Image.
»»»»» url	string	true	none	Media URL	-
»»»»» cover_url	string¦null	true	none	Video Thumbnail	-
»»»»» width	integer¦null	true	none	Width (px)	-
»»»»» height	integer¦null	true	none	Height (px)	-
»»»»» duration	integer¦null	true	none	Duration	Seconds.
»»» user_collected	integer	true	none	Bookmarked	`1`-No, `2`-Yes.
»»» advertiser_count	integer¦null	true	none	Advertisers Count	-
»»» active_adset_count	integer	true	none	Active Ad Groups	-
»» last_page	integer	true	none	Last Page	-
»» per_page	integer	true	none	Items per Page	-
»» total	integer	true	none	Total Records	-
» credits	object	true	none	Credits information	Credits information for the current API request
»» remaining_credits	integer	true	none	Remaining credits	Remaining credits after this request
»» consumed_credits	integer	true	none	Consumed credits	Credits consumed by this request
»» total_credits	integer	true	none	Total credits	Total credits of the current credits type

Original API information and base URL

Base URLs

Production Environment: https://api.ppspy.com

API Information

API Name: Ad Store List
Request Method: POST
API URL: /open-api/v1/ad-stores/search
Cost: Each record retrieved deducts 2 credits