随着互联网技术的发展，电商平台已经成为人们购物的主要渠道。在这个背景下，1688开放平台提供了丰富的API接口，帮助开发者更好地与平台交互，获取所需数据。本文将重点关注如何获取商品详情信息的API接口。
一、接口概述
通过1688开放平台的商品详情信息API接口，开发者可以获取商品的详细信息，包括商品名称、价格、库存、描述、参数等。这对于电商应用、比价工具、数据分析等方面具有很大价值。使用该接口需要向平台申请权限，并遵循相应的调用规则。
二、请求参数
在调用商品详情信息API接口时，需要传入相应的请求参数。通常包括商品ID、调用时间戳、密钥等。确保传入的参数准确无误，以保证接口的正常运行。
1.公共参数
名称 |
类型 |
必须 |
描述 |
key |
String |
是 |
调用key（前往申请key,必须以GET方式拼接在URL中） |
secret |
String |
是 |
调用密钥 |
api_name |
String |
是 |
API接口名称（包括在请求地址中）[item_search,item_get,item_search_shop等] |
cache |
String |
否 |
[yes,no]默认yes，将调用缓存的数据，速度比较快 |
result_type |
String |
否 |
[json,jsonu,xml,serialize,var_export]返回数据格式，默认为json，jsonu输出的内容中文可以直接阅读 |
lang |
String |
否 |
[cn,en,ru]翻译语言，默认cn简体中文 |
version |
String |
否 |
API版本 |
2.请求参数
请求参数：num_iid=610947572360
参数说明：num_iid:1688商品ID
sales_data:&sales_data=1 获取近30天成交数据
agent:&agent=1 获取1688分销代发价格数据
三、响应数据
当请求成功后，API接口会返回相应的响应数据。这些数据通常包括商品的详细信息，如商品名称、价格、库存、描述、参数等。开发者可以根据实际需求，解析并处理这些数据，以实现相应的功能。
Version: Date:
名称 |
类型 |
必须 |
示例值 |
描述 |
item |
item[] |
0 |
宝贝详情数据 |
|
num_iid |
String |
0 |
宝贝ID |
|
title |
String |
0 |
商品标题 |
|
desc_short |
String |
0 |
商品简介 |
|
price |
Float |
0 |
价格 |
|
total_price |
Float |
0 |
||
suggestive_price |
Float |
0 |
||
orginal_price |
Float |
0 |
原价 |
|
nick |
String |
0 |
卖家昵称 |
|
num |
Int |
0 |
||
detail_url |
String |
0 |
宝贝链接 |
|
pic_url |
String |
0 |
宝贝图片 |
|
brand |
String |
0 |
品牌 |
|
brandId |
Int |
0 |
品牌id |
|
rootCatId |
Int |
0 |
顶级分类ID |
|
cid |
Int |
0 |
||
desc |
String |
0 |
||
item_imgs |
Mix |
0 |
商品图片 |
|
item_weight |
String |
0 |
||
post_fee |
Float |
0 |
邮费 |
|
express_fee |
Float |
0 |
EMS费用 |
|
ems_fee |
Float |
0 |
物流费用 |
|
shipping_to |
String |
0 |
发货至 |
|
video |
video[] |
0 |
商品视频 |
|
sample_id |
String |
0 |
||
props_name |
String |
0 |
商品属性名 |
|
prop_imgs |
prop_imgs[] |
0 |
商品属性图片列表 |
|
property_alias |
String |
0 |
属性别名 |
|
props |
Mix |
0 |
商品详情 |
|
total_sold |
Int |
0 |
||
scale |
Int |
0 |
||
sellUnit |
Int |
0 |
||
skus |
skus[] |
0 |
商品规格信息列表 |
|
seller_id |
Int |
0 |
卖家ID |
|
sales |
Int |
0 |
销售额 |
|
shop_id |
Int |
0 |
店铺ID |
|
props_list |
Mix |
0 |
商品属性 |
|
seller_info |
seller_info[] |
0 |
卖家信息 |
|
tmall |
Boolean |
0 |
是否天猫 |
|
data_from |
String |
0 |
错误信息 |
|
error |
String |
0 |
错误信息 |
|
unit |
String |
0 |
单位 |
|
is_support_mix |
Boolean |
0 |
||
mix_amount |
Int |
0 |
||
mix_Begin |
Int |
0 |
||
mix_number |
Int |
0 |
||
sales_data |
Date |
0 |
||
location |
String |
0 |
发货地 |
|
props_img |
Mix |
0 |
属性图片 |
|
sales_info |
Mix |
0 |
||
desc_img |
Mix |
0 |
详情图片列表 |
|
shop_item |
Mix |
0 |
||
relate_items |
Mix |
0 |
四、调用示例与代码解析
以下是调用商品详情信息API接口的示例代码：
import requests def get_product_detail(product_id, timestamp, api_key): url = f"https://api.1688.com/product/detail?productId={product_id}×tamp={timestamp}&apiKey={api_key}" response = requests.get(url) if response.status_code == 200: return response.json() else: return None
-- 请求示例 url 默认请求参数已经URL编码处理 curl -i "https://api-gw.onebound.cn/1688/item_get/?key=<您自己的apiKey>&secret=<您自己的apiSecret>&num_iid=610947572360"
响应示例
{ "item": { "num_iid": "610947572360", "title": "厂家直销小米有品Qin2 Pro智能手机学生机老人机备用机小爱同学4G", "desc_short": "", "price": "799.00", "total_price": 0, "suggestive_price": 0, "orginal_price": "799.00", "nick": "qin多亲科技", "num": "1763", "detail_url": "https://detail.1688.com/offer/610947572360.html", "pic_url": "https://cbu01.alicdn.com/img/ibank/2020/063/830/13235038360_979836901.jpg", "brand": "", "brandId": "", "rootCatId": "", "cid": "50903", "desc": "<div id=\"offer-template-0\"></div><p><span><span>深圳市多亲科技有限公司（简称“多亲科技”)成立于2014年9月是国内领先的人工智能硬件解决方案供应商。多亲科技积极推动人工智能技术的创新研发，在人工智能终端设备、系统软件的研发和生产领域，具有深厚的技术沉淀与实力。</span></span></p><p><span> </span></p><p><span> 多亲产品销售网络覆盖全国各地乃至远销海外，欢迎企业定制、团购、经销代理。</span></p><p><span> 优质的产品、过硬的技术、完善的服务、是我们合作双赢的开篇。</span></p><p><span> <span ><strong><span >欢迎有意向者实地考察，垂询电话：13662284449.</span></strong></span></span></p><p><span> </span></p><p><span>温馨提示：</span></p><p><span><span><span>1、可定制--</span></span>承接各种订单订制！为客户定制机身、开机画面、预装软件、包装等定制！</span><br /><span><span><span>2、质量保证--</span></span>本公司专注通讯行业10年，线下线下百花齐放，客户复购率达30%以上。</span><br /><span><span><span>3、价格实惠--</span></span>本店是工厂直供，没有中间商差价，一站到客，薄利多销。</span><br /><span><span><span>4、售后服务--</span></span>本店出售的所有产品均提供1年的质保。因质量原因退换货（非人为因素）30天内换新。</span></p><p> </p><p><span><img alt=\"undefined\" height=\"446.22866894197955\" src=\"https://cbu01.alicdn.com/img/ibank/2020/560/807/14112708065_979836901.jpg\" width=\"790\" /><br /><img alt=\"undefined\" height=\"457.5154730327144\" src=\"https://cbu01.alicdn.com/img/ibank/2020/303/507/14112705303_979836901.jpg\" width=\"790\" /><br /><img alt=\"undefined\" height=\"443.2365499573014\" src=\"https://cbu01.alicdn.com/img/ibank/2020/499/812/14150218994_979836901.jpg\" width=\"790\" /><br /><img alt=\"undefined\" height=\"440.350569675723\" src=\"https://cbu01.alicdn.com/img/ibank/2020/770/128/14199821077_979836901.jpg\" width=\"790\" /><br /></span></p><p><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/588/942/13197249885_979836901.jpg\" /></p><p><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/778/789/13234987877_979836901.jpg\" /><br /><br /><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/109/489/13234984901_979836901.jpg\" /><br /><br /><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/156/072/13197270651_979836901.jpg\" /><br /><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/270/710/13235017072_979836901.jpg\" /><br /><br /><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/735/999/13234999537_979836901.jpg\" /><br /><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/549/252/13197252945_979836901.jpg\" /><br /><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/409/552/13197255904_979836901.jpg\" /><br /><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/247/935/13278539742_979836901.jpg\" /><br /><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/355/845/13278548553_979836901.jpg\" /><br /><br /></p><p><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/917/372/13197273719_979836901.jpg\" /><br /><br /><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/969/099/13234990969_979836901.jpg\" /><br /><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/175/455/13278554571_979836901.jpg\" /></p><p><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/427/386/13314683724_979836901.jpg\" /><br /><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/331/365/13278563133_979836901.jpg\" /><br /><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/654/500/13235005456_979836901.jpg\" /><br /><br /><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/542/110/13235011245_979836901.jpg\" /><br /><br /><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/291/020/13235020192_979836901.jpg\" /><br /><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/329/635/13278536923_979836901.jpg\" /><br /><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/996/155/13278551699_979836901.jpg\" /></p><p><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/230/920/13235029032_979836901.jpg\" /><br /><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/464/972/13197279464_979836901.jpg\" /><br /><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/380/275/13278572083_979836901.jpg\" /><br /><br /><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/999/462/13197264999_979836901.jpg\" /><br /><br /><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/868/245/13278542868_979836901.jpg\" /><br /><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/843/410/13235014348_979836901.jpg\" /><br /><br /><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/897/200/13235002798_979836901.jpg\" /><br /><br /><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/914/800/13235008419_979836901.jpg\" /><br /><br /><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/709/762/13197267907_979836901.jpg\" /><br /><br /><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/427/545/13278545724_979836901.jpg\" /><br /><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/741/003/13197300147_979836901.jpg\" /><br /><br /><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/175/710/13235017571_979836901.jpg\" /><br /><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/410/485/13278584014_979836901.jpg\" /><br /><br /><img alt=\"undefined\" src=\"https://cbu01.alicdn.com/img/ibank/2020/863/665/13278566368_979836901.jpg\" /><br /><br /><br /></p>", "item_imgs": [ { "url": "https://cbu01.alicdn.com/img/ibank/2020/063/830/13235038360_979836901.jpg" }, { "url": "https://cbu01.alicdn.com/img/ibank/2020/445/748/13819847544_979836901.jpg" }, { "url": "https://cbu01.alicdn.com/img/ibank/2020/487/543/13234345784_979836901.jpg" }, { "url": "https://cbu01.alicdn.com/img/ibank/2020/296/695/13418596692_979836901.jpg" }, { "url": "https://cbu01.alicdn.com/img/ibank/2020/167/778/13462877761_979836901.jpg" } ], "item_weight": "", "post_fee": "", "express_fee": "", "ems_fee": "", "shipping_to": "", "video": [], "sample_id": "", "props_name": "0:0:机身内存:64GB;1:0:颜色:铁灰色;1:1:颜色:瓷白色", "prop_imgs": { "prop_img": [] }, "property_alias": "0:0:64GB;1:0:铁灰色;1:1:瓷白色", "props": [ { "name": "品牌", "value": "多亲" }, { "name": "型号", "value": "Qin 2 Pro" }, { "name": "手机类型", "value": "老人手机" }, { "name": "外形", "value": "直板" }, { "name": "主屏尺寸", "value": "大屏幕(5.0英寸—5.9英寸)" }, { "name": "网络制式", "value": "移动4G(TD-LTE),联通/电信4G(FDD-LTE)" }, { "name": "操作系统", "value": "Android 9.0系统" }, { "name": "电池容量", "value": "2100" }, { "name": "摄像头像素", "value": "1200万-1999万" }, { "name": "存储卡", "value": "支持存储卡" }, { "name": "处理器核心", "value": "八核" }, { "name": "运行内存", "value": "2GB" }, { "name": "手机版本", "value": "大陆行货" }, { "name": "售后类型", "value": "全国联保" }, { "name": "上市时间", "value": "2019" }, { "name": "适用送礼场合", "value": "员工福利,颁奖纪念,广告促销,节日,展销会,公关策划,生日,商务馈赠" }, { "name": "3C证书编号", "value": "2019161606319519" }, { "name": "CPU品牌", "value": "展讯" }, { "name": "运营商", "value": "中国移动,中国电信,中国联通" }, { "name": "网络模式", "value": "单卡单模" }, { "name": "机身内存", "value": "64GB" }, { "name": "颜色", "value": "铁灰色,瓷白色" }, { "name": "电信设备进网许可证编号", "value": "02-B613-192425" } ], "total_sold": "1", "scale": "", "sellUnit": "", "skus": { "sku": [ { "price": "799.00", "total_price": 0, "sales": "55", "properties": "0:0;1:1", "properties_name": "0:0:机身内存:64GB;1:1:颜色:瓷白色", "quantity": "932", "sku_id": "4309097072612", "spec_id": "63828b15ad641fdb131775f32e4c050c" }, { "price": "799.00", "total_price": 0, "sales": "159", "properties": "0:0;1:0", "properties_name": "0:0:机身内存:64GB;1:0:颜色:铁灰色", "quantity": "831", "sku_id": "4302217872901", "spec_id": "0eb631954bfe8fb00a45824fc6193f2f" } ] }, "seller_id": "2206619673102", "sales": 30, "shop_id": "", "props_list": { "0:0": "机身内存:64GB", "1:0": "颜色:铁灰色", "1:1": "颜色:瓷白色" }, "seller_info": { "nick": "qin多亲科技", "user_num_id": "2206619673102", "sid": "b2b-2206619673102e9470", "title": "深圳多亲科技实力卖场", "zhuy": "https://winport.m.1688.com/page/index.html?memberId=b2b-2206619673102e9470", "shop_name": "qin多亲科技" }, "tmall": "", "data_from": "1688app", "error": "", "unit": "部", "is_support_mix": null, "mix_amount": null, "mix_begin": null, "mix_number": null, "min_num": "2", "sales_data": "", "location": "广东省 深圳市", "props_img": [], "sales_info": { "seller_num": "", "repeat_rate_purchase": "", "per_capita_purchases": "", "comment_num": "", "comment_url": "" }, "desc_img": [ "https://cbu01.alicdn.com/img/ibank/2020/560/807/14112708065_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/303/507/14112705303_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/499/812/14150218994_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/770/128/14199821077_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/588/942/13197249885_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/778/789/13234987877_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/109/489/13234984901_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/156/072/13197270651_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/270/710/13235017072_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/735/999/13234999537_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/549/252/13197252945_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/409/552/13197255904_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/247/935/13278539742_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/355/845/13278548553_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/917/372/13197273719_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/969/099/13234990969_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/175/455/13278554571_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/427/386/13314683724_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/331/365/13278563133_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/654/500/13235005456_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/542/110/13235011245_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/291/020/13235020192_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/329/635/13278536923_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/996/155/13278551699_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/230/920/13235029032_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/464/972/13197279464_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/380/275/13278572083_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/999/462/13197264999_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/868/245/13278542868_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/843/410/13235014348_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/897/200/13235002798_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/914/800/13235008419_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/709/762/13197267907_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/427/545/13278545724_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/741/003/13197300147_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/175/710/13235017571_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/410/485/13278584014_979836901.jpg", "https://cbu01.alicdn.com/img/ibank/2020/863/665/13278566368_979836901.jpg" ], "shop_item": [], "relate_items": [] }, "secache": "f75c59301daa3fc1610a8563c998f851", "secache_time": 1608276252, "secache_date": "2020-12-18 15:24:12", "translate_status": "", "translate_time": 0, "language": { "default_lang": "cn", "current_lang": "cn" }, "error": "", "reason": "", "error_code": "0000", "cache": 0, "api_info": "today:12 max:10000", "execution_time": 6.65, "server_time": "Beijing/2020-12-18 15:24:17", "client_ip": "182.111.155.89", "call_args": { "num_iid": "610947572360", "area_id": "440111" }, "api_type": "1688", "translate_language": "zh-CN", "translate_engine": "google_cn", "server_memory": "4.44MB", "request_id": "gw-2.5fdc591b3bdb0" }
异常示例
{ "error": "item-not-found", "reason": "商品没找到", "error_code": "2000", "success": 0, "cache": 0, "api_info": "today:0 max:10000", "execution_time": 0.081, "server_time": "Beijing/2020-06-10 23:44:00", "call_args": [], "api_type": "1688", "request_id": "15ee0ffc041242" }
错误码解释
状态代码(error_code) |
状态信息 |
详细描述 |
是否收费 |
0000 |
success |
接口调用成功并返回相关数据 |
是 |
2000 |
Search success but no result |
接口访问成功，但是搜索没有结果 |
是 |
4000 |
Server internal error |
服务器内部错误 |
否 |
4001 |
Network error |
网络错误 |
否 |
4002 |
Target server error |
目标服务器错误 |
否 |
4003 |
Param error |
用户输入参数错误 |
忽略 |
4004 |
Account not found |
用户帐号不存在 |
忽略 |
4005 |
Invalid authentication credentials |
授权失败 |
忽略 |
4006 |
API stopped |
您的当前API已停用 |
忽略 |
4007 |
Account stopped |
您的账户已停用 |
忽略 |
4008 |
API rate limit exceeded |
并发已达上限 |
忽略 |
4009 |
API maintenance |
API维护中 |
忽略 |
4010 |
API not found with these values |
API不存在 |
忽略 |
4012 |
Please add api first |
请先添加api |
忽略 |
4013 |
Number of calls exceeded |
调用次数超限 |
忽略 |
4014 |
Missing url param |
参数缺失 |
忽略 |
4015 |
Wrong pageToken |
参数pageToken有误 |
忽略 |
4016 |
Insufficient balance |
余额不足 |
忽略 |
4017 |
timeout error |
请求超时 |
否 |
5000 |
unknown error |
未知错误 |
否 |
五、常见问题与处理方法
在调用商品详情信息API接口时，可能会遇到一些问题，如请求超时、参数错误等。以下是一些常见问题的处理方法：
- 请求超时：检查网络连接是否正常，同时适当增加请求超时时间。
- 参数错误：仔细核对传入的请求参数，确保与文档要求一致。特别注意商品ID、时间戳和API密钥的准确性。
- 返回数据异常：检查响应数据的状态码和内容，分析可能的原因。如有需要，可联系1688开放平台技术支持寻求帮助。
六、总结与展望
通过本文的介绍，我们了解了如何使用1688开放平台的商品详情信息API接口获取商品详细信息。这一功能对于开发者来说具有很高的实用价值，可以帮助实现电商应用、比价工具、数据分析等多种功能。在未来的发展中，随着电商平台的不断壮大和开放平台技术的持续进步，我们期待看到更多实用、便捷的API接口出现，为开发者提供更多可能性。
