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 套格式对照

单 SKU 简化版（最常见）

"price": 99,
"sales": 1050

多 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%}")