item_search_seller（铺搜索接口）完整文档｜竞品店铺搜索分析专用

一、接口基础定位

接口别名：商品搜索 - 店铺筛选版  item_search_seller
核心作用：输入关键词 / 类目，按店铺维度聚合返回店铺列表，批量提取竞品店铺 ID、店铺名称、店铺类型、店内爆款、均价、总销量，用于竞品店铺摸底、赛道头部商家统计。

区分两个易混淆接口

1. item_search_seller：搜关键词，返回 店铺列表（多家竞品店铺汇总，做竞品大盘分析）
2. item_search_shop：传入单个 seller_id，返回 该店铺全部商品（单店全量商品采集）

二、核心业务场景（竞品店铺分析）

1. 赛道头部竞品店铺挖掘
   输入类目关键词，批量抓取该类目下销量 TOP 自营 / POP 店铺，统计竞品玩家数量、头部店铺布局。
2. 竞品分层监控
   区分京东自营、品牌旗舰店、第三方专营店，拆分不同店铺定价区间、爆款矩阵。
3. 竞品店铺数据台账
   批量导出店铺 ID、店铺名、总动销商品数、类目均价、月销总和，生成竞品分析报表。
4. 定向竞品全量采集链路
   item_search_seller 获取全部竞品 seller_id → 循环调用  item_search_shop 拉取店内所有商品 → 再调用商品详情接口拿 SKU、主图、促销价。
5. 铺货 / 无货源商家对标
   筛选同价位、同品类竞品店铺，复制爆款标题、规格、定价策略做上新参考。
6. AI 行业舆情分析
   聚合多家竞品店铺销量、价格分布，训练行业定价模型、蓝海店铺挖掘。

三、完整请求示例入参

import requests
import json
def fetch_competitor_products(keyword, app_key):
    """通过关键词搜索获取竞品商品数据"""
    url = "https://api.taobao.com/router/rest"  # 实际地址请参考官方文档
    params = {
        "method": "taobao.item.search",
        "keyword": keyword,
        "app_key": app_key,
        "format": "json",
        "fields": "num_iid,title,price,sales"  # 按需获取字段
    }
    try:
        response = requests.get(url, params=params)
        if response.status_code == 200:
            data = response.json()
            # 注意：实际返回结构需根据API文档解析
            return data.get('items', [])
        else:
            print(f"API请求失败: {response.status_code}")
            return []
    except Exception as e:
        print(f"请求异常: {e}")
        return []
# 使用示例（注册Key https://o0b.cn/ibrad）
# products = fetch_competitor_products("无线耳机", "YOUR_APP_KEY")
# print(f"获取到 {len(products)} 个竞品商品")

四、关键返回字段（店铺维度，竞品分析核心）

1. 店铺聚合基础信息

• shopId / seller_id：店铺唯一 ID（下游采集全店商品必备主键）
• shopName：店铺全称（旗舰店 / 专营店 / 自营）
• shopScore：店铺综合评分
• sellerType：店铺类型（品牌旗舰店 / 专卖店 / 专营店）

2. 店铺经营数据（竞品分析核心指标）

• totalGoods：该店铺当前类目下在售商品总数
• sumSales：店铺类目商品总销量
• avgPrice：店铺商品均价，判断竞品定价档位
• topSkuList：店铺 TOP3 爆款商品（skuId、标题、主图、促销价、月销）

3. 单品附属字段（辅助分析店铺爆款结构）

skuId、title、mainImage、price、promotion_price、volume、couponInfo

五、调用频率 & 限流规则

1. 分页限制
   单页最大 20 条商品，无店铺分页游标，靠页码循环遍历；单关键词最多拉取前 100 页头部竞品店铺。
2. 超限报错
   code:429 请求过于频繁，需指数退避重试（1s/2s/4s）。
3. 缓存机制
   店铺聚合数据缓存 5～10 分钟，大批量竞品盘点建议凌晨错峰采集。

六、竞品店铺完整采集链路（落地流程）

1. 调用  item_search_seller 关键词检索，分页抓取全部竞品  seller_id；
2. 去重店铺 ID 列表；
3. 循环  item_search_shop 传入 seller_id，分页拉取该店所有 SKU；
4. SKU 分片批量调用商品详情接口，提取主图、多 SKU 规格、实时促销价；
5. 入库维度：店铺维度大盘数据 + 单品价格 / 销量明细，用于竞品对比分析。

七、给客户商务话术（选型介绍）

我们支持 item_search_seller店铺搜索接口，输入类目关键词即可批量抓取赛道全部竞品店铺，区分自营、旗舰店、第三方商家，同步获取店铺均价、总销量、头部爆款；搭配店铺商品、商品详情接口形成完整竞品分析链路，批量提取主图、SKU、实时促销价格，支持高并发分页采集，全程合规官方数据源，稳定无封控风险。

八、避坑要点

1. seller_info 不传 yes，不会返回店铺 ID、店铺名称，无法做竞品店铺归集；
   2 只靠关键词搜索会有大量重复店铺，入库必须以 seller_id做唯一索引去重；
   3 接口只返回类目内商品，如需店铺全品类商品，必须配套 item_search_shop；
   4 大促期间平台临时下调 QPS，大批量竞品盘点建议拆分多任务、多密钥分流。