VVIC（搜款网）作为国内领先的服装服饰批发市场供应链平台，其开放平台的 seller_search 接口专注于提供批发市场的商家及商品排行榜数据，涵盖热销商品排行、商家销量排名、类目趋势等核心信息。该接口广泛应用于服装行业的货源选品、竞品分析、市场趋势预测等场景，为供应商、零售商提供数据支持。
一、seller_search 接口核心特性分析
- 接口定位与核心价值
seller_search 接口是 VVIC 开放平台的核心排行榜接口，不同于基础商品搜索接口，其核心特点在于：
基于真实交易数据的动态排行（支持日榜、周榜、月榜）
覆盖全平台商家及商品的多维度排序（销量、热度、增长率等）
支持按类目、地区、价格带等精准筛选
提供商家资质、供货能力、合作数据等供应链关键指标 - 接口权限与调用限制
使用 seller_search 接口需遵守 VVIC 开放平台的使用规范：
限制类型 具体规则 说明
权限要求 需申请 “排行榜数据” 权限，个人开发者需完成实名认证，企业开发者需提供营业执照 企业开发者可获取更详细的交易数据（如实际成交量）
调用频率 个人开发者：10 次 / 分钟；企业开发者：30 次 / 分钟 超过限制会触发 5 分钟临时封禁
数据返回 单次最多返回 50 条记录，最多支持 30 页（即 1500 条数据） 排行榜数据每 2 小时更新一次，无需高频调用
字段限制 个人开发者仅能获取公开数据（如商品标题、价格、销量区间）；企业开发者可获取供货价、起批量等敏感字段 敏感字段需单独签署数据使用协议 - 核心参数解析
（1）必选参数
参数名 类型 说明 示例
app_key String 应用唯一标识（从开放平台获取） "your_app_key"
timestamp Integer 时间戳（秒级，与当前时间差≤5 分钟） 1719000000
sign String 签名（按 VVIC 算法生成） 见下文 “签名生成逻辑”
rank_type String 排行榜类型 "product_sale"（商品销量榜）、"seller_sale"（商家销量榜）
period String 统计周期 "day"（日榜）、"week"（周榜）、"month"（月榜）
page Integer 页码（1≤page≤30） 1
page_size Integer 每页记录数（10≤page_size≤50） 50
（2）可选筛选参数
参数名 类型 说明 示例
category_id Integer 类目 ID（如女装 = 1001，男装 = 1002） 1001
city String 产地筛选（如 “广州”“杭州”“东莞”） "广州"
price_min Float 最低价格（单位：元） 50.0
price_max Float 最高价格（单位：元） 200.0
growth_rate Float 增长率筛选（仅对增长榜有效，≥输入值） 30（筛选增长率≥30% 的商品）
is_factory Integer 是否工厂直供（0 = 全部，1 = 仅工厂） 1
二、签名生成逻辑与返回数据结构 - 签名生成逻辑
VVIC 采用 MD5 签名算法，确保请求合法性，步骤如下：
按 参数名 ASCII 码升序 排序所有请求参数（含必选和可选参数）。
拼接为 “key1=value1&key2=value2&...” 格式的字符串（注意：sign 参数不参与签名）。
在拼接字符串末尾追加 &app_secret=你的app_secret（从开放平台获取）。
对最终字符串进行 MD5 加密，结果转为 大写字母 即为 sign 值。
排序并拼接后字符串为上述内容，MD5 加密后得到 sign=A1B2C3D4E5F67890ABCDEF1234567890。 - 返回数据结构解析
seller_search 接口返回 JSON 格式数据，核心结构包括 基础信息、排行榜数据 和 统计指标 三部分：
（1）基础信息（外层字段）
字段名 类型 说明
code Integer 状态码（0 = 成功，非 0 = 失败）
message String 状态描述（失败时返回错误原因）
total Integer 符合条件的总记录数
page Integer 当前页码
page_size Integer 每页记录数
data Array 排行榜数据列表（核心字段）
（2）商品排行榜数据（data 字段，rank_type=product_sale 时）
字段名 类型 说明
product_id String 商品 ID
title String 商品标题（含属性，如 “夏季新款连衣裙 韩版 显瘦”）
main_img String 商品主图 URL
price Float 批发价（元）
retail_price Float 建议零售价（元）
sales Integer 周期销量（件）
growth_rate Float 环比增长率（%）
seller_id String 商家 ID
seller_name String 商家名称
city String 产地
category String 所属类目
tags Array 标签（如 “爆款”“新款”“工厂直供”）
rank Integer 当前排名
last_rank Integer 上期排名（用于计算排名变化）
（3）商家排行榜数据（data 字段，rank_type=seller_sale 时）
字段名 类型 说明
seller_id String 商家 ID
seller_name String 商家名称
logo String 商家 logo URL
sales Float 周期销售额（元）
product_count Integer 在售商品数
reply_rate Float 回复率（%）
ship_time Float 平均发货时间（小时）
city String 所在地
main_category String 主营类目
cooperation_rate Float 合作成功率（%）
rank Integer 当前排名
三、Python 实现方案
以下是 seller_search 接口的完整 Python 实现，包含 基础调用框架、数据获取、趋势分析 和 可视化功能：
import requests
import time
import hashlib
import json
import logging
import pandas as pd
import matplotlib.pyplot as plt
import numpy as np
from datetime import datetime, timedelta
from collections import defaultdict
from typing import Dict, List, Optional, Tuple
配置日志
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s - %(levelname)s - %(message)s"
)
配置中文显示
plt.rcParams["font.family"] = ["SimHei", "WenQuanYi Micro Hei", "Heiti TC"]
plt.rcParams["axes.unicode_minus"] = False
class VVICSellerSearch:
"""VVIC seller_search 接口封装类，用于获取和分析排行榜数据"""
def __init__(self, app_key: str, app_secret: str):
"""
初始化 VVIC API 客户端
:param app_key: 应用的 app_key（从开放平台获取）
:param app_secret: 应用的 app_secret（从开放平台获取）
"""
self.app_key = app_key
self.app_secret = app_secret
self.gateway_url = "https://api.vvic.com/v2/rank/seller_search"
self.session = requests.Session()
self.session.headers.update({
"Content-Type": "application/x-www-form-urlencoded;charset=utf-8",
"User-Agent": "VVICSellerSearch/1.0.0 (Python)"
})
# 频率控制（个人开发者10次/分钟，企业开发者30次/分钟）
self.rate_limit = 10 # 默认个人开发者限制，企业可手动修改为30
self.call_timestamps = [] # 存储调用时间戳（秒级）
def set_rate_limit(self, limit: int) -> None:
"""设置调用频率限制（次/分钟）"""
if 10 <= limit <= 30:
self.rate_limit = limit
logging.info(f"已设置调用频率限制为 {limit} 次/分钟")
else:
logging.warning("频率限制必须在10-30之间，未修改")
def _generate_sign(self, params: Dict) -> str:
"""
生成签名（MD5算法）
:param params: 请求参数字典
:return: 签名字符串（大写）
"""
# 1. 按参数名ASCII升序排序
sorted_params = sorted(params.items(), key=lambda x: x[0])
# 2. 拼接为"key=value&key=value"格式
param_str = "&".join([f"{k}={v}" for k, v in sorted_params])
# 3. 追加app_secret
sign_str = f"{param_str}&app_secret={self.app_secret}"
# 4. MD5加密并转为大写
return hashlib.md5(sign_str.encode("utf-8")).hexdigest().upper()
def _check_rate_limit(self) -> None:
"""检查并控制调用频率"""
current_time = time.time()
# 保留1分钟内的调用记录
self.call_timestamps = [t for t in self.call_timestamps if current_time - t < 60]
# 若超过限制，计算需要等待的时间
if len(self.call_timestamps) >= self.rate_limit:
oldest_time = self.call_timestamps[0]
sleep_time = 60 - (current_time - oldest_time) + 1 # 额外加1秒保险
logging.warning(f"调用频率超限，等待 {sleep_time:.1f} 秒")
time.sleep(sleep_time)
# 再次清理过期记录
self.call_timestamps = [t for t in self.call_timestamps if time.time() - t < 60]
# 记录本次调用时间
self.call_timestamps.append(current_time)
def call_seller_search(self, rank_type: str, period: str, page: int = 1,
page_size: int = 50, filters: Optional[Dict] = None) -> Optional[Dict]:
"""
调用 seller_search 接口
:param rank_type: 排行榜类型（product_sale/seller_sale）
:param period: 统计周期（day/week/month）
:param page: 页码
:param page_size: 每页数量
:param filters: 筛选参数（如category_id、city等）
:return: 接口返回结果，失败返回None
"""
# 1. 构建基础参数
base_params = {
"app_key": self.app_key,
"timestamp": int(time.time()), # 秒级时间戳
"rank_type": rank_type,
"period": period,
"page": page,
"page_size": page_size
}
# 2. 合并筛选参数
if filters and isinstance(filters, Dict):
# 过滤空值参数
valid_filters = {k: v for k, v in filters.items() if v is not None}
base_params.update(valid_filters)
# 3. 生成签名
base_params["sign"] = self._generate_sign(base_params)
# 4. 频率控制
self._check_rate_limit()
try:
# 5. 发送请求
response = self.session.get(self.gateway_url, params=base_params, timeout=15)
response.raise_for_status() # 抛出HTTP错误
# 6. 解析响应
result = response.json()
# 7. 处理状态码
if result.get("code") != 0:
logging.error(f"接口调用失败：code={result.get('code')}, message={result.get('message')}")
return None
logging.info(f"成功获取 {rank_type}（{period}）第 {page} 页数据，共 {result.get('total', 0)} 条")
return result
except requests.exceptions.RequestException as e:
logging.error(f"请求异常：{str(e)}")
return None
except json.JSONDecodeError:
logging.error(f"响应解析失败：{response.text[:200]}...")
return None
def batch_get_rank_data(self, rank_type: str, period: str, max_pages: int = 5,
page_size: int = 50, filters: Optional[Dict] = None) -> Tuple[List[Dict], Dict]:
"""
批量获取多页排行榜数据
:param rank_type: 排行榜类型
:param period: 统计周期
:param max_pages: 最大获取页数（≤30）
:param page_size: 每页数量
:param filters: 筛选参数
:return: 排行榜数据列表和元信息（总条数、周期等）
"""
all_data = []
meta_info = {"total": 0, "rank_type": rank_type, "period": period, "filters": filters}
max_pages = min(max_pages, 30) # 限制最大页数为30
for page in range(1, max_pages + 1):
logging.info(f"正在获取第 {page}/{max_pages} 页数据...")
result = self.call_seller_search(rank_type, period, page, page_size, filters)
if not result or "data" not in result:
logging.warning(f"第 {page} 页无数据，停止批量获取")
break
# 提取数据并添加页码信息
page_data = result["data"]
for item in page_data:
item["page"] = page
item["crawl_time"] = datetime.now().strftime("%Y-%m-%d %H:%M:%S") # 抓取时间
all_data.extend(page_data)
# 保存元信息（第一页获取一次即可）
if page == 1:
meta_info["total"] = result.get("total", 0)
meta_info["update_time"] = result.get("update_time", "") # 数据更新时间
# 若当前页数据不足page_size，说明已无更多数据
if len(page_data) < page_size:
logging.info(f"第 {page} 页数据不足 {page_size} 条，停止批量获取")
break
logging.info(f"批量获取完成，共获取 {len(all_data)} 条 {rank_type}（{period}）数据")
return all_data, meta_info
def analyze_product_rank(self, product_data: List[Dict]) -> Dict:
"""分析商品排行榜数据"""
if not product_data:
return {"error": "无商品数据可分析"}
# 1. 价格分布分析
prices = [item.get("price", 0.0) for item in product_data if item.get("price") > 0]
price_stats = {}
if prices:
price_stats = {
"min": round(min(prices), 2),
"max": round(max(prices), 2),
"avg": round(sum(prices) / len(prices), 2),
"median": round(np.median(prices), 2)
}
# 2. 产地分布
city_counts = defaultdict(int)
for item in product_data:
city = item.get("city", "未知")
city_counts[city] += 1
# 3. 销量与增长率分析
sales = [item.get("sales", 0) for item in product_data]
growth_rates = [item.get("growth_rate", 0.0) for item in product_data if item.get("growth_rate") is not None]
# 4. 排名变化分析（上升/下降/不变）
rank_changes = defaultdict(int)
for item in product_data:
if "last_rank" in item and "rank" in item:
last_rank = item["last_rank"]
current_rank = item["rank"]
if last_rank > current_rank:
rank_changes["上升"] += 1
elif last_rank < current_rank:
rank_changes["下降"] += 1
else:
rank_changes["不变"] += 1
# 5. 热门标签分析
tag_counts = defaultdict(int)
for item in product_data:
for tag in item.get("tags", []):
tag_counts[tag] += 1
return {
"total_products": len(product_data),
"price_analysis": price_stats,
"city_distribution": dict(city_counts),
"sales_stats": {
"total_sales": sum(sales),
"avg_sales": round(sum(sales)/len(sales), 1) if sales else 0,
"top3_sales": sorted(sales, reverse=True)[:3]
},
"growth_analysis": {
"avg_growth": round(sum(growth_rates)/len(growth_rates), 1) if growth_rates else 0,
"high_growth_count": sum(1 for r in growth_rates if r >= 50) # 高增长率（≥50%）商品数
},
"rank_change": dict(rank_changes),
"top_tags": sorted(tag_counts.items(), key=lambda x: x[1], reverse=True)[:10]
}
def analyze_seller_rank(self, seller_data: List[Dict]) -> Dict:
"""分析商家排行榜数据"""
if not seller_data:
return {"error": "无商家数据可分析"}
# 1. 销售额分析
sales = [item.get("sales", 0.0) for item in seller_data if item.get("sales") > 0]
sales_stats = {}
if sales:
sales_stats = {
"total": round(sum(sales), 2),
"avg": round(sum(sales)/len(sales), 2),
"top3": sorted(sales, reverse=True)[:3]
}
# 2. 商家所在地分布
city_counts = defaultdict(int)
for item in seller_data:
city = item.get("city", "未知")
city_counts[city] += 1
# 3. 主营类目分布
category_counts = defaultdict(int)
for item in seller_data:
category = item.get("main_category", "未知")
category_counts[category] += 1
# 4. 服务质量分析（回复率、发货时间）
reply_rates = [item.get("reply_rate", 0.0) for item in seller_data]
ship_times = [item.get("ship_time", 0.0) for item in seller_data if item.get("ship_time") > 0]
return {
"total_sellers": len(seller_data),
"sales_analysis": sales_stats,
"city_distribution": dict(city_counts),
"category_distribution": dict(category_counts),
"service_analysis": {
"avg_reply_rate": round(sum(reply_rates)/len(reply_rates), 1) if reply_rates else 0,
"avg_ship_time": round(sum(ship_times)/len(ship_times), 1) if ship_times else 0
},
"product_count_stats": {
"avg_product_count": round(sum(item.get("product_count", 0) for item in seller_data)/len(seller_data), 1)
}
}
def visualize_analysis(self, analysis: Dict, title: str, output_dir: str = ".") -> None:
"""可视化分析结果"""
# 1. 价格分布直方图（商品分析专用）
if "price_analysis" in analysis and analysis["price_analysis"]:
plt.figure(figsize=(10, 6))
prices = [item.get("price", 0.0) for item in analysis.get("raw_data", []) if item.get("price") > 0]
plt.hist(prices, bins=10, alpha=0.7, color='lightgreen')
plt.axvline(analysis["price_analysis"]["avg"], color='red', linestyle='--',
label=f'平均价格: {analysis["price_analysis"]["avg"]}元')
plt.title(f'{title} - 商品价格分布')
plt.xlabel('价格（元）')
plt.ylabel('商品数量')
plt.legend()
plt.tight_layout()
plt.savefig(f"{output_dir}/price_distribution.png")
plt.close()
logging.info(f"价格分布图表已保存至 {output_dir}/price_distribution.png")
# 2. 产地分布饼图
if "city_distribution" in analysis and analysis["city_distribution"]:
plt.figure(figsize=(8, 8))
# 只显示占比前5的产地，其余归为"其他"
city_data = sorted(analysis["city_distribution"].items(), key=lambda x: x[1], reverse=True)
if len(city_data) > 5:
top5 = city_data[:5]
others = sum(count for _, count in city_data[5:])
top5.append(("其他", others))
city_data = top5
labels, sizes = zip(*city_data)
plt.pie(sizes, labels=labels, autopct='%1.1f%%', startangle=90)
plt.title(f'{title} - 产地分布')
plt.axis('equal')
plt.tight_layout()
plt.savefig(f"{output_dir}/city_distribution.png")
plt.close()
logging.info(f"产地分布图表已保存至 {output_dir}/city_distribution.png")
# 3. 销量TOP10商品条形图（商品分析专用）
if "sales_stats" in analysis and "raw_data" in analysis:
# 提取销量TOP10的商品名称和销量
top10_sales = sorted(
analysis["raw_data"],
key=lambda x: x.get("sales", 0),
reverse=True
)[:10]
plt.figure(figsize=(12, 6))
names = [item["title"][:10] + "..." for item in top10_sales] # 截断长标题
sales = [item.get("sales", 0) for item in top10_sales]
plt.barh(names, sales, color='skyblue')
plt.xlabel('销量（件）')
plt.title(f'{title} - 销量TOP10商品')
plt.gca().invert_yaxis() # 反转Y轴，让第一名在最上方
plt.tight_layout()
plt.savefig(f"{output_dir}/top10_sales.png")
plt.close()
logging.info(f"销量TOP10图表已保存至 {output_dir}/top10_sales.png")
def export_to_excel(self, data: List[Dict], meta_info: Dict, filename: str) -> None:
"""导出数据到Excel"""
if not data:
logging.warning("无数据可导出")
return
try:
with pd.ExcelWriter(filename) as writer:
# 数据详情页
df_data = pd.DataFrame(data)
df_data.to_excel(writer, sheet_name='数据详情', index=False)
# 元信息页
df_meta = pd.DataFrame(list(meta_info.items()), columns=['参数', '值'])
df_meta.to_excel(writer, sheet_name='元信息', index=False)
logging.info(f"数据已导出至 {filename}")
except Exception as e:
logging.error(f"导出Excel失败: {str(e)}")
示例调用
if name == "main":
# 替换为实际参数（从VVIC开放平台获取）
# 初始化客户端
vvic_api = VVICSellerSearch(APP_KEY, APP_SECRET)
# 若为企业开发者，设置更高的频率限制
# vvic_api.set_rate_limit(30)
# 示例1：获取女装商品日销量排行榜
print("=== 女装商品日销量排行榜分析 ===")
product_filters = {
"category_id": 1001, # 1001=女装
"city": "广州", # 筛选广州产地
"price_min": 50, # 最低价格50元
"price_max": 200 # 最高价格200元
}
# 获取前3页数据（每页50条）
product_data, product_meta = vvic_api.batch_get_rank_data(
rank_type="product_sale",
period="day",
max_pages=3,
page_size=50,
filters=product_filters
)
# 分析商品数据
if product_data:
# 保存原始数据用于可视化
product_analysis = vvic_api.analyze_product_rank(product_data)
product_analysis["raw_data"] = product_data # 临时存储原始数据用于绘图
print(f"分析商品总数: {product_analysis['total_products']}")
print(f"价格范围: {product_analysis['price_analysis']['min']}-{product_analysis['price_analysis']['max']}元")
print(f"平均价格: {product_analysis['price_analysis']['avg']}元")
print(f"总销量: {product_analysis['sales_stats']['total_sales']}件")
print(f"平均增长率: {product_analysis['growth_analysis']['avg_growth']}%")
print("主要产地:")
for city, count in sorted(product_analysis["city_distribution"].items(), key=lambda x: x[1], reverse=True)[:3]:
print(f" {city}: {count}件商品")
# 可视化分析结果
vvic_api.visualize_analysis(
product_analysis,
title="广州女装日销排行榜分析",
output_dir="."
)
# 导出数据到Excel
vvic_api.export_to_excel(product_data, product_meta, "女装商品排行榜数据.xlsx")
# 示例2：获取男装商家周销量排行榜
print("\n=== 男装商家周销量排行榜分析 ===")
seller_filters = {
"category_id": 1002, # 1002=男装
"is_factory": 1 # 仅工厂直供商家
}
# 获取前2页数据
seller_data, seller_meta = vvic_api.batch_get_rank_data(
rank_type="seller_sale",
period="week",
max_pages=2,
page_size=50,
filters=seller_filters
)
# 分析商家数据
if seller_data:
seller_analysis = vvic_api.analyze_seller_rank(seller_data)
print(f"分析商家总数: {seller_analysis['total_sellers']}")
print(f"总销售额: {seller_analysis['sales_analysis']['total']}元")
print(f"平均在售商品数: {seller_analysis['product_count_stats']['avg_product_count']}")
print(f"平均回复率: {seller_analysis['service_analysis']['avg_reply_rate']}%")
print(f"平均发货时间: {seller_analysis['service_analysis']['avg_ship_time']}小时")
# 导出数据到Excel
vvic_api.export_to_excel(seller_data, seller_meta, "男装商家排行榜数据.xlsx")
四、接口调用注意事项
- 常见错误及解决方案
错误码 说明 解决方案
400 参数错误 检查参数格式（如 page 需为正整数，period 必须是 day/week/month）
401 签名错误 重新生成签名，确保参数排序正确、app_secret 无误、timestamp 在有效期内
403 权限不足 检查是否已申请 “排行榜数据” 权限，敏感字段需单独申请
429 调用频率超限 减少调用次数，或升级为企业开发者提高限额
500 服务器错误 重试请求（建议间隔 3-5 秒），最多重试 3 次
1001 类目 ID 无效 参考 VVIC 开放平台的类目 ID 对照表，使用正确的 category_id - 性能优化建议
批量获取策略：优先使用较大的 page_size（如 50）减少请求次数，降低触发频率限制的风险
数据缓存：排行榜数据每 2 小时更新一次，建议缓存结果，避免重复调用
增量更新：通过对比上次抓取的 rank 值，仅获取排名变化的商品 / 商家数据
筛选优化：合理使用 category_id、city 等筛选参数，减少返回数据量
错峰调用：避开平台数据更新高峰期（通常为凌晨 2-4 点），提高接口响应速度
五、应用场景与扩展建议
典型应用场景
货源选品：通过商品销量榜识别批发市场爆款，指导采购决策
供应商评估：基于商家销量榜和服务指标（回复率、发货时间）选择优质供应商
市场趋势预测：分析周榜 / 月榜的增长率变化，预测季节性商品趋势
区域货源对比：通过 city 参数对比不同产地的商品价格和销量，优化采购区域
竞品监控：跟踪特定类目下的商家排名变化，分析竞争对手动态
扩展建议
趋势追踪系统：定时抓取排行榜数据，构建商品 / 商家的历史排名数据库，分析长期趋势
智能选品模型：结合价格、销量、增长率、产地等多维度数据，建立选品评分模型
供应链预警：监控合作商家的排名变化，当排名持续下降时触发预警
多平台对比：整合 VVIC 与其他服装批发平台（如 1688、衣联网）的排行榜数据，全面分析市场
可视化看板：开发实时数据看板，直观展示类目趋势、热销商品、优质商家等关键指标
通过 seller_search 接口获取的排行榜数据，能够帮助服装行业从业者快速把握批发市场动态，降低选品风险，优化供应链效率。在实际应用中，需注意合规使用数据，遵守平台的调用规范和数据使用协议，同时结合业务场景持续优化分析模型，提升决策价值。
