# 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](https://www.pipispy.com/zh/doc/others-region), 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](https://www.pipispy.com/zh/doc/others-product-category), 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 ```bash 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 ```json { "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 ```json { "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 |