Advertiser Details API
- API Name: Get Advertiser Details
- Request Method: POST
- API Endpoint:
/open-api/v1/data
- API Path:
/v3/api/open/top-advertiser/detail
- API Description: Retrieve detailed advertiser information by advertiser ID
- Pricing: Details API pricing rules: 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/top-advertiser/detail" |
Yes |
|
| params |
object |
API input parameters object |
See parameter list |
Yes |
|
Parameter List (params object)
| Parameter |
Type |
Required |
Description |
| id |
String |
Yes |
Advertiser ID (e.g., 60bf09612980dde5e9564279), corresponds to the id field in the advertiser leaderboard list 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/top-advertiser/detail",
"params": {
"id": "60bf09612980dde5e9564279"
}
}'
Response Parameters
Response Structure
{
"code": 200,
"message": "success",
"data": {},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 1,
"success": true,
"fail": false
}
Response Field Descriptions
| Field |
Type |
Description |
| code |
Integer |
Response status code, 200 indicates success |
| message |
String |
Response message |
| data |
Object |
Advertiser detail information |
| version |
String |
API version |
| timestamp |
Number/null |
Response timestamp (null when unavailable) |
| sign |
String/null |
Response signature (null when unavailable) |
| 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 |
Advertiser Details Fields
| Field |
Type |
Description |
| id |
String |
Advertiser ID |
| root_path |
String |
Advertiser domain |
| app_image |
String |
Advertiser icon URL |
| ad_platform_list |
Array |
Ad platform list (tiktok, facebook, facebook-library) |
| shop_type |
Array |
E-commerce system type list (shopify, woocommerce, etc.) |
| data_count |
Number |
Total ad data count |
| monthly_visits |
Number |
Website monthly visits |
| first_data_time |
Number |
First data time (timestamp, seconds) |
| found_time |
Number |
First discovery time (timestamp, seconds) |
| latest_found_time |
Number |
Latest discovery time (timestamp, seconds) |
| region |
Array |
Placement region list (country codes) |
| is_collection |
Boolean |
Whether the current user has collected this advertiser |
| is_ai |
Boolean |
Whether AI-related advertiser |
| is_drama |
Boolean |
Whether short drama-related advertiser |
| all_shop_type |
Array |
All associated e-commerce system types |
| Field |
Type |
Description |
| all_data_count |
Long |
Total ad count across all platforms |
| all_play_count |
Long |
Total ad play count across all platforms |
| all_page_count |
Long |
Total advertiser account count across all platforms |
| all_put_days |
Long |
Placement days across all platforms |
| all_found_time |
Long |
Earliest discovery time across all platforms (timestamp, seconds) |
| all_latest_found_time |
Long |
Latest discovery time across all platforms (timestamp, seconds) |
| all_min_cpm |
Double |
Minimum CPM across all platforms (USD) |
| all_max_cpm |
Double |
Maximum CPM across all platforms (USD) |
| all_min_cpa |
Long |
Minimum estimated order count across all platforms |
| all_max_cpa |
Long |
Maximum estimated order count across all platforms |
| all_store_ad_state |
Integer |
Overall ad status (-1=stopped, 1=active) |
| Field |
Type |
Description |
| tiktok_data_count |
Long |
Total ad count on TikTok platform |
| tiktok_play_count |
Long |
Total ad play count on TikTok platform |
| tiktok_page_count |
Long |
Advertiser account count on TikTok platform |
| tiktok_popular_person_count |
Long |
Popular creator count on TikTok platform |
| tiktok_put_days |
Long |
Placement days on TikTok platform |
| tiktok_found_time |
Long |
First discovery time on TikTok platform (timestamp, seconds) |
| tiktok_latest_found_time |
Long |
Latest discovery time on TikTok platform (timestamp, seconds) |
| tiktok_min_cpm |
Double |
Minimum CPM on TikTok platform (USD) |
| tiktok_max_cpm |
Double |
Maximum CPM on TikTok platform (USD) |
| tiktok_min_cpa |
Long |
Minimum estimated order count on TikTok platform |
| tiktok_max_cpa |
Long |
Maximum estimated order count on TikTok platform |
| tiktok_store_ad_state |
Integer |
TikTok ad status (-1=stopped, 1=active) |
| Field |
Type |
Description |
| facebook_data_count |
Long |
Total ad count on Facebook platform |
| facebook_play_count |
Long |
Total ad play count on Facebook platform |
| facebook_page_count |
Long |
Advertiser account count on Facebook platform |
| facebook_put_days |
Long |
Placement days on Facebook platform |
| facebook_found_time |
Long |
First discovery time on Facebook platform (timestamp, seconds) |
| facebook_latest_found_time |
Long |
Latest discovery time on Facebook platform (timestamp, seconds) |
| facebook_min_cpm |
Double |
Minimum CPM on Facebook platform (USD) |
| facebook_max_cpm |
Double |
Maximum CPM on Facebook platform (USD) |
| facebook_min_cpa |
Long |
Minimum estimated order count on Facebook platform |
| facebook_max_cpa |
Long |
Maximum estimated order count on Facebook platform |
| facebook_store_ad_state |
Integer |
Facebook ad status (-1=stopped, 1=active) |
| Field |
Type |
Description |
| facebook_library_data_count |
Long |
Total ad count in Meta Ad Library |
| facebook_library_play_count |
Long |
Total ad play count in Meta Ad Library |
| facebook_library_page_count |
Long |
Advertiser account count in Meta Ad Library |
| facebook_library_put_days |
Long |
Placement days in Meta Ad Library |
| facebook_library_found_time |
Long |
First discovery time in Meta Ad Library (timestamp, seconds) |
| facebook_library_latest_found_time |
Long |
Latest discovery time in Meta Ad Library (timestamp, seconds) |
| facebook_library_min_cpm |
Double |
Minimum CPM in Meta Ad Library (USD) |
| facebook_library_max_cpm |
Double |
Maximum CPM in Meta Ad Library (USD) |
| facebook_library_min_cpa |
Long |
Minimum estimated order count in Meta Ad Library |
| facebook_library_max_cpa |
Long |
Maximum estimated order count in Meta Ad Library |
| facebook_library_reach |
Long |
Reach in Meta Ad Library |
| facebook_library_adset_count |
Long |
Total ad set count in Meta Ad Library |
| facebook_library_adset_active_count |
Long |
Active ad set count currently being placed in Meta Ad Library |
| facebook_library_ad_active_count |
Long |
Active ad count currently being placed in Meta Ad Library |
| facebook_library_ad_inactive_count |
Long |
Paused ad count in Meta Ad Library |
| facebook_library_ad_offline_count |
Long |
Offline ad count in Meta Ad Library |
| facebook_library_ad_state |
Integer |
Meta Ad Library ad status (-1=stopped, 1=active) |
| Field |
Type |
Description |
| website_id |
String |
Website unique identifier |
| website_icon |
String |
Website icon URL |
| website_title |
String |
Website title |
| website_url |
String |
Website link |
| website_languages |
Array |
Languages used by the website |
| website_countries |
Array |
Countries where the website is located |
| website_currencies |
Array |
Currencies supported by the website |
| website_monthly_visits |
Long |
Website monthly visits |
| website_bounce_rate |
Double |
Website bounce rate (0.0-1.0) |
| website_visit_seconds |
Long |
Website average visit duration (seconds) |
Response Example
{
"code": 200,
"message": "success",
"data": {
"id": "61f57e4d9a301ef93d53b88a",
"root_path": "example-shop.com",
"app_image": "https://fb-cdn.pipispy.com/images/example.png",
"ad_platform_list": ["tiktok", "facebook", "facebook-library"],
"shop_type": ["shopify"],
"data_count": 1250,
"monthly_visits": 5000000,
"first_data_time": 1675830644,
"found_time": 1675830644,
"latest_found_time": 1752202412,
"region": ["US", "CA", "GB", "DE", "FR"],
"is_collection": false,
"is_ai": false,
"is_drama": false,
"all_shop_type": ["shopify"],
"all_data_count": 2500,
"all_play_count": 76792774635,
"all_page_count": 3256,
"all_put_days": 180,
"all_found_time": 1675830644,
"all_latest_found_time": 1752202412,
"all_min_cpm": 15.5,
"all_max_cpm": 45.8,
"all_min_cpa": 50,
"all_max_cpa": 500,
"all_store_ad_state": 1,
"tiktok_data_count": 1000,
"tiktok_play_count": 50000000000,
"tiktok_page_count": 1500,
"tiktok_popular_person_count": 1157348,
"tiktok_put_days": 150,
"tiktok_found_time": 1675830644,
"tiktok_latest_found_time": 1752202412,
"tiktok_min_cpm": 18.0,
"tiktok_max_cpm": 42.5,
"tiktok_min_cpa": 60,
"tiktok_max_cpa": 450,
"tiktok_store_ad_state": 1,
"facebook_data_count": 800,
"facebook_play_count": 20000000000,
"facebook_page_count": 1200,
"facebook_put_days": 120,
"facebook_found_time": 1680000000,
"facebook_latest_found_time": 1752000000,
"facebook_min_cpm": 12.0,
"facebook_max_cpm": 38.0,
"facebook_min_cpa": 45,
"facebook_max_cpa": 400,
"facebook_store_ad_state": 1,
"facebook_library_data_count": 700,
"facebook_library_play_count": 6792774635,
"facebook_library_page_count": 556,
"facebook_library_put_days": 90,
"facebook_library_found_time": 1685000000,
"facebook_library_latest_found_time": 1752202412,
"facebook_library_min_cpm": 20.0,
"facebook_library_max_cpm": 50.0,
"facebook_library_min_cpa": 70,
"facebook_library_max_cpa": 550,
"facebook_library_reach": 15000000,
"facebook_library_adset_count": 150,
"facebook_library_adset_active_count": 80,
"facebook_library_ad_active_count": 200,
"facebook_library_ad_inactive_count": 100,
"facebook_library_ad_offline_count": 400,
"facebook_library_ad_state": 1,
"website_info": {
"website_id": "web_001",
"website_icon": "https://fb-cdn.pipispy.com/images/icon.png",
"website_title": "Example Shop",
"website_url": "https://example-shop.com",
"website_languages": ["en", "de", "fr"],
"website_countries": ["US", "CA", "GB"],
"website_currencies": ["USD", "EUR", "GBP"],
"website_monthly_visits": 5000000,
"website_bounce_rate": 0.45,
"website_visit_seconds": 180
}
},
"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, such as missing advertiser ID |
| 403 |
Insufficient permissions |
| 404 |
Advertiser does not exist |
| 444 |
Too many requests, rate limit triggered |
| 500 |
Internal server error |