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