微店关键词搜索商品列表 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 实现：

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

#!/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	后端抖动	指数退避重试