Ad Store Rank List Interface
Interface Information
- Interface Name: Get Ad Store Rank List
- Request Method: POST
- Interface Address:
/open-api/v1/data - Interface Path:
/v3/api/open/rank/store/list - Interface Description: Retrieve ad store rank list information based on filter conditions with pagination support
- Pricing: Retrieving one data record consumes 1 credit
Request Headers:
- Content-Type: application/json
- Accept: application/json
Request Parameters
Request Structure
| Parameter | Type | Description | Example | Required | Default |
|---|---|---|---|---|---|
key | string | User's external API request key | "your_api_key_here" | Yes | |
uri | string | Interface path | "/v3/api/open/rank/store/list" | Yes | |
params | object | Interface parameter object | See parameter list | Yes |
Request Body Parameters (params object)
| Parameter | Type | Required | Description |
|---|---|---|---|
data_type | Integer | Yes | Data platform type, determines which platform's ad store data to query. Values: 0-All platforms data (aggregate data from TikTok + Facebook + Meta Ad Library), 1-TikTok platform data, 2-Facebook platform data, 3-Meta Ad Library data. This parameter affects the data source and statistical metrics for other filter fields |
time | Long | Yes | Data time range, determines the query time dimension. Values: 3-All data (no time limit), 4-Yesterday data, 0-Last 7 days data, 1-Last 1 month (30 days) data, 2-Last 3 months (90 days) data. Note: When time != 0, related data fields will return change/increment data for that time range |
sort | Integer | Yes | Sort field. Values: 0-Sort by ad count, 1-Sort by ad plays (when data_type=3 means sort by reach/ad plays), 2-Sort by likes, 4-Sort by delivery days, 6-Sort by ad spend (USD), 7-Sort by ad start date, 8-Sort by ad end date, 10-Sort by monthly traffic, 13-Sort by estimated orders, 14-Sort by advertiser count |
sort_type | String | Yes | Sort order, used with sort parameter. Values: desc-Descending (large to small), asc-Ascending (small to large) |
page_size | Integer | Yes | Records per page, specifies the number of stores returned per page. Recommended to set between 20-200 |
current_page | Integer | Yes | Current page number, page numbers start from 1 |
keyword | String | No | Keyword search, for fuzzy matching store related information. Supports searching store name and store URL. System automatically removes https://, http://, www. prefixes. Recommend using pure domain for search. Must be used with search_type parameter |
search_type | Integer | No | Keyword search type, specifies the search scope for keyword parameter. Values: 1-Search by keyword (results can be store name or store URL), 5-Search by store name, 4-Search by store URL |
start_time_start | Long | No | Ad start date - start value, for filtering stores with ad start dates in specified range. Data type: timestamp (seconds). Queries ad start time for corresponding platform based on data_type |
start_time_end | Long | No | Ad start date - end value, used with start_time_start to define upper limit of time range. Data type: timestamp (seconds) |
end_time_start | Long | No | Ad end date - start value, for filtering stores with ad end dates in specified range. Data type: timestamp (seconds). Queries ad end time for corresponding platform based on data_type |
end_time_end | Long | No | Ad end date - end value, used with end_time_start to define upper limit of time range. Data type: timestamp (seconds) |
goods_source_min | Long | No | Ad count - minimum value, for filtering stores with ad count in specified range. Counts ads for corresponding platform based on data_type |
goods_source_max | Long | No | Ad count - maximum value, used with goods_source_min to define upper limit of ad count range |
play_count_min | Long | No | Ad plays - minimum value, for filtering stores with ad plays in specified range. Play count is the total number of video ad plays. Counts plays for corresponding platform based on data_type |
play_count_max | Long | No | Ad plays - maximum value, used with play_count_min to define upper limit of plays range |
put_day_min | Long | No | Delivery days - minimum value, for filtering stores with ad delivery days in specified range |
put_day_max | Long | No | Delivery days - maximum value, used with put_day_min to define upper limit of delivery days range |
cpm_min | Double | No | CPM (Cost Per Thousand Impressions) - minimum value, for filtering stores with ad CPM in specified range, unit: USD. This is an estimated value, for reference only |
cpm_max | Double | No | CPM (Cost Per Thousand Impressions) - maximum value, used with cpm_min to define upper limit of CPM range, unit: USD |
cpa_min | Long | No | Estimated order conversions - minimum value, for filtering stores with estimated order conversions in specified range. This is order count estimated based on ad data and industry standards, for reference only |
cpa_max | Long | No | Estimated order conversions - maximum value, used with cpa_min to define upper limit of estimated orders range |
ad_state | Integer | No | Ad status, for filtering stores with specified ad status. Values: -1-Stopped delivery (ads stopped), 1-Active (recent ad delivery records, usually within last 3 days) |
shop_type | String Array | No | E-commerce system type list, for filtering stores using specified site builder systems. Supports: shopify, woocommerce, magento, shoplazza, shopline, shopyy, squarespace, wix, prestashop, bigcommerce, ecwid, cafe24, wordpress, etc. Example: ["shopify", "woocommerce"] |
store_countries | String Array | No | Store country list, see Countries and Regions, for filtering stores with registration/location in specified countries. Uses ISO 3166-1 alpha-2 standard country codes (2 uppercase letters). Example: ["US", "CA", "GB"] |
store_languages | String Array | No | Store language list, for filtering stores using specified languages. Uses ISO 639-1 standard language codes (2 lowercase letters). Example: ["en", "de"] |
product_category_id | String Array | No | Product category ID list, see E-commerce Categories, for filtering stores with specified product categories (Niche). Need to pass unique category identifier ID (MongoDB ObjectId format). Example: ["62739afc38365b2f72048ebe", "62739b0438365b2f72048ebf"] |
product_count_min | Long | No | Product count - minimum value, for filtering stores with product count in specified range. Product count is the number of different products promoted through ads |
product_count_max | Long | No | Product count - maximum value, used with product_count_min to define upper limit of product count range |
page_count_min | Long | No | Associated advertiser count - minimum value, for filtering stores with associated advertiser (Page/Account) count in specified range. Advertiser count is the number of different advertiser accounts running ads for this store. Counts advertisers for corresponding platform based on data_type |
page_count_max | Long | No | Associated advertiser count - maximum value, used with page_count_min to define upper limit of advertiser count range |
website_monthly_visits_min | Long | No | Website monthly visits - minimum value, for filtering stores with monthly website visits in specified range. Data sourced from third-party traffic statistics tools, this parameter is not affected by time and data_type |
website_monthly_visits_max | Long | No | Website monthly visits - maximum value, used with website_monthly_visits_min to define upper limit of monthly visits range |
reach_min | Long | No | Meta Ad Library reach - minimum value, only effective when data_type=3. Reach is the number of unique users who saw the ad at least once, data sourced from Meta Ad Library public data |
reach_max | Long | No | Meta Ad Library reach - maximum value, only effective when data_type=3. Used with reach_min to define upper limit of reach range |
facebook_library_ad_platform | String Array | No | Meta Ad Library platform list, only effective when data_type=3. Supports: FACEBOOK, INSTAGRAM, AUDIENCE_NETWORK, MESSENGER, THREADS. Example: ["FACEBOOK", "INSTAGRAM"] |
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/rank/store/list",
"params": {
"time": 0,
"sort": 0,
"sort_type": "desc",
"current_page": 1,
"data_type": 0,
"page_size": 20
}
}'
Response Parameters
Response Body Structure
{
"code": 200,
"message": "success",
"data": {
"data": [],
"page": {}
},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 20,
"success": true,
"fail": false
}
Response Field Description
| Field | Type | Description |
|---|---|---|
code | Integer | Response status code, 200 means success |
message | String | Response message |
data | Object | Response data |
data.data | Array | Ad store rank list |
data.page | Object | Pagination information |
version | String | API version |
timestamp | String | 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 |
Ad Store Rank Information Fields
| Field | Type | Description |
|---|---|---|
id | String | Data record ID |
store_id | String | Store unique identifier ID |
root_path | String | Advertiser path identifier (for tracking ad source) |
shop_type | String | Store type (shopify, woocommerce, etc.) |
plat_type | Array | Platform list running ads (tiktok, facebook, facebook-library) |
icon | String | Store avatar image URL |
is_collection | Boolean | Whether current user has favorited this store |
popular_person_count | Long | Number of users following this store |
all_data_count | Long | Total ad count across all platforms |
all_play_count | Long | Total ad impressions across all platforms |
all_digg_count | Long | Total ad likes across all platforms |
all_put_days | Long | Ad delivery days across all platforms |
all_found_time | Long | Earliest ad start time across all platforms (timestamp, seconds) |
all_latest_found_time | Long | Most recent ad 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 orders across all platforms |
all_max_cpa | Long | Maximum estimated orders across all platforms |
all_page_count | Long | Total advertiser accounts across all platforms |
all_store_ad_state | Integer | Overall ad status (-1=Stopped, 1=Active) |
tiktok_data_count | Long | Total ad count on TikTok platform |
tiktok_play_count | Long | Total ad impressions on TikTok platform |
tiktok_page_count | Long | Total advertiser accounts on TikTok platform |
facebook_data_count | Long | Total ad count on Facebook platform |
facebook_play_count | Long | Total ad impressions on Facebook platform |
facebook_page_count | Long | Total advertiser accounts on Facebook platform |
facebook_library_data_count | Long | Total ad count in Facebook Ad Library |
facebook_library_play_count | Long | Total ad impressions in Facebook Ad Library |
facebook_library_reach | Long | Facebook Ad Library reach |
facebook_library_adset_count | Long | Total ad sets in Facebook Ad Library |
facebook_library_adset_active_count | Long | Active ad sets currently running in Facebook Ad Library |
facebook_library_ad_active_count | Long | Active ads currently running in Facebook Ad Library |
facebook_library_ad_inactive_count | Long | Paused ads in Facebook Ad Library |
facebook_library_ad_offline_count | Long | Offline ads in Facebook Ad Library |
facebook_library_page_count | Long | Total advertiser accounts in Facebook Ad Library |
facebook_library_ad_platform | Array | Ad Library ad platforms (FACEBOOK, INSTAGRAM, MESSENGER, etc.) |
good_source | Array | Latest 3 ad information for the store |
website_info | Object | Store website information |
Product Source Information Fields (good_source)
| Field | Type | Description |
|---|---|---|
cover | String | Ad cover image URL |
app_image | String | App icon image URL |
count | Long | Video play count |
video_id | String | Associated video ID |
Website Information Fields (website_info)
| Field | Type | Description |
|---|---|---|
website_id | String | Website unique identifier |
website_url | String | Website URL |
website_title | String | Website title |
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) |
Pagination Information Fields
| Field | Type | Description |
|---|---|---|
total_count | Long | Total record count |
page_count | Long | Total page count |
current_page | Long | Current page number |
page_size | Long | Records per page |
is_next | Boolean | Whether has next page |
Response Example
{
"code": 200,
"message": "success",
"data": {
"data": [
{
"id": "61f57e4d9a301ef93d53b88a",
"store_id": "store_123456",
"root_path": "shop.tiktok.com",
"shop_type": "shopify",
"plat_type": ["tiktok", "facebook"],
"icon": "https://fb-cdn.pipispy.com/images/8caaedcdf7b129675d8eb51c552c7eac.png",
"all_data_count": 2285852,
"all_play_count": 76792774635,
"all_digg_count": 661586882,
"all_put_days": 59,
"all_found_time": 1700000000,
"all_latest_found_time": 1700086400,
"all_page_count": 3256,
"all_min_cpm": 15.5,
"all_max_cpm": 45.8,
"popular_person_count": 1157348,
"is_collection": false,
"good_source": [
{
"cover": "https://fb-cdn.pipispy.com/images/cover1.png",
"app_image": "https://fb-cdn.pipispy.com/images/app1.png",
"count": 1088,
"video_id": "video_001"
},
{
"cover": "https://fb-cdn.pipispy.com/images/cover2.png",
"app_image": "https://fb-cdn.pipispy.com/images/app2.png",
"count": 5715,
"video_id": "video_002"
},
{
"cover": "https://fb-cdn.pipispy.com/images/cover3.png",
"app_image": "https://fb-cdn.pipispy.com/images/app3.png",
"count": 172,
"video_id": "video_003"
}
],
"website_info": {
"website_id": "web_001",
"website_url": "https://shop.tiktok.com",
"website_title": "TikTok Shop",
"website_monthly_visits": 5000000,
"website_bounce_rate": 0.45,
"website_visit_seconds": 180
}
}
],
"page": {
"total_count": 10000,
"page_count": 500,
"current_page": 1,
"page_size": 20,
"is_next": true
}
},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 20,
"success": true,
"fail": false
}
Error Code Description
| Error Code | Description |
|---|---|
200 | Success |
400 | Invalid request parameters |
401 | Unauthorized |
403 | Insufficient permissions |
500 | Internal server error |