Pipispy APIEnglish

数据消耗规则:1. 获取一条数据结果消耗1 数据,获取数据结果的更多数据详情不消耗数据。2. 广告监控: 每次监控 $1 / 月。单个监控有效期为一个月,一个月后自动停止。删除监控不会恢复监控次数,请谨慎删除。监控调用为随时且无限次。

以图搜店铺接口

调用整体流程

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<String> 否 电商系统类型列表,支持:shopify、woocommerce、magento、shoplazza、shopline、shopyy、squarespace、wix、prestashop、bigcommerce、ecwid、cafe24、wordpress等
store_countries List<String> 否 店铺所在国家列表,见 国家地区,使用ISO 3166-1 alpha-2标准的国家代码
store_languages List<String> 否 店铺使用语言列表,使用ISO 639-1标准的语言代码
product_category_id List<String> 否 产品分类ID列表,见 电商分类
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<String> 否 Meta广告资料库投放平台列表(仅data_type=3时有效),支持:FACEBOOK、INSTAGRAM、AUDIENCE_NETWORK、MESSENGER、THREADS

请求示例

基础请求示例

使用 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
    }
  }'

高级过滤示例

使用关键词和地区过滤

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
    }
  }'

响应参数

响应体结构

{
  "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 是否有下一页

响应示例

{
  "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 和全平台的完整统计数据