# 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](https://www.pipispy.com/zh/doc/others-product-category), use comma to separate multiple category IDs |
| region | String | No | Region list, supports region codes like GB/US, see [Countries and Regions](https://www.pipispy.com/zh/doc/others-region), 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
```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/ai-search/image/product/search",
"params": {
"image_id": "img_1737532800123456",
"current_page": 1,
"page_size": 20
}
}'
```
### Advanced Filtering Examples
#### Using Keywords and Region Filtering
```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/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
```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/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
```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
#### 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\ | 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
```json
{
"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 |
---
## Related APIs
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