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 Details API

API Information

  • API Name: Ad Library Product Details
  • Request Method: POST
  • API Endpoint: /open-api/v1/data
  • API Path: /v3/api/open/ppspy/ad-products/detail
  • API Description: Retrieve detailed information about ad library products by product ID, including basic product information, advertising data, store information, advertiser information, and ad count trends
  • Pricing: Base fee: 1 credit/request. Free access conditions (if either is met): Details for this ID have been retrieved within the past 3 days; This ID appeared in your leaderboard list query results within the past 3 days.

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/detail" Yes
params object API input parameters object See parameter list Yes

Path Parameters

Parameter Type Required Description
id String Yes Product ID, used to identify the specific product to query. Can be obtained from the product search API response

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/detail",
    "params": {
      "id": "5b9ac27f7b3d21aecdca5cb00be71baa"
    }
  }'

Response Parameters

Response Structure

{
  "code": 200,
  "message": "success",
  "data": {
    "product": {},
    "store": {},
    "advertisers": [],
    "ad_started_history": []
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 1,
  "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

Data Object Fields (data)

Field Type Description
product Object Product information, contains complete detailed product data
store Object Store information, detailed information about the store to which the product belongs
advertisers Array Advertiser information list, data for all advertisers promoting this product
ad_started_history Array Ad count trends, historical trend data of product ad placements

Product Information Fields (product)

Basic Information

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 price in USD, 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 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
store_id String Store ID, unique identifier of the store to which the product belongs
category_id String Category ID, unique identifier of the category to which the product belongs
category_name String Category name, name of the category to which the product belongs
creation_time Long Product creation time, timestamp: seconds
user_collected Integer Whether collected, possible values:
• 1 - Not collected
• 2 - Collected

Advertising Data

Field Type Description
ad_status Integer Ad status, possible values: 1-Active, 2-Stopped
ad_forecast Integer AI score, possible values: 1-Testing phase, 2-Growth phase, 3-Profit phase
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
ad_platform String Array Ad platform list, platforms where the product ads are placed, such as FACEBOOK, INSTAGRAM, etc.

Store Information Fields (store)

Field Type Description
id String Store ID, unique identifier for the store
name String Store name
logo_url String Store logo image URL
e_commerce_platform String E-commerce platform, name of the e-commerce platform where the store is located
source_store_link String Store link, store homepage URL on the e-commerce platform
month_visits Integer Monthly visits, monthly visit count for the store (estimated value)
published_products_count Integer Product count, total number of products published by the store
monthly_sales Integer Monthly sales, monthly sales count for the store (estimated value)

Advertiser Information Fields (advertisers)

advertisers is an array containing information about all advertisers promoting this product. Each advertiser object contains the following fields:

Basic Information

Field Type Description
id String Advertiser ID, unique identifier for the advertiser
name String Advertiser name
profile_picture_url String Advertiser profile picture link
source_advertiser_id String Advertiser page ID, page identifier on the ad platform
source_advertiser_link String Advertiser page link, advertiser page URL on the ad platform
ads_library_link String Advertiser ad library link, link to view all ads from this advertiser
category_name String Category, category to which the advertiser belongs
creation_time Long Creation time, timestamp: seconds

Advertising Data

Field Type Description
ad_status Integer Ad status, possible values: 1-Active, 2-Stopped
active_ad_count Integer Active ad count, number of ads currently being placed by this advertiser
inactive_ad_count Integer Inactive ad count, number of ads that have been paused
removed_ad_count Integer Removed ad count, number of ads that have been deleted or removed
ad_count Integer Ad creative count, total number of ads created by this advertiser
adset_count Integer Ad set count, total number of ad sets created by this advertiser
active_days Integer Ad days, number of days this advertiser has been continuously advertising
ad_started_at Long Ad start time, timestamp: seconds
ad_ended_at Long Ad end time, timestamp: seconds
ad_country String Array Country list, country codes where this advertiser's ads are placed
ad_platform String Array Ad platform list, ad platforms used by this advertiser
like_count Integer Like count, total likes received by this advertiser's ads
ad_source Integer Ad source

Ad Trend Data Fields (ad_started_history)

ad_started_history is an array recording the change in product ad count over time. Each trend data point contains the following fields:

Field Type Description
date String Date, UTC time. Format: YYYY-MM-DD
count Integer Ad count, number of ads corresponding to this date

Response Example

{
  "code": 200,
  "message": "success",
  "data": {
    "advertisers": [
      {
        "id": "f57f4c9d3ea20be66a132adb5f557eba",
        "name": "wijnvoordeel.be",
        "active_ad_count": 9,
        "active_days": 780,
        "ad_count": 321,
        "ad_country": [
          "BE",
          "other"
        ],
        "ad_ended_at": 1766995200,
        "ad_started_at": 1699603200,
        "ad_status": 1,
        "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=186022184808923",
        "adset_count": 531,
        "creation_time": 1318448479,
        "inactive_ad_count": 0,
        "like_count": 19420,
        "profile_picture_url": "https://scontent-lga3-1.xx.fbcdn.net/v/t39.35426-6/599566144_1210304384349710_4804416712767355916_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=111&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=UydCX9qVwIMQ7kNvwGqJ0kM&_nc_oc=AdnRT5BJoxS5kk-6exgTkCsIjeAeP4S6lmunXkvWZZOS6QNPr_cXeohqsKL1RegXxU4&_nc_zt=14&_nc_ht=scontent-lga3-1.xx&_nc_gid=lEhGO0OMT5L5L9xSpwx3OA&oh=00_AfnI22FlLJw3cHbRiXqUAIQRp1pSWWmgsYlAgNt9RC5y3Q&oe=69592A57",
        "removed_ad_count": 312,
        "ad_source": 1,
        "category_name": "Wine, Beer & Spirits Store",
        "source_advertiser_id": "186022184808923",
        "source_advertiser_link": "https://facebook.com/WijnvoordeelBE"
      }
    ],
    "product": {
      "currency": "EUR",
      "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"
      ],
      "name": "Infinitum Grillo",
      "price": 5.79,
      "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,
      "category_id": "62739aec38365b2f72048ebd",
      "ad_platform": [
        "FACEBOOK",
        "INSTAGRAM",
        "MESSENGER",
        "THREADS"
      ],
      "category_name": "Food",
      "e_commerce_platform": "magento",
      "price_usd": 6.82,
      "source_product_id": "c068345331a01d1216591db170f03672",
      "image_url": "https://fb-cdn.ppspy.com/images/pimg_c1cb26db9e59ba4c70688.png",
      "source_product_link": "https://www.wijnvoordeel.be/infinitum-grillo?channable=019969736b75004b3230303738324e",
      "store_id": "2382cd09c06c7d31cdca5cb00be71baa",
      "user_collected": 2
    },
    "store": {
      "id": "2382cd09c06c7d31cdca5cb00be71baa",
      "name": "wijnvoordeel.be",
      "e_commerce_platform": "magento",
      "logo_url": "https://fb-cdn.pipiads.com/icon_ad0a30d8c8334ccbf37488a8ce91377b.png",
      "month_visits": 19928,
      "source_store_link": "http://wijnvoordeel.be"
    },
    "ad_started_history": [
      {
        "count": 1,
        "date": "2025-12-27"
      }
    ]
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 1,
  "success": true,
  "fail": false
}

Error Code Descriptions

Error Code Description
200 Success
400 Request parameter error, incorrect product ID format
401 Unauthorized, API key is invalid or expired
403 Insufficient permissions, insufficient account balance or restricted API access
404 Product does not exist, product with specified ID not found
444 Too many requests, rate limit triggered
500 Internal server error, please try again later

Notes

  1. Product ID Acquisition: Product ID must be obtained from the ad product search API (/v3/api/open/ppspy/ad-products/search) response
  2. Data Integrity: Some fields may be null, indicating that the data has not been collected or is not applicable to the product
  3. Advertiser Count: The advertisers array may contain multiple advertisers, indicating that multiple advertisers are promoting the same product
  4. Trend Data: ad_started_history provides time series data that can be used to draw trend charts
  5. Time Format:
    • Product and advertiser time fields use Unix timestamps (seconds)
    • Trend data dates use UTC time in YYYY-MM-DD format
  6. Currency Units: All price-related fields (price, price_usd, ad_cost) may have different units, pay attention to distinguish them
  7. Ad Platforms: The ad_platform field may contain multiple platforms, such as FACEBOOK, INSTAGRAM, AUDIENCE_NETWORK, MESSENGER, etc.
  8. Category Information: Products and advertisers may belong to different categories, category_id and category_name correspond to product and advertiser categories respectively
  9. Data Updates: Ad data is updated regularly, it is recommended to re-query periodically to get the latest data
  10. Collection Status: The user_collected field reflects the collection status of the current API user, different users may get different values when querying the same product