1688 拍立淘接口 item_search_img 返回值超细说明

适用：拿到 JSON 后不知道每个字段干啥、怎么用

目标：一眼看懂「相似度」「价格区间」「起订量」等核心指标

依据：2025-08～09 官方最新文档与实测样例

---

一、接口速览

接口	作用	图片上传方式	返回格式
item_search_img	以图搜 1688 商品	①图片 URL ②本地二进制	JSON

---

二、返回值顶层结构

{
  "items": {
    "page": "1",
    "real_total_results": 670,   // 实际库里命中同款+相似款总量
    "total_results": 670,        // 本次可翻页总量（≤real_total_results）
    "pagecount": 14,             // 总页数
    "page_size": "50",           // 每页条数（默认 50，最大 100）
    "item": [ ... ]                // 数组，下面逐字段拆
  }
}

---

三、item[] 数组单条字段全表

字段	类型	示例	业务含义
num_iid	string	"728510689123"	商品数字 ID，可用于 item_get 继续取详情
title	string	"2025 夏新款真丝连衣裙"	商品标题
pic_url	string	"https://cbu01.alicdn.com/..."	1688 压缩图 400×400
price	float / string	128.00	标价（元），部分版本返回区间见 price_range
price_range	object	{"min_price": 95, "max_price": 135}	多 SKU 时最低价~最高价
unit	string	"件"	计价单位
moq	int	2	Minimum Order Quantity 起订量
sales 或 sales_count	int	327	近 30 天已售件数
similarity	float	0.87	图片相似度 0~1，>0.8 可视为"同款"
detail_url	string	"https://detail.1688.com/offer/728510689123.html"	PC 详情页
supplier_name	string	"杭州 xx 服饰有限公司"	店铺/供应商名称
supplier_id	string	"b2b-123456"	店铺 ID，可接 seller_info 接口
location	string	"浙江 杭州市"	发货地
cat_id	string	"1031912"	商品类目 ID
search_type	int	1	1=同款 2=相似款（请求传参决定）

注：不同第三方封装包字段名大小写略有差异，但含义一致。

---

四、价格 & 销量 2 套格式对照

1. 单 SKU 简化版（最常见）

"price": 99,
"sales": 1050

1. 多 SKU 完整版

   "price": {
   "min_price": 85,
   "max_price": 120,
   "unit": "件"
   },
   "transaction": {
   "sales_count": 327,
   "turnover": 42156.5 // 30 天成交额，单位元，部分版本返回
   }

写代码时统一判断类型再取数，可防 KeyError。

---

五、相似度怎么用？

相似度区间	业务建议
≥ 0.90	高概率"同款"，可直接做比价表
0.80-0.89	款式接近，布料/印花略有差异
0.60-0.79	相似元素（领型、图案）
< 0.60	基本无关，可前端过滤掉减少噪音

---

六、易忽略但有用的小字段

• moq：起订量 2 表示"2 件起批"，做 Dropshipping 一定看。

• cat_id：抓下来后可做「类目分布」分析。

• supplier_id：同一供应商往往有多个链接，可用来合并去重。

• pic_url ：是 400×400 压缩图；想要原图把 .search.jpg 替换成 .jpg 即可。

---

七、一段 20 行 Python 打印前 5 款

import requests, time, os
APP_KEY = os.getenv("ALIBABA_APP_KEY")
APP_SECRET = os.getenv("ALIBABA_SECRET")
TOKEN = os.getenv("ALIBABA_TOKEN")

url = "https://api.1688.com/router/rest"
params = dict(
    method="1688.item_search_img",
    app_key=APP_KEY,
    access_token=TOKEN,
    imgid="https://img.alicdn.com/imgextra/...0-beehive-scenes.jpg",  # 先上传获得
    page=1, page_size=5, sort="sale",
    timestamp=int(time.time()),
)
# 生成 sign 并请求 ...（略）
data = requests.post(url, data=params).json()

for i, it in enumerate(data['items']['item'], 1):
    print(f"{i}. {it['title']}\n   "
          f"价格:{it['price']}  销量:{it['sales']}  "
          f"相似度:{it['similarity']:.1%}")

---

八、小结

1. 拍立淘返回的「相似度」是核心指标，0.8 以上即可视为同款。

2. 价格分单 SKU 与区间两种写法，代码里要做类型判断。

3. 30 天销量、起订量、发货地 3 个字段对选品最有决策价值。

4. 总页数 pagecount 不一定一次给全，超过 200 页需换图或细分类目再搜。

如遇任何疑问或有进一步的需求，请随时与我私信或者评论联系。