Pipispy API中文

Data usage rules: 1. Obtaining a data result consumes 1 data. Obtaining more detailed information about a data result does not consume data. 2. Ad Tracker: 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.

Ad Library Product Search API

API Information

  • API Name: Ad Library Product Search
  • Request Method: POST
  • API Endpoint: /open-api/v1/data
  • API Path: /v3/api/open/ppspy/ad-products/search
  • API Description: Search ad library products based on multiple filtering conditions, supporting precise queries by product attributes, store information, advertising data, and other dimensions. Suitable for e-commerce product analysis, competitor research, and other scenarios
  • Pricing: Retrieving one data result consumes 1 credit

Request Headers:

  • Content-Type: application/json
  • Accept: application/json

Request Parameters

Request Structure

Parameter Type Description Example Required Default
key string External API request key "your_api_key_here" Yes
uri string API path "/v3/api/open/ppspy/ad-products/search" Yes
params object API input parameters object See parameter list Yes

Request Body Parameters (params object)

Basic Parameters

Parameter Type Required Description
page Integer No Page number, minimum value equals 1. Used for paginated queries to specify which page of data to retrieve
per_page Integer No Page size, value range 1-100. Specifies the number of products returned per page
order_by String No Sort field, determines which metric to sort results by. Options:
• ad_started_at - Ad start time
• ad_ended_at - Ad end time
• active_adset_count - Active ad set count
• adset_count_24h - 24-hour ad set count
• adset_count - Total ad set count
• ad_count - Ad creative count
• store_active_adset_count - Store active ad set count
• creation_time - Product creation time
• ad_audience_reach - Reach
• ad_cost - Ad spend
• active_days - Ad days
direction String No Sort order, used with order_by. Options:
• desc - Descending (large to small)
• asc - Ascending (small to large)

Product Filter Parameters

Parameter Type Required Description
ids String Array No Product ID list, used for batch querying specified products. Example: ["05fcadd84113edd111628deae2a75553", "1edc9a26b55b66a411628deae2a75553"]
category_id String Array No Product category ID list, see E-commerce Categories for filtering products in specific categories. Example: ["62739aec38365b2f72048ebd", "62739b6038365b2f72048ec1"]
currency String Array No Currency unit list, used for filtering products using specific currencies. Example: ["USD", "EUR"]
e_commerce_platform String Array No E-commerce platform list, used for filtering products from specific e-commerce platforms. Example: ["shopify", "woocommerce"]

Product Price Filtering

Parameter Type Required Description
price_usd_start Double No Product USD price (start), used for filtering the lower limit of price range, unit: USD
price_usd_end Double No Product USD price (end), used for filtering the upper limit of price range, unit: USD. Used with price_usd_start

Product Time Filtering

Parameter Type Required Description
creation_time_start Long No Product creation time (start), timestamp: seconds. Used for filtering the lower limit of creation time range
creation_time_end Long No Product creation time (end), timestamp: seconds. Used for filtering the upper limit of creation time range. Used with creation_time_start

Advertising Data Filtering

Parameter Type Required Description
ad_status Integer No Ad status, used for filtering products with different placement statuses. Options:
• 1 - Active (currently placing ads)
• 2 - Stopped (ads paused)
ad_forecast Integer Array No AI score, evaluates product stage based on AI algorithm. Options:
• 1 - Testing phase (new product testing)
• 2 - Growth phase (growth period)
• 3 - Profit phase (maturity period)
Example: [1, 2]

Ad Time Filtering

Parameter Type Required Description
ad_started_at_start Long No Ad start time (start), timestamp: seconds. Used for filtering the lower limit of ad start time range
ad_started_at_end Long No Ad start time (end), timestamp: seconds. Used for filtering the upper limit of ad start time range. Used with ad_started_at_start
ad_ended_at_start Long No Ad end time (start), timestamp: seconds. Used for filtering the lower limit of ad end time range
ad_ended_at_end Long No Ad end time (end), timestamp: seconds. Used for filtering the upper limit of ad end time range. Used with ad_ended_at_start

Ad Days Filtering

Parameter Type Required Description
active_days_start Long No Ad days (start), used for filtering the lower limit of ad placement days range. More days indicates longer continuous placement
active_days_end Long No Ad days (end), used for filtering the upper limit of ad placement days range. Used with active_days_start

Ad Creative Filtering

Parameter Type Required Description
ad_count_start Integer No Ad creative count (start), used for filtering the lower limit of product ad creative count range. More creatives indicates greater promotion effort
ad_count_end Integer No Ad creative count (end), used for filtering the upper limit of product ad creative count range. Used with ad_count_start

Ad Set Count Filtering

Parameter Type Required Description
active_adset_count_start Integer No Active ad set count (start), used for filtering the lower limit of current active ad set count range. Active ad sets are those currently being placed
active_adset_count_end Integer No Active ad set count (end), used for filtering the upper limit of current active ad set count range. Used with active_adset_count_start
adset_count_start Integer No Total ad set count (start), used for filtering the lower limit of total ad set count range, including active and stopped ad sets
adset_count_end Integer No Total ad set count (end), used for filtering the upper limit of total ad set count range. Used with adset_count_start
adset_count_24h_start Integer No 24-hour ad set count (start), used for filtering the lower limit of new ad sets in the last 24 hours. Used for discovering latest trending products
adset_count_24h_end Integer No 24-hour ad set count (end), used for filtering the upper limit of new ad sets in the last 24 hours. Used with adset_count_24h_start

Ad Spend Filtering

Parameter Type Required Description
ad_cost_start Double No Ad spend (start), unit: USD. Used for filtering the lower limit of ad spend amount range, can evaluate product promotion investment
ad_cost_end Double No Ad spend (end), unit: USD. Used for filtering the upper limit of ad spend amount range. Used with ad_cost_start

Reach Filtering

Parameter Type Required Description
ad_audience_reach_start Integer No Reach (start), used for filtering the lower limit of ad reach range. Reach refers to the number of unique users reached by ads
ad_audience_reach_end Integer No Reach (end), used for filtering the upper limit of ad reach range. Used with ad_audience_reach_start

Store Filter Parameters

Parameter Type Required Description
store_id String No Store ID, used for querying all products under a specific store
store_country String Array No Store country list, used for filtering store products from specific countries. Uses ISO 3166-1 alpha-2 standard country codes. Example: ["US", "CA", "GB"]
store_language String Array No Store language list, used for filtering store products using specific languages. Uses ISO 639-1 standard language codes. Example: ["en", "de", "fr"]
store_pixel_platforms String Array No Pixel platform list, used for filtering store products with specific tracking pixels installed. Options: snap, tiktok, pinterest. Example: ["tiktok", "snap"]

Store Product Count Filtering

Parameter Type Required Description
store_published_products_count_start Integer No Store product count (start), used for filtering the lower limit of store total product count range. Can evaluate store scale
store_published_products_count_end Integer No Store product count (end), used for filtering the upper limit of store total product count range. Used with store_published_products_count_start

Store Advertising Data Filtering

Parameter Type Required Description
store_active_adset_count_start Integer No Store active ad set count (start), used for filtering the lower limit of store current active ad set count range. Can evaluate store's current promotion effort
store_active_adset_count_end Integer No Store active ad set count (end), used for filtering the upper limit of store current active ad set count range. Used with store_active_adset_count_start
store_ad_count_start Integer No Store ad creative count (start), used for filtering the lower limit of store total ad creative count range
store_ad_count_end Integer No Store ad creative count (end), used for filtering the upper limit of store total ad creative count range. Used with store_ad_count_start
Parameter Type Required Description
extend_keywords Array No Keyword search list, used for searching products by keywords. Supports multiple keyword combination searches. Each object in the array contains the following fields:
• field - Search field, options: all (all), product_name (product name), product_link (product URL), advertiser_name (advertiser name)
• logic_operator - Logical operator, options: and, or
• value - Search content
exclude_keywords Array No Exclude keyword list, used for excluding products containing specific keywords. Same structure as extend_keywords

Request Example

curl -X POST "https://www.pipispy.com/open-api/v1/data" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "key": "your_api_key_here",
    "uri": "/v3/api/open/ppspy/ad-products/search",
    "params": {
      "e_commerce_platform": ["magento"],
      "category_id": ["62739aec38365b2f72048ebd"],
      "extend_keywords": [
        {
          "field": "all",
          "value": "Infinitum Grillo",
          "logic_operator": "and"
        }
      ],
      "order_by": "ad_started_at",
      "direction": "desc",
      "page": 1,
      "ad_started_at_start": 1727712000,
      "ad_started_at_end": 1767110399,
      "per_page": 20
    }
  }'

Response Parameters

Response Structure

{
  "code": 200,
  "message": "success",
  "data": {
    "current_page": 1,
    "data": [],
    "last_page": 10,
    "per_page": 20,
    "total": 200
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 20,
  "success": true,
  "fail": false
}

Response Field Descriptions

Field Type Description
code Integer Business status code, 200 indicates success
message String Response message, usually "success" when successful
data Object Response data object
version string API version
timestamp number Response timestamp
sign string Response signature
remaining_credits Long Current remaining available credits after this request
consumed_credits Long Credits consumed by this request
success boolean Whether the request was successful
fail boolean Whether the request failed

Pagination Information Fields

Field Type Description
current_page Integer Current page number
data Array Data list, contains array of product information
last_page Integer Last page number, can be used to determine total pages
per_page Integer Page size, number of data items returned per page
total Integer Total data count, total number of products meeting filter criteria

Product Information Fields

Field Type Description
id String Product ID, unique identifier for the product
name String Product name
price Double Product price (original currency)
price_usd Double Product USD price, converted to USD for easy comparison
currency String Currency unit, such as USD, EUR, etc.
image_url String Product main image URL, the primary display image for the product
images String Array Product image link list, contains all product image URLs
source_product_id String E-commerce platform product ID, product identifier on the original e-commerce platform
source_product_link String Product link, product detail page URL on the e-commerce platform
e_commerce_platform String E-commerce platform, name of the e-commerce platform where the product is located
creation_time Long Product creation time, timestamp: seconds
user_collected Integer Whether collected, options:
• 1 - Not collected
• 2 - Collected

Product Advertising Data Fields

Field Type Description
ad_status Integer Ad status, current ad placement status of the product
ad_forecast Integer Product score, product stage score evaluated by AI
active_ad_count Integer Active ad count, number of ads currently being placed
ad_count Integer Ad count, total number of ads created for the product
active_adset_count Integer Active ad set count, number of ad sets currently being placed
adset_count Integer Total ad set count, total number of ad sets created for the product
adset_count_24h Integer 24-hour ad set count, number of ad sets added in the last 24 hours
active_days Integer Ad days, number of days the product has been continuously advertising
ad_started_at Long Ad start time, timestamp: seconds. Time when the product first started advertising
ad_ended_at Long Ad end time, timestamp: seconds. End time of the last ad placement for the product
ad_cost Double Ad spend, unit: USD. Cumulative advertising investment cost for the product
ad_audience_reach Integer Reach, total number of unique users reached by the ads

Store Information Fields (store)

When the returned data contains store information, the store object contains the following fields:

Field Type Description
id String Store ID, unique identifier for the store
name String Store name
logo_url String Store logo, store logo image URL
country String Store country, country where the store is registered or primarily operates
source_store_link String Store link, store homepage URL on the e-commerce platform
e_commerce_platform String E-commerce platform, name of the e-commerce platform where the store is located
e_commerce_types Integer Array E-commerce types, business type identifiers of the store
ad_count Integer Store creative count, total number of ad creatives created by the store
adset_count Integer Total ad set count, total number of ad sets created by the store
monthly_sales Integer Monthly sales, monthly sales count for the store (estimated value)

Response Example

{
  "code": 200,
  "message": "success",
  "data": {
    "current_page": 1,
    "data": [
      {
        "active_ad_count": 1,
        "active_adset_count": 1,
        "active_days": 2,
        "ad_audience_reach": 368,
        "ad_cost": 6.6,
        "ad_count": 1,
        "ad_ended_at": 1766995200,
        "ad_forecast": 1,
        "ad_started_at": 1766822400,
        "ad_status": 1,
        "adset_count": 1,
        "adset_count_24h": 0,
        "currency": "EUR",
        "e_commerce_platform": "magento",
        "id": "5b9ac27f7b3d21aecdca5cb00be71baa",
        "images": [
          "https://fb-cdn.ppspy.com/images/pimg_c1cb26db9e59ba4c70688.png",
          "https://fb-cdn.ppspy.com/images/pimg_6ca311198854c6eeeffc9.png",
          "https://fb-cdn.ppspy.com/images/pimg_0d9e6a0a2e72f9f291f07.png",
          "https://fb-cdn.ppspy.com/images/pimg_c1cb26db9e59ba4c70688.png",
          "https://fb-cdn.ppspy.com/images/pimg_6ca311198854c6eeeffc9.png"
        ],
        "image_url": "https://fb-cdn.ppspy.com/images/pimg_c1cb26db9e59ba4c70688.png",
        "name": "Infinitum Grillo",
        "price": 5.79,
        "price_usd": 6.82,
        "source_product_id": "c068345331a01d1216591db170f03672",
        "source_product_link": "https://www.wijnvoordeel.be/infinitum-grillo?channable=019969736b75004b3230303738324e",
        "store": {
          "ad_count": 14,
          "adset_count": 27,
          "e_commerce_platform": "magento",
          "id": "2382cd09c06c7d31cdca5cb00be71baa",
          "logo_url": "https://fb-cdn.pipiads.com/icon_ad0a30d8c8334ccbf37488a8ce91377b.png",
          "name": "wijnvoordeel.be",
          "source_store_link": "http://wijnvoordeel.be"
        },
        "store_id": "2382cd09c06c7d31cdca5cb00be71baa",
        "user_collected": 2,
        "favorite_time": 0,
        "ad_platform": [
          "FACEBOOK",
          "INSTAGRAM",
          "MESSENGER",
          "THREADS"
        ]
      }
    ],
    "first_page_url": "http://app-pre.ppspy.com/v1/ad-products/search?direction=desc&page=1&ad_started_at_end=1767110399&ad_started_at_start=1727712000&category_id%5B0%5D=62739aec38365b2f72048ebd&e_commerce_platform%5B0%5D=magento&extend_keywords%5B0%5D%5Bfield%5D=all&extend_keywords%5B0%5D%5Bvalue%5D=Infinitum%20Grillo&extend_keywords%5B0%5D%5Blogic_operator%5D=and&order_by=ad_started_at&per_page=20",
    "from": 1,
    "is_logged_in": true,
    "last_page": 1,
    "last_page_url": "http://app-pre.ppspy.com/v1/ad-products/search?direction=desc&page=1&ad_started_at_end=1767110399&ad_started_at_start=1727712000&category_id%5B0%5D=62739aec38365b2f72048ebd&e_commerce_platform%5B0%5D=magento&extend_keywords%5B0%5D%5Bfield%5D=all&extend_keywords%5B0%5D%5Bvalue%5D=Infinitum%20Grillo&extend_keywords%5B0%5D%5Blogic_operator%5D=and&order_by=ad_started_at&per_page=20",
    "path": "http://app-pre.ppspy.com/v1/ad-products/search",
    "per_page": 20,
    "to": 1,
    "total": 1
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 20,
  "success": true,
  "fail": false
}

Error Code Descriptions

Error Code Description
200 Success
400 Request parameter error, please check parameter format and value range
401 Unauthorized, API key is invalid or expired
403 Insufficient permissions, insufficient account balance or restricted API access
404 API path does not exist
444 Too many requests, rate limit triggered
500 Internal server error, please try again later

Notes

  1. Pagination Limit: It is recommended to set the page data size between 20-100, as excessively large pagination will affect response speed
  2. Time Format: All time fields use Unix timestamps (second-level), please pay attention to conversion
  3. Array Parameters: When using array-type filter conditions, results satisfying any value in the array will be returned (OR logic)
  4. Range Filtering: When using paired start and end parameters, ensure start ≤ end
  5. Keyword Search: extend_keywords and exclude_keywords can be used in combination, first applying include keyword filtering, then applying exclude keyword filtering
  6. Sorting Optimization: It is recommended to specify order_by and direction parameters, otherwise default sorting will be used, which may affect result relevance
  7. Store Information: The store field may be null, indicating that the product currently has no associated store information
  8. Data Updates: Ad data is updated regularly, it is recommended to re-query periodically to get the latest data