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 Search - Product Search API

Overall Call Flow

1. Submit image (/v3/api/open/ai-search/image/submit or /v3/api/open/ai-search/image/submit/image-url), get image_id
   ↓
2. Wait 10-20 seconds
   ↓
3. Query processing status based on image_id (/v3/api/open/ai-search/image/status)
   ↓
4. Get result summary based on image_id (/v3/api/open/ai-search/image/resultSummary)
   ↓
5. Based on summary data and image_id, selectively call detailed list APIs:
    - Product list: /v3/api/open/ai-search/image/product/search (This API)
    - Ad list: /v3/api/open/ai-search/image/search4/ad/search
    - Store list: /v3/api/open/ai-search/image/root-path/search
    - 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 Search Product API is used to search for similar e-commerce products based on images. You need to first obtain an image_id through the image submission API, then use this API to query a list of products 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 products.


API Information

  • API Name: Image Search Product
  • Request Method: POST
  • API Address: /open-api/v1/data
  • API Path: /v3/api/open/ai-search/image/product/search
  • API Description: Query similar products based on image ID, supports 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 User's external API request key "your_api_key_here" Yes
uri string API path "/v3/api/open/ai-search/image/product/search" Yes
params object API input parameters See parameter list Yes

Request Body Parameters (params object)

Parameter Type Required Description
image_id String Yes Image ID, obtained through image submission API. Format: img_ prefix + timestamp
current_page Integer Yes Current page number, starting from 1
page_size Integer Yes Number of items per page
plat_type Integer No Platform type (0: All, 1: TikTok, 2: Facebook)
time Integer No Time range (0: All, 1: Yesterday, 7: Last 7 days, 30: Last 30 days, 90: Last 90 days)
keyword String No Search keyword
search_type Integer No Search type (1: Product title, 2: Product description, 3: Advertiser URL, 4: Advertiser name, 5: Product keywords)
category String No Product category ID list, see E-commerce Categories, use comma to separate multiple category IDs
region String No Region list, supports region codes like GB/US, see Countries and Regions, use comma to separate multiple regions
play_count_min Integer No Minimum ad play count
play_count_max Integer No Maximum ad play count
digg_count_min Integer No Minimum like count
digg_count_max Integer No Maximum like count
digg_play_rate_min Double No Minimum like rate
digg_play_rate_max Double No Maximum like rate
comment_count_min Integer No Minimum comment count
comment_count_max Integer No Maximum comment count
share_count_min Integer No Minimum share count
share_count_max Integer No Maximum share count
video_count_min Integer No Minimum ad count
video_count_max Integer No Maximum ad count
put_day_min Integer No Minimum days running
put_day_max Integer No Maximum days running
create_time_start Integer No Product creation time start value (Unix timestamp, seconds)
create_time_end Integer No Product creation time end value (Unix timestamp, seconds)
tiktok_time_start Integer No Ad start date, first discovery time start value (Unix timestamp, seconds); Note that this does not refer exclusively to the TikTok ad start time; the prefix “tiktok” is used merely as a naming convention and carries no actual distinguishing meaning. Specifically, when plat_type = 2, it refers to the Facebook ad start time; when plat_type = 0, it represents the start time of all ads collectively.
tiktok_time_end Integer No Ad start date, first discovery time end value (Unix timestamp, seconds); Please note that this does not refer exclusively to the end value of the TikTok ad start time; the prefix "tiktok" is used solely as a naming convention and has no actual distinguishing meaning. Specifically, when plat_type = 2, it refers to the end value of the Facebook ad start time, and when plat_type = 0, it represents the end value of the start time for all ads collectively.
latest_found_time_start Integer No Ad end date, latest discovery time start value (Unix timestamp, seconds)
latest_found_time_end Integer No Ad end date, latest discovery time end value (Unix timestamp, seconds)
price_min Double No Product price (USD), minimum price
price_max Double No Product price (USD), maximum price
currency String No Currency unit, use comma to separate multiple currencies
platform String No Platform identifier, use comma to separate, supports: shopify, woocommerce, shoplazza, magento, wix, shopline, squarespace, shopyy
popular_person_count_min Integer No Minimum influencer count (only valid when plat_type=1)
popular_person_count_max Integer No Maximum influencer count (only valid when plat_type=1)
root_path String No Advertiser name
id String No Product ID, use comma to separate multiple IDs
store_id String No Store unique identifier ID, 13-character string (e.g., c2d5b2547218a), corresponds to store_id field in store ranking list API response
after_id String No Pagination cursor ID (for deep pagination)
after_key String No Pagination cursor key (for deep pagination)
sort Integer No Sort method:
When plat_type=0
9-Sort by similarity (default)
0-Total start date
1-Total end date
2-Product creation time
3-Product price (USD)
4-Total ad count
5-Ad plays
6-Total likes
7-Days running

When plat_type=1
9-Sort by similarity (default)
0-TikTok ad start time
1-TikTok ad end time
2-TikTok product creation time
3-TikTok product price (USD)
4-TikTok ad count
5-TikTok play count
6-TikTok like count
7-TikTok days running
8-TikTok influencer count

When plat_type=2
9-Sort by similarity (default)
0-Facebook ad start time
1-Facebook ad end time
2-Facebook product creation time
3-Facebook product price (USD)
4-Facebook ad count
5-Facebook play count
6-Facebook like count
7-Facebook days running
sort_type String No Sort type (asc: ascending, desc: descending)

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/product/search",
    "params": {
        "image_id": "img_1737532800123456",
        "current_page": 1,
        "page_size": 20
    }
  }'

Advanced Filtering Examples

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/product/search",
    "params": {
        "image_id": "img_1737532800123456",
        "current_page": 1,
        "page_size": 20,
        "plat_type": 1,
        "region": "US,GB",
        "keyword": "fashion",
        "search_type": 2,
        "play_count_min": 10000,
        "sort": 0,
        "sort_type": "desc"
    }
  }'

Filtering by Price Range and Category

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/product/search",
    "params": {
        "image_id": "img_1737532800123456",
        "current_page": 1,
        "page_size": 20,
        "price_min": 10,
        "price_max": 100,
        "category": "62739afc38365b2f72048ebe",
        "time": 30,
        "sort": 9
    }
  }'

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 Name Type Description
code Integer Response status code, 200 indicates success
message String Response message
data Object Response data, contains data (product 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 succeeded
fail Boolean Whether request failed

Product Data Fields (data)

Field Name Type Description
id String Product unique identifier ID
title String Product title
image String Product main image URL
price Double Product price
currency String Product price currency type
usd_price Double Product USD price
platform String Product platform identifier
is_collection Boolean Whether already collected
create_time Long Product creation timestamp
tiktok_time Long TikTok platform first discovery timestamp
found_time Long TikTok platform first discovery timestamp
latest_found_time Long TikTok platform latest discovery timestamp
play_count Long TikTok platform play count
digg_count Long TikTok platform like count
digg_play_rate Double TikTok platform like-to-play ratio
comment_count Long TikTok platform comment count
share_count Long TikTok platform share count
video_count Long TikTok platform video count
put_days Long TikTok platform days running
ad_platform_list List<String> Ad platform list (e.g., tiktok, facebook)
popular_person_count Long Influencer count
facebook_data_count Long Facebook platform data count
facebook_digg_count Long Facebook platform like count
facebook_found_time Long Facebook platform first discovery timestamp
facebook_latest_found_time Long Facebook platform latest discovery timestamp
facebook_put_days Long Facebook platform days running
facebook_share_count Long Facebook platform share count
facebook_comment_count Long Facebook platform comment count
all_data_count Long All platforms data count
all_digg_count Long All platforms like count
all_found_time Long All platforms first discovery timestamp
all_latest_found_time Long All platforms latest discovery timestamp
all_put_days Long All platforms days running
all_share_count Long All platforms share count
all_comment_count Long All platforms comment count
sort_id String Sort ID (for pagination sorting)

Pagination Info Fields (page)

Field Name Type Description
total_count Long Total record count
page_count Long Total page count
current_page Long Current page number
page_size Long Page size
is_next Boolean Whether has next page

Response Examples

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "id": "product_001",
        "title": "Wireless Bluetooth Headphones",
        "image": "https://cdn-product.pipispy.com/product_001.jpg",
        "price": 29.99,
        "currency": "USD",
        "usd_price": 29.99,
        "platform": "shopify",
        "is_collection": false,
        "create_time": 1700000000,
        "tiktok_time": 1700086400,
        "found_time": 1700086400,
        "latest_found_time": 1737532800,
        "play_count": 1523456,
        "digg_count": 45678,
        "digg_play_rate": 0.03,
        "comment_count": 3456,
        "share_count": 1234,
        "video_count": 125,
        "put_days": 45,
        "ad_platform_list": ["tiktok", "facebook"],
        "popular_person_count": 23,
        "facebook_data_count": 56,
        "facebook_digg_count": 12345,
        "facebook_found_time": 1700172800,
        "facebook_latest_found_time": 1737446400,
        "facebook_put_days": 38,
        "facebook_share_count": 567,
        "facebook_comment_count": 890,
        "all_data_count": 181,
        "all_digg_count": 58023,
        "all_found_time": 1700086400,
        "all_latest_found_time": 1737532800,
        "all_put_days": 45,
        "all_share_count": 1801,
        "all_comment_count": 4346,
        "sort_id": "product_001"
      },
      {
        "id": "product_002",
        "title": "Smart Watch Fitness Tracker",
        "image": "https://cdn-product.pipispy.com/product_002.jpg",
        "price": 49.99,
        "currency": "USD",
        "usd_price": 49.99,
        "platform": "shopify",
        "is_collection": true,
        "create_time": 1699913600,
        "tiktok_time": 1700000000,
        "found_time": 1700000000,
        "latest_found_time": 1737446400,
        "play_count": 2345678,
        "digg_count": 78901,
        "digg_play_rate": 0.034,
        "comment_count": 5678,
        "share_count": 2345,
        "video_count": 198,
        "put_days": 52,
        "ad_platform_list": ["tiktok"],
        "popular_person_count": 45,
        "facebook_data_count": 0,
        "facebook_digg_count": 0,
        "facebook_found_time": 0,
        "facebook_latest_found_time": 0,
        "facebook_put_days": 0,
        "facebook_share_count": 0,
        "facebook_comment_count": 0,
        "all_data_count": 198,
        "all_digg_count": 78901,
        "all_found_time": 1700000000,
        "all_latest_found_time": 1737446400,
        "all_put_days": 52,
        "all_share_count": 2345,
        "all_comment_count": 5678,
        "sort_id": "product_002"
      }
    ],
    "page": {
      "total_count": 1000,
      "page_count": 50,
      "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 search product flow 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 (This API): /v3/api/open/ai-search/image/product/search
  6. Store Search: /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=9), product list is sorted by image similarity in descending order, with most similar products first
  2. Platform Filtering: Use plat_type parameter to filter product data from specific platforms
  3. Time Range: Use time parameter to get product data within specified time range
  4. Keyword Search: Supports multiple search types, can search by product title, description, store URL, and other dimensions
  5. Region Filtering: Supports multi-region filtering, use comma to separate multiple region codes
  6. Category Filtering: Supports filtering by product category, requires correct category ID
  7. Data Statistics: Response includes complete statistics for TikTok, Facebook, and all platforms