# 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\ | No | E-commerce system type list, supports: shopify, woocommerce, magento, shoplazza, shopline, shopyy, squarespace, wix, prestashop, bigcommerce, ecwid, cafe24, wordpress, etc. | | store_countries | List\ | No | Shop country list, see [Country Regions](https://www.pipispy.com/zh/doc/others-region), using ISO 3166-1 alpha-2 standard country codes | | store_languages | List\ | No | Shop language list, using ISO 639-1 standard language codes | | product_category_id | List\ | No | Product category ID list, see [E-commerce Categories](https://www.pipispy.com/zh/doc/others-product-category) | | 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\ | 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 ```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/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 ```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/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 ```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 | 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 ```json { "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 | --- ## Related APIs 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