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.

Image-to-Shop Search API

Overall Calling Process

1. Submit Image (/v3/api/open/ai-search/image/submit or /v3/api/open/ai-search/image/submit/image-url)
   ↓
2. Wait 10-20 seconds
   ↓
3. Query Processing Status (/v3/api/open/ai-search/image/status) (This API)
   ↓
4. Get Result Summary (/v3/api/open/ai-search/image/resultSummary)
   ↓
5. Based on summary data, selectively call detailed list APIs:
    - Product List: /v3/api/open/ai-search/image/product/search
    - Ad List: /v3/api/open/ai-search/image/search4/ad/search
    - Shop List: /v3/api/open/ai-search/image/root-path/search (This API)
    - TikTok Products: /v3/api/open/ai-search/image/tiktok-product/search
    - TikTok Shops: /v3/api/open/ai-search/image/tiktok-shop/search

API Overview

The Image-to-Shop Search API is used to search for similar ad shops (advertisers) based on an image. You need to first obtain an image_id through the image submission API, then use this API to query the shop list similar to the image.

This API supports rich filtering conditions, including platform type, data type, region, keywords, interaction data range, time range, and other multi-dimensional filtering to help users accurately locate target shops.


API Information

  • API Name: Image-to-Shop Search
  • Request Method: POST
  • API Endpoint: /open-api/v1/data
  • API Path: /v3/api/open/ai-search/image/root-path/search
  • API Description: Query similar shops based on image ID, supporting multi-dimensional filtering and sorting
  • Pricing: Retrieving one data result consumes 1 credit

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/ai-search/image/root-path/search" Yes
params object API input parameter object See parameter list Yes

Request Body Parameters (params object)

Parameter Type Required Description
image_id String Yes Image ID obtained from image submission API. Format: img_ prefix + timestamp
data_type Integer Yes Data platform type (0: All platforms, 1: TikTok platform, 2: Facebook platform, 3: Meta Ad Library)
time Long Yes Data time range (3: All data, 4: Yesterday's data, 0: Last 7 days, 1: Last 1 month, 2: Last 3 months)
sort Integer Yes Sort field (0: Sort by ad count, 1: Sort by ad plays, 2: Sort by likes, 4: Sort by days running, 6: Sort by ad spend, 7: Sort by ad start date, 8: Sort by ad end date, 10: Sort by similarity (default), 13: Sort by estimated orders, 14: Sort by advertiser count)
sort_type String No Sort order (desc: Descending, asc: Ascending)
page_size Integer Yes Records per page, recommended to set between 20-200
current_page Integer Yes Current page number, starting from 1
keyword String No Search keyword, supports searching shop name and shop URL
search_type Integer No Keyword search type (1: Search by keyword, 4: Search by shop URL, 5: Search by shop name)
start_time_start Long No Ad start date minimum (Unix timestamp, seconds)
start_time_end Long No Ad start date maximum (Unix timestamp, seconds)
end_time_start Long No Ad end date minimum (Unix timestamp, seconds)
end_time_end Long No Ad end date maximum (Unix timestamp, seconds)
goods_source_min Long No Minimum ad count
goods_source_max Long No Maximum ad count
play_count_min Long No Minimum ad play count
play_count_max Long No Maximum ad play count
put_day_min Long No Minimum days running
put_day_max Long No Maximum days running
cpm_min Double No Minimum CPM (Cost Per Mille), unit: USD
cpm_max Double No Maximum CPM (Cost Per Mille), unit: USD
cpa_min Long No Minimum estimated order conversions
cpa_max Long No Maximum estimated order conversions
ad_state Integer No Ad status (-1: Stopped, 1: Active)
shop_type List<String> No E-commerce system type list, supports: shopify, woocommerce, magento, shoplazza, shopline, shopyy, squarespace, wix, prestashop, bigcommerce, ecwid, cafe24, wordpress, etc.
store_countries List<String> No Shop country list, see Country Regions, using ISO 3166-1 alpha-2 standard country codes
store_languages List<String> No Shop language list, using ISO 639-1 standard language codes
product_category_id List<String> No Product category ID list, see E-commerce Categories
product_count_min Long No Minimum product count
product_count_max Long No Maximum product count
page_count_min Long No Minimum associated advertiser count
page_count_max Long No Maximum associated advertiser count
website_monthly_visits_min Long No Minimum monthly website visits
website_monthly_visits_max Long No Maximum monthly website visits
reach_min Long No Minimum Meta Ad Library reach (only valid when data_type=3)
reach_max Long No Maximum Meta Ad Library reach (only valid when data_type=3)
facebook_library_ad_platform List<String> No Meta Ad Library platform list (only valid when data_type=3), supports: FACEBOOK, INSTAGRAM, AUDIENCE_NETWORK, MESSENGER, THREADS

Request Examples

Basic Request Example

Using cURL

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/ai-search/image/root-path/search",
    "params": {
        "image_id": "img_1737532800123456",
        "data_type": 0,
        "time": 0,
        "sort": 10,
        "current_page": 1,
        "page_size": 20
    }
  }'

Advanced Filter Example

Using Keywords and Region Filtering

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/ai-search/image/root-path/search",
    "params": {
        "image_id": "img_1737532800123456",
        "data_type": 1,
        "time": 0,
        "sort": 0,
        "sort_type": "desc",
        "current_page": 1,
        "page_size": 20,
        "keyword": "fashion",
        "search_type": 5,
        "shop_type": ["shopify", "woocommerce"],
        "store_countries": ["US", "GB"],
        "play_count_min": 10000
    }
  }'

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

Top-Level Fields

Field Type Description
code Integer Response status code, 200 indicates success
message String Response message
data Object Response data, contains data (shop list) and page (pagination info)
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 request was successful
fail Boolean Whether request failed

Shop Data Fields (data)

Field Name Type Description
id String Data record ID
store_id String Shop unique ID
root_path String Advertiser path identifier
shop_type String Shop type (shopify, woocommerce, etc.)
plat_type Array Platform list where ads are running (tiktok, facebook, facebook-library)
icon String Shop avatar image URL
is_collection Boolean Whether current user has collected this shop
popular_person_count Long Number of users following this shop
all_data_count Long Total ad count across all platforms
all_play_count Long Total ad impression count across all platforms
all_digg_count Long Total ad like count across all platforms
all_put_days Long Total days running across all platforms
all_found_time Long Earliest ad start time across all platforms (timestamp, seconds)
all_latest_found_time Long Latest 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 account count 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 impression count on TikTok platform
tiktok_page_count Long Advertiser account count on TikTok platform
facebook_data_count Long Total ad count on Facebook platform
facebook_play_count Long Total ad impression count on Facebook platform
facebook_page_count Long Advertiser account count on Facebook platform
facebook_library_data_count Long Total ad count in Facebook Ad Library
facebook_library_play_count Long Total ad impression count in Facebook Ad Library
facebook_library_reach Long Facebook Ad Library reach
facebook_library_adset_count Long Total ad set count in Facebook Ad Library
facebook_library_adset_active_count Long Active running ad set count in Facebook Ad Library
facebook_library_ad_active_count Long Active running ad count in Facebook Ad Library
facebook_library_ad_inactive_count Long Paused ad count in Facebook Ad Library
facebook_library_ad_offline_count Long Offline ad count in Facebook Ad Library
facebook_library_page_count Long Advertiser account count in Facebook Ad Library
facebook_library_ad_platform Array Ad Library ad platforms (FACEBOOK, INSTAGRAM, MESSENGER, etc.)
good_source Array Latest 3 ads published by the shop
website_info Object Shop website information

Product Source Fields (good_source)

Field Name 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 Info Fields (website_info)

Field Name Type Description
website_id String Website unique identifier
website_url String Website URL
website_title String Website title
website_monthly_visits Long Monthly website visits
website_bounce_rate Double Website bounce rate (0.0-1.0)
website_visit_seconds Long Average website visit duration (seconds)

Pagination Fields (page)

Field Name Type Description
total_count Long Total record count
page_count Long Total page count
current_page Long Current page
page_size Long Records per page
is_next Boolean Has next page

Response Example

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "id": "61f57e4d9a301ef93d53b88a",
        "store_id": "store_123456",
        "root_path": "shop.example.com",
        "shop_type": "shopify",
        "plat_type": ["tiktok", "facebook"],
        "icon": "https://fb-cdn.pipispy.com/images/icon.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.example.com",
          "website_title": "Example 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 Request parameter error
401 Unauthorized - Invalid API key
500 Internal server error

The complete image-to-shop search process involves the following APIs:

  1. Image Submission: /v3/api/open/ai-search/image/submit or /v3/api/open/ai-search/image/submit/image-url
  2. Processing Status Query: /v3/api/open/ai-search/image/status
  3. Result Summary: /v3/api/open/ai-search/image/resultSummary
  4. Ad Search: /v3/api/open/ai-search/image/search4/ad/search
  5. Product Search: /v3/api/open/ai-search/image/product/search
  6. Shop Search (This API): /v3/api/open/ai-search/image/root-path/search
  7. TikTok Product Search: /v3/api/open/ai-search/image/tiktok-product/search
  8. TikTok Shop Search: /v3/api/open/ai-search/image/tiktok-shop/search

Usage Notes

  1. Similarity Sorting: By default (sort=10), shops are sorted by image similarity in descending order, with most similar shops listed first
  2. Platform Filtering: Use the data_type parameter to filter shop data from specific platforms
  3. Time Range: Use the time parameter to get shop data within a specified time range
  4. Keyword Search: Supports searching by shop name or shop URL
  5. Region Filtering: Supports filtering by shop country
  6. Shop Type: Supports filtering by e-commerce system type (such as Shopify, WooCommerce, etc.)
  7. Data Statistics: Results include complete statistics for TikTok, Facebook, and all platforms