微店关键词搜索商品列表 API 实战：micro.item_search 全流程指南

关键词：微店 API、item_search、关键词搜索、签名鉴权、分页抓取、Python 爬虫

一、接口定位与能力

micro.item_search 是微店开放平台唯一面向"全站商品"的搜索级接口，可根据关键词返回商品 ID、标题、价格、销量、店铺、主图等 20+ 字段，支持分页、价格/销量排序，是选品、竞品监控、市场调研的"入口级"API。

官方地址
https://api-gw.onebound.cn/micro/item_search/（第三方聚合）

或微店官方网关 https://api.weidian.com/v3/micro/item_search（需申请白名单）
协议：HTTP GET/POST，JSON 返回
默认 QPS：200，峰值 429 会限流，需指数退避

二、公共参数与请求语法

字段	类型	必填	说明
key	String	是	平台分配的 AppKey
secret	String	是	平台分配的 AppSecret
api_name	String	是	固定值 `item_search`
q	String	是	搜索关键词，如"徒步鞋"
page	Int	否	页码，默认 1
page_size	Int	否	每页条数，默认 20，最大 100
sort	String	否	`sales_desc` 销量降序，`price_asc` 价格升序 ...
timestamp	Int	是	秒级时间戳，10 位
sign	String	是	动态签名，见下方算法

三、签名算法（HMAC-SHA256）

将除 sign 外的所有 Query 参数按 key 升序排列；
拼成 key1=value1&key2=value2 后，首尾拼接 AppSecret；
做 HMAC-SHA256，输出 64 位大写 HEX。

Python 实现：

python 复制代码

import hmac, hashlib, urllib.parse, time

def calc_sign(p: dict, secret: str) -> str:
    s = '&'.join([f"{k}={urllib.parse.quote_plus(str(p[k]))}"
                  for k in sorted(p)])
    return hmac.new(secret.encode(), s.encode(),
                    hashlib.sha256).hexdigest().upper()

四、最小可运行 Demo（单页）

Python

python 复制代码

#!/usr/bin/env python3
# weidian_item_search.py
import requests, json, time, hmac, hashlib, urllib.parse

APP_KEY    = '你的AppKey'
APP_SECRET = '你的AppSecret'
KEYWORD    = '女装'

def sign(p: dict) -> str:
    s = '&'.join([f"{k}={urllib.parse.quote_plus(str(p[k]))}"
                  for k in sorted(p)])
    return hmac.new(APP_SECRET.encode(), s.encode(),
                    hashlib.sha256).hexdigest().upper()

def search(keyword: str, page: int = 1, page_size: int = 20):
    url = 'https://api-gw.onebound.cn/micro/item_search/'
    params = {
        'key'        : APP_KEY,
        'api_name'   : 'item_search',
        'q'          : keyword,
        'page'       : page,
        'page_size'  : page_size,
        'timestamp'  : int(time.time())
    }
    params['sign'] = sign(params)
    r = requests.get(url, params=params, timeout=5)
    return r.json()

if __name__ == '__main__':
    data = search(KEYWORD, page=1, page_size=5)
    items = data['items']['item']
    for it in items:
        print(it['title'], it['price'], it['sales'])

运行结果（示例）：

复制代码

重磅推荐羊绒大衣 1360 129
SS24春夏羊绒背心 478 18
复古丹宁外套 610 59
...

五、把脚本升级成"爬虫"式多页抓取

目标：一次性拿回 3 000 件"徒步鞋"商品，落库存分析。

自动翻页：读取返回的 pagecount 字段，递归抓取；
限速：单线程 200 QPS 上限，每页间隔 0.2 s；
异常处理：429 限流时退避 2 s，最多重试 3 次；
落库：MongoDB 按 num_iid 唯一索引，重复更新。

核心代码：

抓取 3 000 条耗时约 2 min，平均 40 QPS，安全不撞限。

六、数据字段速览

字段	示例	说明
num_iid	7235227171	商品唯一 ID，可拼接详情页 URL
title	重磅推荐‼️羊绒大衣	商品标题，含 Emoji
price	1360	现价（元）
original_price	1458	划线价
sales	129	已售件数
pic_url	https://si.geilicdn.com/...	主图 800×800
detail_url	https://weidian.com/item.html?itemID=...	可直跳微店
shop_id	1828271009	店铺 ID
seller_nick	芳心之选店	店铺昵称

七、常见报错与排查

错误码	原因	解决方案
15	签名错误	检查参数排序、URL 编码、HMAC 是否大写
26	调用超限	降速或申请更高配额
4003	关键词为空	必填字段缺失
5xx	后端抖动	指数退避重试

八、合规与版权提示

微店官方允许"自用型"数据抓取，但禁止将商品图片、描述等版权内容打包转售或对外提供 SaaS 服务；
建议把调用频率控制在 200 QPS 以内，若需更高配额，走"企业认证"通道；
数据落库后请做脱敏处理，用户手机号、收货地址等隐私字段切勿落盘。

九、结语

通过 micro.item_search，你可在 30 分钟内完成"关键词 → 商品列表 → 持久化 → 差异对比"的完整闭环：

选品：每天凌晨跑一次"徒步鞋"，销量>100 且涨幅>20 % 的商品自动加入选品池；
监控：对竞品店铺做 30 min 级价格跟踪，变动即飞书机器人告警；
分析：结合 item_get 详情接口，把 SKU、库存、主图一并拉回，做聚类定价模型。