API REFERENCE

Ad Product List API

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

Request parameters 51 fields

Pass each parameter in its specified location.

Parameter	Type	Description
body body · optional	object	\| -
» extend_keywords body · optional	[object]	Keyword Search \| none
»» field body · required	string	Search Field \| Options: `all`, `product_name`, `product_link`, `advertiser_name`.
»» value body · required	string	Search Value \| none
»» logic_operator body · required	string	Logical Operator \| Options: `and`, `or`.
» exclude_keywords body · optional	[object]	Exclude Keywords \| none
»» field body · required	string	Search Field \| Options: `all`, `product_name`, `product_link`, `advertiser_name`.
»» value body · required	string	Search Value \| none
»» logic_operator body · required	string	Logical Operator \| Options: `and`, `or`.
» ad_forecast body · optional	[integer]	AI Score \| Options: `1`-Testing phase, `2`-Growth phase, `3`-Profit phase.
» e_commerce_platform body · optional	[string]	E-commerce Platform \| none
» creation_time_start body · optional	integer	Product Creation Time (Start) \| Unix timestamp (in seconds).
» creation_time_end body · optional	integer	Product Creation Time (End) \| Unix timestamp (in seconds).
» category_id body · optional	[string]	Product Category ID \| none
» store_country body · optional	[string]	Store Country \| none
» price_usd_start body · optional	number	Product USD Price (Start) \| none
» price_usd_end body · optional	number	Product USD Price (End) \| none
» currency body · optional	[string]	Currency \| none
» store_pixel_platforms body · optional	[string]	Pixel Platforms \| Options: `snap`, `tiktok`, `pinterest`.
» store_language body · optional	[string]	Store Language \| none
» store_published_products_count_start body · optional	integer	Store Products Count (Start) \| none
» store_published_products_count_end body · optional	integer	Store Products Count (End) \| none
» active_adset_count_start body · optional	integer	Active Ad Sets Count (Start) \| none
» active_adset_count_end body · optional	integer	Active Ad Sets Count (End) \| none
» adset_count_24h_start body · optional	integer	24h Ad Sets Count (Start) \| none
» adset_count_24h_end body · optional	integer	24h Ad Sets Count (End) \| none
» adset_count_start body · optional	integer	Total Ad Sets Count (Start) \| none
» adset_count_end body · optional	integer	Total Ad Sets Count (End) \| none
» ad_count_start body · optional	integer	Ad Creatives Count (Start) \| none
» ad_count_end body · optional	integer	Ad Creatives Count (End) \| none
» store_active_adset_count_start body · optional	integer	Store Active Ad Sets Count (Start) \| none
» store_active_adset_count_end body · optional	integer	Store Active Ad Sets Count (End) \| none
» store_ad_count_start body · optional	integer	Store Ad Creatives Count (Start) \| none
» store_ad_count_end body · optional	integer	Store Ad Creatives Count (End) \| none
» ad_audience_reach_start body · optional	integer	Audience Reach (Start) \| none
» ad_audience_reach_end body · optional	integer	Audience Reach (End) \| none
» ad_cost_start body · optional	number	Ad Spend (Start) \| In USD
» ad_cost_end body · optional	number	Ad Spend (End) \| In USD
» ad_status body · optional	integer	Ad Status \| Options: `1`-Active, `2`-Stopped.
» active_days_start body · optional	integer	Active Days (Start) \| none
» active_days_end body · optional	integer	Active Days (End) \| none
» ad_started_at_start body · optional	integer	Ad Start Time (Start) \| Unix timestamp (in seconds).
» ad_started_at_end body · optional	integer	Ad Start Time (End) \| Unix timestamp (in seconds).
» ad_ended_at_start body · optional	integer	Ad End Time (Start) \| Unix timestamp (in seconds).
» ad_ended_at_end body · optional	integer	Ad End Time (End) \| Unix timestamp (in seconds).
» order_by body · optional	string	Sort Field \| Options: `ad_started_at`, `ad_ended_at`, `active_adset_count`, `adset_count_24h`, `adset_count`, `ad_count`, `store_active_adset_count`, `creation_time`, `ad_audience_reach`, `ad_cost`, `active_days`.
» direction body · optional	string	Sort Direction \| Options: `desc`-Descending, `asc`-Ascending.
» page body · optional	integer	Page Number \| Min value: `1`.
» per_page body · optional	integer	Page Size \| Range: `1-100`.
» ids body · optional	[string]	Product IDs \| none
» store_id body · optional	string	Store ID \| none

Response example

Response · JSON

{
    "code": 200,
    "message": "success",
    "data": {
        "current_page": 10,
        "data": [
            {
                "id": "8f624441d1106bb9937e187e13af0bf4",
                "store_id": "b06855e0873197f5937e187e13af0bf4",
                "name": "Thera Pillow | Traction Massager",
                "source_product_link": "https://callixe.com/products/thera",
                "currency": "USD",
                "price": 89.73,
                "price_usd": 89.73,
                "ad_count": 1,
                "creation_time": 1712007737,
                "active_ad_count": 1,
                "source_product_id": "9426992202001",
                "images": [
                    "https://fb-cdn.pipiads.com/images/pimg_c502cb2f8e21f07022aa.png",
                    "https://fb-cdn.pipiads.com/images/pimg_c64596f08800b96cbdd4.png",
                    "https://fb-cdn.pipiads.com/images/pimg_87f89103b85e469582d4.png",
                    "https://fb-cdn.pipiads.com/images/pimg_e19af42f354271c796d9.png",
                    "https://fb-cdn.pipiads.com/images/pimg_d99b44555550dfe88916.png"
                ],
                "adset_count": 0,
                "active_adset_count": 0,
                "adset_count_24h": 0,
                "ad_forecast": 1,
                "ad_status": 1,
                "e_commerce_platform": "shopify",
                "ad_audience_reach": 0,
                "ad_cost": 0.99,
                "active_days": 1,
                "ad_started_at": 1728370800,
                "ad_ended_at": 1728370800,
                "image_url": "https://fb-cdn.pipiads.com/images/pimg_c502cb2f8e21f07022aa.png",
                "store": {
                    "id": "b06855e0873197f5937e187e13af0bf4",
                    "name": "CALLIXE",
                    "ad_count": 1,
                    "e_commerce_platform": "shopify",
                    "e_commerce_types": [
                        1,
                        3
                    ],
                    "logo_url": null,
                    "source_store_link": "https://callixe.com",
                    "adset_count": 0,
                    "country": "US",
                    "monthly_sales": null
                },
                "user_collected": 2
            }
        ],
        "last_page": 1,
        "per_page": 2,
        "total": 1
    },
    "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	none
» data	object	true	none	Response Data	none
»» current_page	integer	true	none	Current Page	none
»» data	[object]	true	none	Data List	none
»»» id	string	true	none	Product ID	none
»»» store_id	string	true	none	Store ID	none
»»» name	string	true	none	Product Name	none
»»» source_product_link	string	true	none	Product URL	none
»»» currency	string¦null	true	none	Currency	none
»»» price	number¦null	true	none	Product Price	none
»»» price_usd	number¦null	true	none	Product Price (USD)	none
»»» ad_count	integer	true	none	Ad Count	none
»»» creation_time	integer¦null	true	none	Creation Time	Unix timestamp (in seconds).
»»» active_ad_count	integer	true	none	Active Ad Count	none
»»» source_product_id	string	true	none	Platform Product ID	none
»»» images	[string]	true	none	Product Image URLs	none
»»» image_url	string¦null	true	none	Primary Image	none
»»» adset_count	integer	true	none	Total Ad Sets	none
»»» active_adset_count	integer	true	none	Active Ad Sets	none
»»» adset_count_24h	integer	true	none	24h Ad Sets	none
»»» ad_forecast	integer	true	none	AI Score	none
»»» ad_status	integer	true	none	Ad Status	none
»»» e_commerce_platform	string	true	none	E-commerce Platform	none
»»» ad_audience_reach	integer¦null	true	none	Audience Reach	none
»»» ad_cost	number¦null	true	none	Ad Spend	In USD
»»» active_days	integer	true	none	Active Days	none
»»» ad_started_at	integer	true	none	Ad Start Time	Unix timestamp (in seconds).
»»» ad_ended_at	integer	true	none	Ad End Time	Unix timestamp (in seconds).
»»» store	object¦null	true	none	Store Info	none
»»»» id	string	true	none	Store ID	none
»»»» name	string	true	none	Store Name	none
»»»» ad_count	integer	true	none	Store Ad Count	none
»»»» e_commerce_platform	string¦null	true	none	E-commerce Platform	none
»»»» e_commerce_types	[integer]¦null	true	none	E-commerce Types	none
»»»» logo_url	string¦null	true	none	Store Logo	none
»»»» source_store_link	string¦null	true	none	Store URL	none
»»»» adset_count	integer	true	none	Total Ad Sets	none
»»»» monthly_sales	integer¦null	true	none	Monthly Sales	none
»»»» country	string¦null	true	none	Country	none
»»» user_collected	integer	true	none	Bookmarked	Options: `1`-No, `2`-Yes.
»» last_page	integer	true	none	Last Page	none
»» per_page	integer	true	none	Page Size	none
»» total	integer	true	none	Total Records	none
» 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 Product List
Request Method: POST
API URL: /open-api/v1/ad-products/search
Cost: Each record retrieved deducts 2 credits