1688获得商品类目调取商品榜单

获取商品类目 ID（alibaba.category.get）

该接口用于拉取 1688 全量类目树，获取目标类目的唯一categoryId，是调用榜单接口的前提。

1. 接口基础信息

• 请求地址：https://gw.open.1688.com/openapi/param2/2/portals.open/api/getCategory
• 请求方式：GET/POST
• 数据格式：JSON
• 频率限制：单应用 QPS≤10，日调用≤5 万次，建议本地缓存（更新周期≥24 小时）

2. 核心请求参数

参数名	类型	是否必填	说明
method	String	是	固定值：alibaba.category.get
app_key	String	是	开放平台分配的应用 ID
timestamp	Long	是	13 位 Unix 时间戳（毫秒级）
format	String	是	固定值：json
v	String	是	固定值：2.0
sign_method	String	是	固定值：md5
sign	String	是	按规则生成的签名

3. 返回核心字段

字段名	类型	说明
categoryId	Long	类目唯一 ID（调用榜单接口的核心参数）
name	String	类目中文名称
level	Int	类目层级（1-5 级，1 级为顶级类目）
parentId	Long	父类目 ID
isLeaf	Boolean	是否为叶子类目（true不可下钻）
children	Array	子类目列表（递归结构）

4. Python 调用示例

python

运行

import requests
import hashlib
import time

# 配置凭证
app_key = "你的app_key"
app_secret = "你的app_secret"
url = "https://gw.open.1688.com/openapi/param2/2/portals.open/api/getCategory"

# 构造基础参数
params = {
    "method": "alibaba.category.get",
    "app_key": app_key,
    "timestamp": str(int(time.time() * 1000)),
    "format": "json",
    "v": "2.0",
    "sign_method": "md5"
}

# 生成签名
def generate_sign(params, secret):
    param_str = "".join([f"{k}{v}" for k, v in sorted(params.items())])
    sign_str = secret + param_str + secret
    return hashlib.md5(sign_str.encode()).hexdigest().upper()

params["sign"] = generate_sign(params, app_secret)

# 发送请求
response = requests.get(url, params=params)
category_data = response.json()

# 解析类目树（递归打印，提取目标类目ID）
def parse_category(categories, level=0):
    for cat in categories:
        print(f"{'  '*level}[L{cat['level']}] {cat['name']} (ID:{cat['categoryId']})")
        if "children" in cat and cat["children"]:
            parse_category(cat["children"], level + 1)

# 执行解析
if "result" in category_data and "categories" in category_data["result"]:
    parse_category(category_data["result"]["categories"])

---

三、步骤 2：调取类目商品榜单（product.topList.query）

通过步骤 1 获取的categoryId，调用该接口获取指定类目下的商品榜单，支持多类型、多周期筛选。

1. 接口基础信息

• 请求地址：https://gw.open.1688.com/openapi/param2/1/com.alibaba.product/product.topList.query
• 请求方式：GET/POST
• 数据格式：JSON
• 数据更新：每小时更新，企业认证用户响应≤300ms

2. 核心请求参数

参数名	类型	是否必填	说明
method	String	是	固定值：product.topList.query
app_key	String	是	应用 ID
timestamp	Long	是	13 位时间戳
format	String	是	json
v	String	是	2.0
sign_method	String	是	md5
sign	String	是	签名
categoryId	Long	是	步骤 1 获取的类目 ID（支持 1-5 级）
rankType	String	是	榜单类型：complex（综合榜）、hot（热销榜）、goodPrice（好价榜）、anchorHot（主播热卖榜）、anchorNew（主播新兴榜）、anchorRecommend（主播热推榜）、VNHot（越南热销榜）、VNTrend（越南趋势榜）
pageNo	Int	否	页码，默认 1
pageSize	Int	否	每页条数，默认 20，最大 50

3. 返回核心字段

字段名	类型	说明
offerId	Long	商品 ID
title	String	商品标题
price	String	商品价格（区间 / 单价）
saleCount	Int	销量
imageUrl	String	商品主图 URL
categoryId	Long	商品所属类目 ID
sellerId	Long	卖家 ID
evaluateScore	Float	商品评分
rank	Int	榜单排名

4. Python 调用示例

python

运行

# 沿用步骤1的凭证与签名函数
target_category_id = 1031918  # 替换为步骤1获取的目标类目ID
rank_type = "hot"  # 热销榜，可按需替换

# 构造榜单请求参数
rank_params = {
    "method": "product.topList.query",
    "app_key": app_key,
    "timestamp": str(int(time.time() * 1000)),
    "format": "json",
    "v": "2.0",
    "sign_method": "md5",
    "categoryId": target_category_id,
    "rankType": rank_type,
    "pageNo": 1,
    "pageSize": 20
}

# 生成签名并请求
rank_params["sign"] = generate_sign(rank_params, app_secret)
rank_url = "https://gw.open.1688.com/openapi/param2/1/com.alibaba.product/product.topList.query"
rank_response = requests.get(rank_url, params=rank_params)
rank_data = rank_response.json()

# 解析榜单数据
if "result" in rank_data and "products" in rank_data["result"]:
    products = rank_data["result"]["products"]
    for idx, product in enumerate(products, 1):
        print(f"排名{idx} | 商品ID:{product['offerId']} | 标题:{product['title']} | 价格:{product['price']} | 销量:{product['saleCount']}")

---

四、常见问题与避坑指南

1. 权限不足（403 错误）：未申请对应接口权限，需在开放平台重新提交权限申请。
2. 签名失败 ：参数未按字母序排序 、时间戳过期（需 13 位毫秒级）、app_secret错误，需严格遵循签名规则。
3. 类目 ID 无效 ：传入的categoryId不存在或层级错误，需通过类目接口重新核对。
4. 频率超限：单应用 QPS 超 10 或日调用超 5 万，需增加缓存或申请更高权限。
5. 榜单无数据 ：类目下无对应类型榜单，或pageNo超出总页数，可更换rankType或调整页码。

---

五、进阶应用场景

• 选品分析：结合热销榜 + 好价榜，筛选高性价比爆款，辅助供应链选品。
• 竞品监控：定时拉取指定类目榜单，追踪竞品销量、价格、排名变化。
• 市场趋势：对比日 / 周 / 月榜单，识别类目增长趋势，预判市场热点。
• 跨境选品 ：调用VNHot/VNTrend榜单，适配东南亚市场需求。