# 以图搜店铺接口 ## 调用整体流程 ``` 1. 提交图片 （/v3/api/open/ai-search/image/submit或/v3/api/open/ai-search/image/submit/image-url） ↓ 2. 等待10-20秒 ↓ 3. 查询处理状态（/v3/api/open/ai-search/image/status）（本接口） ↓ 4. 获取结果摘要（/v3/api/open/ai-search/image/resultSummary） ↓ 5. 根据摘要数据，选择性调用详细列表接口： - 产品列表：/v3/api/open/ai-search/image/product/search - 广告列表：/v3/api/open/ai-search/image/search4/ad/search - 店铺列表：/v3/api/open/ai-search/image/root-path/search （本接口） - TikTok产品：/v3/api/open/ai-search/image/tiktok-product/search - TikTok店铺：/v3/api/open/ai-search/image/tiktok-shop/search ``` ## 接口概述 以图搜店铺接口用于根据图片搜索相似的广告店铺（广告主）。需要先通过图片提交接口获取 `image_id`，然后使用该接口查询与图片相似的店铺列表。 该接口支持丰富的过滤条件，包括平台类型、数据类型、地区、关键词、互动数据范围、时间范围等多维度筛选，帮助用户精准定位目标店铺。 --- ## 接口信息 - **接口名称**: 以图搜店铺 - **请求方法**: POST - **接口地址**: `/open-api/v1/data` - **接口路径**: `/v3/api/open/ai-search/image/root-path/search` - **接口描述**: 根据图片ID查询相似店铺，支持多维度过滤和排序 - **价格说明**: 获取一条数据结果消耗1 credit **请求头:** - Content-Type: application/json - Accept: application/json --- ## 请求参数 ### 请求结构 | 参数名 | 类型 | 描述 | 示例 | 必填 | 默认值 | | ------ | ------ | --------------------------- | ------------------------------------------------- | ---- | ------ | | key | string | 用户申请的外部 api 请求 key | "your_api_key_here" | 是 | | | uri | string | 接口路径 | "/v3/api/open/ai-search/image/root-path/search" | 是 | | | params | object | 接口入参对象 | 见参数列表 | 是 | | ### 请求体参数 (params 对象) | 参数名 | 类型 | 必填 | 描述 | |----------------------|----------------|------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | image_id | String | 是 | 图片ID,通过图片提交接口获得。格式:img_开头+时间戳 | | data_type | Integer | 是 | 数据平台类型 (0:全平台数据, 1:TikTok平台数据, 2:Facebook平台数据, 3:Meta广告资料库数据) | | time | Long | 是 | 数据时间范围 (3:全部数据, 4:昨天数据, 0:近7天数据, 1:近1个月数据, 2:近3个月数据) | | sort | Integer | 是 | 排序字段 (0:按广告数排序, 1:按广告播放数排序, 2:按点赞数排序, 4:按投放天数排序, 6:按广告花费排序, 7:按广告开始日期排序, 8:按广告结束日期排序, 10:按相似度排序(默认), 13:按预估订单数排序, 14:按广告主数排序) | | sort_type | String | 否 | 排序方式 (desc:降序, asc:升序) | | page_size | Integer | 是 | 每页记录数,建议设置在20-200之间 | | current_page | Integer | 是 | 当前页码,从1开始 | | keyword | String | 否 | 搜索关键词,支持搜索店铺名字和店铺URL | | search_type | Integer | 否 | 关键词搜索类型 (1:按关键词搜索, 4:按店铺URL搜索, 5:按店铺名字搜索) | | start_time_start | Long | 否 | 广告开始日期起始值(Unix时间戳,秒) | | start_time_end | Long | 否 | 广告开始日期结束值(Unix时间戳,秒) | | end_time_start | Long | 否 | 广告结束日期起始值(Unix时间戳,秒) | | end_time_end | Long | 否 | 广告结束日期结束值(Unix时间戳,秒) | | goods_source_min | Long | 否 | 广告数量最小值 | | goods_source_max | Long | 否 | 广告数量最大值 | | play_count_min | Long | 否 | 广告播放数最小值 | | play_count_max | Long | 否 | 广告播放数最大值 | | put_day_min | Long | 否 | 投放天数最小值 | | put_day_max | Long | 否 | 投放天数最大值 | | cpm_min | Double | 否 | CPM(千次展示成本)最小值,单位:美元(USD) | | cpm_max | Double | 否 | CPM(千次展示成本)最大值,单位:美元(USD) | | cpa_min | Long | 否 | 预估订单转化数最小值 | | cpa_max | Long | 否 | 预估订单转化数最大值 | | ad_state | Integer | 否 | 广告状态 (-1:停止投放, 1:活跃) | | shop_type | List\ | 否 | 电商系统类型列表,支持:shopify、woocommerce、magento、shoplazza、shopline、shopyy、squarespace、wix、prestashop、bigcommerce、ecwid、cafe24、wordpress等 | | store_countries | List\ | 否 | 店铺所在国家列表,见 [国家地区](https://www.pipispy.com/zh/doc/others-region),使用ISO 3166-1 alpha-2标准的国家代码 | | store_languages | List\ | 否 | 店铺使用语言列表,使用ISO 639-1标准的语言代码 | | product_category_id | List\ | 否 | 产品分类ID列表,见 [电商分类](https://www.pipispy.com/zh/doc/others-product-category) | | product_count_min | Long | 否 | 产品数量最小值 | | product_count_max | Long | 否 | 产品数量最大值 | | page_count_min | Long | 否 | 关联广告主数量最小值 | | page_count_max | Long | 否 | 关联广告主数量最大值 | | website_monthly_visits_min | Long | 否 | 网站月访问量最小值 | | website_monthly_visits_max | Long | 否 | 网站月访问量最大值 | | reach_min | Long | 否 | Meta广告资料库覆盖人数最小值(仅data_type=3时有效) | | reach_max | Long | 否 | Meta广告资料库覆盖人数最大值(仅data_type=3时有效) | | facebook_library_ad_platform | List\ | 否 | Meta广告资料库投放平台列表(仅data_type=3时有效),支持:FACEBOOK、INSTAGRAM、AUDIENCE_NETWORK、MESSENGER、THREADS | --- ## 请求示例 ### 基础请求示例 #### 使用 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 } }' ``` ### 高级过滤示例 #### 使用关键词和地区过滤 ```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 } }' ``` --- ## 响应参数 ### 响应体结构 ```json { "code": 200, "message": "success", "data": { "data": [ ... ], "page": { ... } }, "version": "v1", "timestamp": null, "sign": null, "remaining_credits": 9980, "consumed_credits": 20, "success": true, "fail": false } ``` ### 响应字段说明 #### 顶层字段 | 字段名 | 类型 | 描述 | | --------- | ------- | ------------------------------------------------------ | | code | Integer | 响应状态码,200 表示成功 | | message | String | 响应消息 | | data | Object | 响应数据,包含 data(店铺列表)和 page(分页信息) | | version | String | API 版本 | | timestamp | String | 响应时间戳 | | sign | String | 响应签名 | | remaining_credits | Long | 当前请求后的剩余可用积分 | | consumed_credits | Long | 本次请求消耗的积分 | | success | Boolean | 请求是否成功 | | fail | Boolean | 请求是否失败 | #### 店铺数据字段 (data) | 字段名 | 类型 | 描述 | | ------ | ---- | ---- | | id | String | 数据记录ID | | store_id | String | 店铺唯一标识ID | | root_path | String | 广告主路径标识 | | shop_type | String | 店铺类型(shopify、woocommerce等) | | plat_type | Array | 投放广告的平台列表(tiktok、facebook、facebook-library) | | icon | String | 店铺头像图片地址 | | is_collection | Boolean | 当前用户是否已收藏该店铺 | | popular_person_count | Long | 关注该店铺的用户数量 | | all_data_count | Long | 所有平台的广告总数 | | all_play_count | Long | 所有平台的广告曝光总次数 | | all_digg_count | Long | 所有平台的广告点赞总数 | | all_put_days | Long | 所有平台的广告投放天数 | | all_found_time | Long | 所有平台中最早的广告开始时间(时间戳,秒) | | all_latest_found_time | Long | 所有平台中最近的广告时间(时间戳,秒) | | all_min_cpm | Double | 所有平台的最小CPM(美元) | | all_max_cpm | Double | 所有平台的最大CPM(美元) | | all_min_cpa | Long | 所有平台的最小预估订单数 | | all_max_cpa | Long | 所有平台的最大预估订单数 | | all_page_count | Long | 所有平台的广告主账号总数 | | all_store_ad_state | Integer | 总广告状态(-1=停止,1=活跃) | | tiktok_data_count | Long | TikTok平台的广告总数 | | tiktok_play_count | Long | TikTok平台的广告曝光总次数 | | tiktok_page_count | Long | TikTok平台的广告主账号总数 | | facebook_data_count | Long | Facebook平台的广告总数 | | facebook_play_count | Long | Facebook平台的广告曝光总次数 | | facebook_page_count | Long | Facebook平台的广告主账号总数 | | facebook_library_data_count | Long | Facebook广告库中的广告总数 | | facebook_library_play_count | Long | Facebook广告库的广告曝光总次数 | | facebook_library_reach | Long | Facebook广告库覆盖人数 | | facebook_library_adset_count | Long | Facebook广告库中的广告组总数 | | facebook_library_adset_active_count | Long | Facebook广告库中正在投放的活跃广告组数量 | | facebook_library_ad_active_count | Long | Facebook广告库中正在投放的活跃广告数量 | | facebook_library_ad_inactive_count | Long | Facebook广告库中已暂停投放的广告数量 | | facebook_library_ad_offline_count | Long | Facebook广告库中已下线的广告数量 | | facebook_library_page_count | Long | Facebook广告库中的广告主账号总数 | | facebook_library_ad_platform | Array | 广告库广告平台(FACEBOOK、INSTAGRAM、MESSENGER等) | | good_source | Array | 店铺最新发布的3条广告信息 | | website_info | Object | 店铺网站信息 | #### 商品源信息字段 (good_source) | 字段名 | 类型 | 描述 | | --------- | ------- | ---------------- | | cover | String | 广告封面图片URL | | app_image | String | 应用图标图片URL | | count | Long | 视频播放量 | | video_id | String | 关联视频ID | #### 网站信息字段 (website_info) | 字段名 | 类型 | 描述 | | ------ | ---- | ---- | | website_id | String | 网站唯一标识 | | website_url | String | 网站链接 | | website_title | String | 网站标题 | | website_monthly_visits | Long | 网站月访问量 | | website_bounce_rate | Double | 网站跳出率(0.0-1.0) | | website_visit_seconds | Long | 网站平均访问时长(秒) | #### 分页信息字段 (page) | 字段名 | 类型 | 描述 | | ------------ | ------- | ------------ | | total_count | Long | 总记录数 | | page_count | Long | 总页数 | | current_page | Long | 当前页码 | | page_size | Long | 每页记录数 | | is_next | Boolean | 是否有下一页 | --- ## 响应示例 ```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 } ``` --- ## 错误码说明 | 错误码 | 描述 | | ------ | --------------------- | | 200 | 成功 | | 400 | 请求参数错误 | | 401 | 未授权 - API 密钥无效 | | 500 | 服务器内部错误 | --- ## 相关接口 完整的以图搜店铺流程涉及以下接口: 1. **图片提交**: `/v3/api/open/ai-search/image/submit` 或 `/v3/api/open/ai-search/image/submit/image-url` 2. **处理状态查询**: `/v3/api/open/ai-search/image/status` 3. **结果摘要**: `/v3/api/open/ai-search/image/resultSummary` 4. **广告搜索**: `/v3/api/open/ai-search/image/search4/ad/search` 5. **产品搜索**: `/v3/api/open/ai-search/image/product/search` 6. **店铺搜索**(本接口): `/v3/api/open/ai-search/image/root-path/search` 7. **TikTok产品搜索**: `/v3/api/open/ai-search/image/tiktok-product/search` 8. **TikTok店铺搜索**: `/v3/api/open/ai-search/image/tiktok-shop/search` --- ## 使用说明 1. **相似度排序**: 默认情况下(sort=10),店铺列表按图片相似度降序排列,最相似的店铺排在最前面 2. **平台筛选**: 使用 data_type 参数可以筛选特定平台的店铺数据 3. **时间范围**: 使用 time 参数可以获取指定时间范围内的店铺数据 4. **关键词搜索**: 支持按店铺名字或店铺URL搜索 5. **地区过滤**: 支持按店铺所在国家筛选 6. **店铺类型**: 支持按电商系统类型筛选(如Shopify、WooCommerce等) 7. **数据统计**: 返回结果包含 TikTok、Facebook 和全平台的完整统计数据