一、接口概述

item_search_seller 是1688开放平台提供的店铺检索接口，允许开发者通过关键词、行业分类、地区等条件搜索1688平台上的店铺列表。该接口广泛应用于市场调研、竞品分析、供应商筛选、电商工具开发等场景。

接口名称	功能	请求方式	返回格式
item_search_seller	搜索1688店铺列表	GET/POST	JSON

---

二、请求参数说明

公共参数

参数名	类型	必须	说明
key	String	是	调用Key（API密钥）
secret	String	是	调用密钥
api_name	String	是	API接口名称，固定为item_search_seller
cache	String	否	缓存控制，默认yes
result_type	String	否	返回格式：json、jsonu、xml等，默认json
lang	String	否	翻译语言，cn（默认）、en、ru
version	String	否	API版本号

业务参数

参数名	类型	必须	说明
q	String	是	搜索关键词（店铺名称、主营品类等）
page	Integer	否	页码，默认1
page_size	Integer	否	每页条数，默认20，最大100
cat	String	否	行业分类ID
city	String	否	地区筛选，如"浙江 杭州"
sort	String	否	排序方式（见下文）

排序方式（sort参数）

排序值	含义
default	综合排序（默认）
credit	信用等级从高到低
sale	销量从高到低
time	开店时间从新到旧

---

三、返回值顶层结构

API返回标准JSON格式，顶层结构如下：

{
  "code": 200,
  "msg": "success",
  "request_id": "2025021414300012345",
  "items": {
    "page": "1",
    "real_total_results": 1560,
    "total_results": 1560,
    "pagecount": 78,
    "page_size": "20",
    "item": [ ... ]
  }
}

字段说明

字段	类型	说明
code	Integer	状态码，200表示成功，401未授权，429请求频率过高
msg	String	状态描述，如"success"或错误信息
request_id	String	请求唯一标识符，用于问题追踪和调试
items	Object	搜索结果容器对象

---

四、分页信息字段（items层级）

字段	类型	示例	业务含义
page	String	"1"	当前页码
real_total_results	Integer	1560	实际库中符合搜索条件的店铺总数
total_results	Integer	1560	本次可翻页总量（≤real_total_results）
pagecount	Integer	78	总页数
page_size	String	"20"	每页条数
item	Array	[...]	店铺列表数组

---

五、店铺详情字段（item数组内）

每条店铺记录包含以下核心字段：

5.1 基础信息

字段	类型	示例	业务含义
seller_id / member_id	String	"b2b-2200733087881719de"	店铺/卖家唯一标识ID
seller_nick	String	"某某旗舰店"	店铺昵称/名称
shop_name	String	"杭州某某服饰有限公司"	店铺完整名称
shop_url	String	https://shop12345678.1688.com	店铺首页链接
shop_id	String	"12345678"	店铺数字ID

5.2 经营信息

表格

复制

字段	类型	示例	业务含义
main_business	String	"女装、连衣裙、T恤"	主营品类描述
cat_id	String	"1031912"	主营类目ID
cat_name	String	"女装"	主营类目名称
products_count	Integer	328	店铺商品总数
sales_count	Integer	15680	累计销量（如有）

5.3 信用与资质

字段	类型	示例	业务含义
credit_level	String	"AAA"	信用等级
credit_score	Integer	95	信用评分（0-100）
is_enterprise	Boolean	true	是否企业认证
is_factory	Boolean	true	是否源头工厂
years_in_business	Integer	8	经营年限

5.4 联系与地址信息

字段	类型	示例	业务含义
location / area	String	"浙江 杭州市"	所在地区
address	String	"杭州市余杭区..."	详细地址
contact_name	String	"张经理"	联系人（部分返回）
phone	String	"0571-88888888"	联系电话（部分返回）

5.5 交易与服务数据

字段	类型	示例	业务含义
transaction_level	String	"lv.4"	交易勋章等级
return_rate	Float	0.02	退货率（2%）
response_time	String	"2小时内"	平均响应时间
shipping_speed	String	"24小时发货"	发货速度描述

---

六、完整响应示例

{
  "code": 200,
  "msg": "success",
  "request_id": "2025021414300012345",
  "items": {
    "page": "1",
    "real_total_results": 1560,
    "total_results": 1560,
    "pagecount": 78,
    "page_size": "20",
    "item": [
      {
        "seller_id": "b2b-2200733087881719de",
        "seller_nick": "杭州丝绸源头厂家",
        "shop_name": "杭州某某丝绸服饰有限公司",
        "shop_url": "https://shop12345678.1688.com",
        "shop_id": "12345678",
        "main_business": "真丝连衣裙、丝绸围巾、真丝睡衣",
        "cat_id": "1031912",
        "cat_name": "女装",
        "products_count": 328,
        "sales_count": 15680,
        "credit_level": "AAA",
        "credit_score": 98,
        "is_enterprise": true,
        "is_factory": true,
        "years_in_business": 12,
        "location": "浙江 杭州市",
        "address": "杭州市余杭区某某路168号",
        "transaction_level": "lv.5",
        "return_rate": 0.015,
        "response_time": "1小时内",
        "shipping_speed": "24小时发货"
      },
      {
        "seller_id": "b2b-2200733087881720de",
        "seller_nick": "苏州棉麻批发基地",
        "shop_name": "苏州某某纺织品有限公司",
        "shop_url": "https://shop87654321.1688.com",
        "shop_id": "87654321",
        "main_business": "棉麻面料、棉麻服装、家居布艺",
        "cat_id": "1031913",
        "cat_name": "面料",
        "products_count": 156,
        "sales_count": 8920,
        "credit_level": "AA",
        "credit_score": 88,
        "is_enterprise": true,
        "is_factory": false,
        "years_in_business": 5,
        "location": "江苏 苏州市",
        "area": "江苏 苏州市",
        "transaction_level": "lv.3",
        "response_time": "2小时内"
      }
    ]
  }
}

---

七、店铺等级与信用体系说明

7.1 信用等级（credit_level）

等级	含义	建议合作策略
AAA	最高信用	优先合作，货源稳定
AA	优秀信用	可放心合作
A	良好信用	常规合作
B	一般信用	需小额试单验证
C	较低信用	谨慎合作，建议实地考察

7.2 交易勋章（transaction_level）

表格

复制

等级	含义	近30天交易额门槛
lv.1	新手商家	新开店
lv.2	初级商家	较低
lv.3	中级商家	中等
lv.4	高级商家	较高
lv.5	顶级商家	非常高

---

八、错误响应格式

当请求失败时，返回结构如下：

{
  "code": 401,
  "msg": "Unauthorized",
  "request_id": "2025021414300099999",
  "error": {
    "code": 401,
    "message": "Unauthorized: Invalid API Key"
  }
}

常见错误码：

错误码	含义	处理建议
400	参数错误	检查关键词q是否为空，页码是否越界
401	未授权	检查API Key和权限
429	请求频率过高	降低QPS，申请更高配额
500	服务器内部错误	联系平台技术支持
503	服务暂时不可用	稍后重试

---

九、Python调用示例

import requests
import time
import hashlib
import urllib.parse

# 配置参数
APP_KEY = "your_app_key"
APP_SECRET = "your_app_secret"
API_URL = "https://api-gw.onebound.cn/1688/item_search_seller"

def generate_sign(params, secret):
    """
    生成API签名（根据1688签名规则）
    """
    # 按参数名升序排序
    sorted_params = sorted(params.items())
    # 拼接字符串
    param_str = urllib.parse.urlencode(sorted_params)
    # 拼接密钥
    sign_str = param_str + secret
    # MD5加密
    sign = hashlib.md5(sign_str.encode()).hexdigest().upper()
    return sign

def search_sellers(keyword, page=1, page_size=20, city=None, sort="default"):
    """
    1688店铺搜索
    """
    params = {
        "key": APP_KEY,
        "api_name": "item_search_seller",
        "q": keyword,
        "page": page,
        "page_size": page_size,
        "sort": sort,
        "timestamp": int(time.time())
    }
    
    if city:
        params["city"] = city
    
    # 生成签名
    params["sign"] = generate_sign(params, APP_SECRET)
    
    try:
        response = requests.get(API_URL, params=params, timeout=30)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"请求异常: {e}")
        return None

def parse_sellers(data):
    """
    解析并打印店铺搜索结果
    """
    if not data or data.get("code") != 200:
        error_msg = data.get("msg", "未知错误") if data else "无响应数据"
        print(f"请求失败: {error_msg}")
        return
    
    items = data.get("items", {})
    sellers = items.get("item", [])
    
    print(f"共找到 {items.get('real_total_results', 0)} 家店铺，当前第 {items.get('page')} 页：\n")
    
    for idx, seller in enumerate(sellers, 1):
        print(f"{idx}. {seller.get('shop_name', '未知店铺')}")
        print(f"   昵称: {seller.get('seller_nick')}")
        print(f"   主营: {seller.get('main_business', '未填写')}")
        print(f"   信用: {seller.get('credit_level', 'N/A')} (评分: {seller.get('credit_score', 'N/A')})")
        print(f"   商品数: {seller.get('products_count', 0)}  累计销量: {seller.get('sales_count', 0)}")
        print(f"   所在地: {seller.get('location', '未知')}")
        print(f"   工厂认证: {'✓' if seller.get('is_factory') else '✗'}  企业认证: {'✓' if seller.get('is_enterprise') else '✗'}")
        print(f"   链接: {seller.get('shop_url')}\n")

# 使用示例
if __name__ == "__main__":
    # 搜索杭州地区的丝绸店铺
    result = search_sellers(
        keyword="丝绸 连衣裙", 
        page=1, 
        page_size=10,
        city="浙江 杭州",
        sort="credit"  # 按信用排序
    )
    
    if result:
        parse_sellers(result)

---

十、应用场景与最佳实践

10.1 典型应用场景

场景	搜索策略	关键字段
供应商筛选	按主营品类+信用等级排序	credit_level, is_factory, years_in_business
竞品监控	定期搜索同类店铺	seller_id, products_count, sales_count
区域选品	按地区+类目筛选	location, cat_id, main_business
源头工厂	筛选is_factory=true	is_factory, is_enterprise, address

10.2 最佳实践建议

1. 关键词优化：使用行业术语而非泛词，如"真丝连衣裙"比"衣服"更精准

2. 分页控制：建议每页20-50条，过多影响响应速度

3. 数据缓存：店铺基础信息变化较慢，建议缓存24小时以上

4. 组合筛选：结合city+cat_id可大幅提升搜索精度

5. 信用验证：优先选择credit_level≥AA且is_enterprise=true的店铺

---

十一、关联接口推荐

接口名称	功能	与item_search_seller的关系
seller_info	获取店铺详情	通过seller_id获取更详细资质信息
item_search_shop	获取店铺所有商品	通过shop_id获取店铺商品列表
item_get	获取商品详情	分析店铺具体商品质量
item_search	按关键词搜索商品	对比不同店铺同类商品

---

十二、注意事项

1. 权限申请：需先在1688开放平台申请item_search_seller接口权限

2. 频率限制：普通用户QPS限制较低，企业认证用户可达每秒5-10次

3. 数据合规：禁止非合规爬取或商用，需遵守平台数据使用规范

4. 字段变动：部分字段（如phone）可能因隐私政策调整而不再返回

5. 地区格式：city参数建议使用"省 市"格式，如"浙江 杭州"