1688 拍立淘（item_search_img）是电商开发者高频使用的以图搜货 API，通过图片 URL/Base64 快速匹配同款 / 相似商品，返回标准化 JSON 结构。本文从接口调用、JSON 结构、字段解析、Python 实战、异常处理、数据应用全链路讲解，帮你彻底掌握 1688 拍立淘 API 的 JSON 数据反馈与处理。
一、接口基础：1688 拍立淘 API 核心信息
1. 接口标识
- 接口名称：
1688.item_search_img（按图搜索商品） - 调用方式：POST/GET（支持 URL 参数 / 表单参数）
- 数据格式：请求参数 + 返回结果均为 JSON
- 图片上传：支持图片 URL、Base64 编码、本地图片（需先上传获 imgid）
- 适用场景：电商选品、同款比价、供应商查找、商品溯源、智能推荐
2. 调用必备参数（Python 请求核心）
python
运行
# 基础请求参数（第三方API/开放平台通用） params = { "method": "1688.item_search_img", # 固定接口名 "app_key": "你的AppKey", # 开放平台应用密钥 "access_token": "你的授权token", # 授权凭证 "imgid": "图片URL或Base64", # 核心：图片资源 "search_type": "1", # 1=同款，2=相似款 "page": "1", # 页码 "page_size": "50", # 每页条数（最大100） "sort": "sale_desc", # 排序：sale_desc(销量)、price_asc(价格升序) "timestamp": "1744567890", # 时间戳 "sign": "签名加密串" # 必传签名（防篡改） }
3. Python 调用基础代码（requests 实现）
python
运行
import requests import time import hashlib # 配置信息 APP_KEY = "你的AppKey" APP_SECRET = "你的AppSecret" IMG_URL = "https://example.com/product.jpg" # 商品图片URL API_URL = "https://api.1688.com/router/rest" # 官方网关 # 生成签名（1688 API必填） def generate_sign(params, secret): sorted_params = sorted(params.items()) query_str = "".join([f"{k}{v}" for k, v in sorted_params]) sign_str = secret + query_str + secret return hashlib.md5(sign_str.encode()).hexdigest().upper() # 构造请求参数 params = { "method": "1688.item_search_img", "app_key": APP_KEY, "imgid": IMG_URL, "search_type": "1", "page": 1, "page_size": 50, "sort": "sale_desc", "timestamp": int(time.time()), "format": "json", "v": "2.0" } params["sign"] = generate_sign(params, APP_SECRET) # 发送请求获取JSON response = requests.post(API_URL, data=params) json_data = response.json() # 核心：获取JSON反馈数据 print(json_data) # 打印完整JSON
二、顶层 JSON 结构：标准反馈格式
1688 拍立淘 API 返回固定层级 JSON，包含状态信息、分页信息、商品列表三大模块，以下是标准结构（含字段类型 + 说明）：
json
{ "code": 200, // 状态码：200=成功，401=未授权，429=限流 "msg": "success", // 状态描述：success/错误信息 "request_id": "abc123def456", // 请求唯一ID（问题排查必备） "items": { // 核心数据容器 "page": "1", // 当前页码 "real_total_results": 892,// 实际总匹配数（同款+相似） "total_results": 892, // 可返回总条数（≤real_total） "pagecount": 18, // 总页数 "page_size": "50", // 每页条数 "item": [ // 商品数组（核心数据） { // 单商品JSON字段（下文详解） } ] } }
顶层关键字段解析
表格
| 字段 | 类型 | 说明 | 实战用途 |
code |
Integer | 状态码：200 成功，401 授权失效，429 限流，500 服务器错误 | 先判断 code=200 再解析数据 |
msg |
String | 状态文本 | 错误时获取具体原因（如 "参数错误"） |
request_id |
String | 全局唯一请求 ID | 对接 1688 客服排查问题 |
items.real_total_results |
Integer | 真实匹配总量 | 判断数据规模，决定是否翻页 |
items.pagecount |
Integer | 总页数 | 循环翻页获取全量数据 |
items.item |
Array | 商品列表（核心） | 解析商品信息的核心数组 |
三、商品 item 字段：JSON 核心数据全解
items.item是 JSON 反馈的核心数组，每个元素对应 1 个匹配商品，包含商品基础、价格销量、图片链接、店铺信息、相似度等 20 + 关键字段：
1. 商品唯一标识（必存字段）
json
{ "num_iid": "741422477524", // 商品ID（1688唯一主键） "detail_url": "https://detail.1688.com/offer/741422477524.html", // 详情页链接 "title": "夏季纯棉T恤男士宽松短袖", // 商品标题（关键词提取核心） "similarity": 0.92, // 图片相似度（0~1，>0.8为同款） "seller_id": "12345678" // 卖家ID（供应商唯一标识） }
2. 价格 & 销量（电商核心）
json
{ "price": "29.90", // 售价（元） "promotion_price": "25.90", // 促销价（无则同price） "min_order": "2", // 起批量（B2B核心） "sales": 15600, // 累计销量（件） "unit": "件", // 销售单位 "price_range": "25.90-35.00" // 价格区间（多规格时） }
3. 图片 & 商品属性
json
{ "pic_url": "https://cbu01.alicdn.com/img/ibank/2026/xxx.jpg", // 主图链接 "pic_small_url": "https://...", // 缩略图 "cid": "123456", // 类目ID "category_name": "男装>T恤", // 类目名称 "property": "颜色:白色;尺码:M/L/XL" // 商品属性（规格） }
4. 店铺 & 物流信息
json
{ "seller_nick": "XX服饰工厂店", // 店铺名称 "area": "浙江杭州", // 店铺所在地 "shop_type": "实力商家", // 店铺类型（实力商家/普通店铺） "post_fee": "6.00", // 运费（元） "freight_template": "包邮", // 运费模板 "is_onsale": "true", // 是否在售（true/false） "one_stop_service": "true" // 是否一件代发（ Dropshipping ） }
5. 扩展字段（进阶分析）
json
{ "create_time": "2026-01-15", // 商品上架时间 "update_time": "2026-04-10", // 最后更新时间 "score": "4.8", // 店铺评分（5分制） "trade_num": 320, // 近30天交易数 "feedback_rate": "99.5%" // 好评率 }
四、Python 解析 JSON 实战：代码 + 输出
1. 完整解析代码（提取核心字段）
python
运行
# 假设已获取json_data（上文请求结果） def parse_xhs_pailitao_json(json_data): result = { "status": "失败", "total": 0, "goods_list": [] } # 1. 先判断请求状态 if json_data.get("code") != 200: result["msg"] = json_data.get("msg", "未知错误") return result # 2. 提取分页信息 items = json_data.get("items", {}) result["status"] = "成功" result["total"] = items.get("real_total_results", 0) result["page"] = items.get("page", 1) result["pagecount"] = items.get("pagecount", 0) # 3. 解析商品数组（核心） goods_list = [] for item in items.get("item", []): goods = { "goods_id": item.get("num_iid", ""), "title": item.get("title", ""), "price": item.get("price", "0"), "sales": item.get("sales", 0), "similarity": f"{item.get('similarity', 0)*100:.1f}%", "min_order": item.get("min_order", "1"), "pic_url": item.get("pic_url", ""), "detail_url": item.get("detail_url", ""), "shop_name": item.get("seller_nick", ""), "shop_area": item.get("area", ""), "one_stop": item.get("one_stop_service", False) } goods_list.append(goods) result["goods_list"] = goods_list return result # 执行解析 parsed_data = parse_xhs_pailitao_json(json_data) # 打印结果 print(f"请求状态：{parsed_data['status']}") print(f"匹配总数：{parsed_data['total']}") print("-"*50) for i, goods in enumerate(parsed_data["goods_list"][:5], 1): # 打印前5条 print(f"{i}. {goods['title']}") print(f" 价格：{goods['price']}元 | 销量：{goods['sales']} | 相似度：{goods['similarity']}") print(f" 起批：{goods['min_order']}件 | 店铺：{goods['shop_name']}({goods['shop_area']})") print(f" 链接：{goods['detail_url']}") print("-"*30)
2. 解析输出示例
plaintext
请求状态：成功 匹配总数：892 -------------------------------------------------- 1. 夏季纯棉T恤男士宽松短袖潮流百搭 价格：29.90元 | 销量：15600 | 相似度：92.0% 起批：2件 | 店铺：XX服饰工厂店(浙江杭州) 链接：https://detail.1688.com/offer/741422477524.html ------------------------------ 2. 男士纯棉短袖T恤2026新款宽松版 价格：27.50元 | 销量：12300 | 相似度：88.5% 起批：3件 | 店铺：YY服装商行(广东广州) 链接：https://detail.1688.com/offer/741422477525.html ------------------------------
五、异常 JSON 反馈：错误码 & 处理方案
1. 常见错误 JSON（实战必遇）
json
// 401 授权失效 {"code":401,"msg":"invalid access_token","request_id":"abc123"} // 429 请求限流（高频调用） {"code":429,"msg":"too many requests","request_id":"def456"} // 400 参数错误 {"code":400,"msg":"imgid is null","request_id":"ghi789"} // 500 服务器错误 {"code":500,"msg":"server error","request_id":"jkl012"}
2. Python 异常处理代码
python
运行
def safe_request(params): try: response = requests.post(API_URL, data=params, timeout=10) response.raise_for_status() # 抛出HTTP异常 json_data = response.json() # 业务异常判断 if json_data["code"] == 401: print("错误：授权token失效，重新获取token") # 自动刷新token逻辑 elif json_data["code"] == 429: print("错误：触发限流，等待5秒后重试") time.sleep(5) return safe_request(params) # 自动重试 elif json_data["code"] != 200: print(f"业务错误：{json_data['msg']}") return json_data except requests.exceptions.Timeout: print("错误：请求超时") except requests.exceptions.ConnectionError: print("错误：网络连接失败") except Exception as e: print(f"未知错误：{str(e)}") return None
六、JSON 数据进阶应用：电商实战场景
1. 数据筛选（按相似度 / 价格 / 销量）
python
运行
# 筛选：相似度>90% + 价格<30元 + 一件代发 filtered_goods = [ goods for goods in parsed_data["goods_list"] if float(goods["similarity"].replace("%","")) > 90 and float(goods["price"]) < 30 and goods["one_stop"] ] print(f"符合条件商品数：{len(filtered_goods)}")
2. 数据存储（JSON/Excel/ 数据库）
python
运行
import json import pandas as pd # 保存为JSON文件 with open("1688_pailitao_result.json","w",encoding="utf-8") as f: json.dump(parsed_data, f, ensure_ascii=False, indent=2) # 保存为Excel（数据分析） df = pd.DataFrame(parsed_data["goods_list"]) df.to_excel("1688拍立淘商品数据.xlsx", index=False)
3. 翻页获取全量数据
python
运行
# 自动翻页获取所有商品 all_goods = [] page = 1 while True: params["page"] = page json_data = safe_request(params) if not json_data or json_data.get("code")!=200: break parsed = parse_xhs_pailitao_json(json_data) all_goods.extend(parsed["goods_list"]) # 判断是否最后一页 if page >= parsed["pagecount"]: break page += 1 time.sleep(1) # 防限流 print(f"全量商品数：{len(all_goods)}")
七、总结：1688 拍立淘 JSON 核心要点
- 结构标准化：顶层
code/msg/request_id/items，商品数组item包含全维度信息 - 核心字段：
num_iid（商品 ID）、similarity（相似度 > 0.8 为同款）、price/sales（价格销量）、min_order（起批量） - Python 处理：先判断
code=200，再解析items.item，异常处理覆盖 401/429 / 超时 - 实战价值：JSON 数据可直接用于选品、比价、供应商分析、数据报表、智能推荐
掌握 1688 拍立淘 API 的 JSON 反馈，是电商 Python 开发的核心技能，可快速搭建以图搜货、供应链分析、自动选品等系统，大幅提升电商运营效率。
