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

Request Body Parameters (params object)

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

Shop Data Fields (data)

Product Source Fields (good_source)

Website Info Fields (website_info)

Pagination Fields (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

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