1688查询榜单列表API接口解析（附 JSON 样例）

原创

用户1597063760

发布于 2026-09-21 11:15:10

1180

文章被收录于专栏：经验经验

摘要

在跨境选品、供应链市场分析、爆款挖掘业务中，需要获取 1688 类目热销榜、好价榜、综合榜商品清单，用来识别平台爆款、跟踪品类趋势。如果直接通过网页爬虫抓取榜单页面，会遇到页面改版、JS 动态渲染、反爬风控、榜单缓存变更等一系列问题，维护成本高。

1688 开放平台官方提供类目榜单接口 1688.item_search_best，可按照类目 ID 查询各类榜单商品，返回榜单排名、商品 offerId、标题、主图、阶梯价格、30 天销量、工厂标签等结构化数据，适合替代爬虫做选品系统、市场分析系统。本文完整解析接口能力、入参、返回字段，附带 JSON 样例、开发流程与踩坑点。

一、接口基础信息

1. 基础属性

接口Method：1688.item_search_best（1688查询榜单列表，taobaoapi2014前往体验）

请求网关： c0b.cc/R4rbK2 （HTTPS，支持 GET/POST）

数据格式：请求&返回均为JSON

签名算法：平台标准MD5/HMAC签名

2.适用业务场景

跨境选品系统：抓取类目热销榜单，挖掘潜力爆品

市场趋势分析：统计类目热销商品价格区间、供应商分布

竞品跟踪：监控类目头部商品上新、销量变化

供应链选品平台：基于榜单数据做货源推荐

联动商品详情 API：拿到 offerId 后拉取完整商品规格、库存信息

二、请求核心参数

参数名	类型	是否必填	说明
app_key	string	是	开放平台应用密钥
method	string	是	固定product.topList.query
timestamp	string	是	13 位毫秒时间戳
sign	string	是	接口签名
categoryId	string	是	1688 类目 ID，查询哪个类目榜单
rankType	string	是	榜单类型：hot/complex/goodPrice/anchorHot 等
pageNo	int	否	页码，从 1 开始
pageSize	int	否	每页条数，最大 50
access_token	string	否	部分主播类榜单需要用户授权 token

注意：categoryId 必须使用 1688 平台类目 ID，不能传入中文类目名称。

三、返回 JSON 样例

{
    "code": 0,
    "msg": "success",
    "request_id": "20260921101500123456",
    "data": {
        "rankInfo": {
            "rank_name": "数码配件热销榜",
            "rank_type": "hot",
            "categoryId": "123456"
        },
        "total": 80,
        "pageNo": 1,
        "pageSize": 10,
        "itemList": [
            {
                "rank": 1,
                "offerId": "681345678901",
                "title": "手机无线充电器 15W快充桌面磁吸充电器",
                "picUrl": "https://cbu01.alicdn.com/kf/H88xxxx.jpg",
                "priceRange": "12.50‑22.00",
                "minOrderQuantity": 2,
                "monthSales": 12600,
                "isFactory": true,
                "onePieceSale": true,
                "supplierName": "XX电子科技有限公司",
                "supplierArea": "广东深圳",
                "detailUrl": "https://detail.1688.com/offer/681345678901.html"
            },
            {
                "rank": 2,
                "offerId": "681345678902",
                "title": "透明手机壳 适用多型号TPU防摔保护壳",
                "picUrl": "https://cbu01.alicdn.com/kf/H22xxxx.jpg",
                "priceRange": "1.80‑3.50",
                "minOrderQuantity": 10,
                "monthSales": 9800,
                "isFactory": true,
                "onePieceSale": false,
                "supplierName": "XX塑胶制品厂",
                "supplierArea": "广东东莞",
                "detailUrl": "https://detail.1688.com/offer/681345678902.html"
            }
        ]
    }
}

四、核心返回字段释义

字段	说明
code	状态码，0 成功；非 0 为权限、参数、限流异常
request_id	请求唯一 ID，用于线上日志排查工单
rankInfo	榜单基础信息：榜单名称、榜单类型、查询类目 ID
total	榜单商品总数量（平台榜单有上限，不会返回类目全部商品）
rank	榜单排名序号，数字越小排名越靠前
offerId	商品 ID，用于调用商品详情 API 的主键
title	商品标题
picUrl	商品主图 CDN 地址，带防盗链
priceRange	阶梯价格区间字符串
minOrderQuantity	最小起订量，B 端选品核心过滤字段
monthSales	近 30 天销量，用于判断爆款热度
isFactory	是否源头工厂标识
onePieceSale	是否支持一件代发，跨境选品常用筛选条件
supplierName	供应商公司 / 店铺名称
supplierArea	供应商产地产业带
detailUrl	商品详情页链接

五、高频开发踩坑实录

类目 ID 错误：传入中文类目名称，接口返回空列表；必须使用 1688 数字类目 ID。

权限未开通：该接口不是默认开通，需要单独提交申请，未开通返回无权限错误。

榜单数据有上限：榜单不会返回类目全部商品，只返回头部排行，total 有上限。

数据非实时：榜单存在平台缓存，不要做秒级高频轮询，建议小时级定时同步。

分页不要超限：pageSize 不要超过 50，超限直接报错。

图片防盗链：返回 picUrl 不能直接对外展示，需要下载转存自有对象存储。

榜单类型不匹配：主播类榜单anchorHot需要额外授权 token，普通调用拿不到数据。

六、业务拓展

榜单接口只返回商品简略信息，拿到 offerId 后，联动：

1688 商品详情 API：获取 SKU、完整阶梯价、属性、库存

1688 运费 API：核算拿货 + 运费综合采购成本组合完成完整跨境选品分析系统。

接口返回榜单数据仅限企业内部市场分析、选品业务，禁止批量对外分发、售卖榜单数据。

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

开发经验

#1688查询榜单API

#1688API

#经验