1688 item_search_best 接口深度分析及 Python 实现

1688 平台的 item_search_best 接口是获取各类榜单数据的核心接口，能够返回平台上不同类目、不同维度的热销商品榜单信息。对于商家选品、市场趋势分析、竞品监控等场景具有重要价值，尤其是在 B2B 电商环境中，能帮助企业把握市场动态和采购趋势。

一、接口核心特性分析

1. 接口功能与定位

• 核心功能：获取 1688 平台各类榜单数据，包括热销榜、飙升榜、新品榜等

• 数据特点：

  • 包含榜单排名、商品基础信息、价格、销量等核心数据
  • 提供多维度榜单分类，支持不同行业、不同类目筛选
  • 反映市场实时动态，数据具有较强的时效性
  • 包含 B2B 特有的批发数据和供应商信息

• 应用场景：

  • 市场趋势分析与预测
  • 爆款商品识别与选品决策
  • 竞品监控与市场策略调整
  • 供应链优化与采购计划制定
  • 行业动态追踪与商机发现

2. 认证机制

1688 开放平台的 item_search_best 接口采用标准认证方式：

• 基于 appkey + appsecret 的身份验证
• 需要通过 access_token 进行授权访问
• 接口调用需在请求中包含签名信息确保安全性
• 部分高级榜单数据需要额外申请权限

3. 核心参数与响应结构

请求参数

响应核心字段

• 榜单元信息：榜单类型、时间周期、类目、更新时间

• 分页信息：总商品数、总页数、当前页码

• 商品列表：每个商品包含

  • 基础信息：商品 ID、名称、图片、链接
  • 排名信息：当前排名、排名变化
  • 价格信息：批发价、起订量、价格区间
  • 销售数据：30 天销量、销售额、增长率
  • 供应商信息：供应商 ID、名称、信用等级
  • 榜单指标：上榜理由、热度值

二、Python 脚本实现

以下是调用 1688 item_search_best 接口的完整 Python 实现，包含认证、请求、数据解析和深度分析功能： import requests import time import json import logging import re import os from typing import Dict, Optional, List, Tuple from requests.exceptions import RequestException import matplotlib.pyplot as plt import numpy as np from collections import defaultdict

配置日志

logging.basicConfig( level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s" )

class Alibaba1688BestSearchAPI: def init(self, appkey: str, appsecret: str): """ 初始化1688榜单接口客户端 :param appkey: 1688开放平台appkey :param appsecret: 1688开放平台appsecret """ self.appkey = appkey self.appsecret = appsecret self.base_url = "gw.open.1688.com/openapi/gat…" self.session = requests.Session() self.access_token = None self.token_expires_at = 0 # token过期时间戳 self.session.headers.update({ "Content-Type": "application/x-www-form-urlencoded", "User-Agent": "AlibabaApp/10.1.0 (Android; 11; Scale/2.00)" })

def _get_access_token(self) -> Optional[str]:
    """获取访问令牌"""
    # 检查token是否有效
    if self.access_token and self.token_expires_at > time.time() + 60:
        return self.access_token
        
    logging.info("获取新的access_token")
    params = {
        "method": "alibaba.oauth2.getToken",
        "client_id": self.appkey,
        "client_secret": self.appsecret,
        "grant_type": "client_credentials",
        "format": "json"
    }
    
    try:
        response = self.session.get(self.base_url, params=params, timeout=10)
        response.raise_for_status()
        result = response.json()
        
        if "error_response" in result:
            logging.error(f"获取access_token失败: {result['error_response']['msg']} (错误码: {result['error_response']['code']})")
            return None
            
        self.access_token = result["access_token"]
        self.token_expires_at = time.time() + result.get("expires_in", 86400)  # 默认为24小时
        return self.access_token
            
    except RequestException as e:
        logging.error(f"获取access_token请求异常: {str(e)}")
        return None

def search_best_items(self, 
                     rank_type: str = "best", 
                     cat: Optional[str] = None,
                     period: str = "day",
                     page: int = 1,
                     page_size: int = 20,
                     industry: Optional[str] = None) -> Optional[Dict]:
    """
    获取榜单商品数据
    :param rank_type: 榜单类型：best（热销榜）、rise（飙升榜）、new（新品榜）
    :param cat: 类目ID
    :param period: 时间周期：day（日榜）、week（周榜）、month（月榜）
    :param page: 页码
    :param page_size: 每页条数
    :param industry: 行业ID
    :return: 榜单数据
    """
    # 验证参数
    valid_rank_types = ["best", "rise", "new"]
    if rank_type not in valid_rank_types:
        logging.error(f"无效的榜单类型: {rank_type}，支持: {valid_rank_types}")
        return None
        
    valid_periods = ["day", "week", "month"]
    if period not in valid_periods:
        logging.error(f"无效的时间周期: {period}，支持: {valid_periods}")
        return None
        
    if page_size < 1 or page_size > 50:
        logging.error(f"每页条数必须在1-50之间，当前为: {page_size}")
        return None
        
    # 获取有效的access_token
    if not self._get_access_token():
        return None
        
    # 构建参数
    timestamp = int(time.time())
    params = {
        "method": "alibaba.item.search.best",
        "client_id": self.appkey,
        "access_token": self.access_token,
        "timestamp": timestamp,
        "format": "json",
        "v": "1.0",
        "rank_type": rank_type,
        "period": period,
        "page": page,
        "page_size": page_size
    }
    
    # 添加可选参数
    if cat:
        params["cat"] = cat
    if industry:
        params["industry"] = industry
        
    try:
        response = self.session.get(self.base_url, params=params, timeout=15)
        response.raise_for_status()
        result = response.json()
        
        if "error_response" in result:
            logging.error(f"获取榜单数据失败: {result['error_response']['msg']} (错误码: {result['error_response']['code']})")
            return None
            
        best_response = result.get("alibaba_item_search_best_response", {})
        best_data = best_response.get("result", {})
        
        if not best_data:
            logging.warning("未获取到榜单数据")
            return None
            
        # 格式化榜单数据
        return self._format_best_data(best_data, rank_type, period, cat, industry)
        
    except RequestException as e:
        logging.error(f"获取榜单数据请求异常: {str(e)}")
        return None
    except json.JSONDecodeError:
        logging.error(f"榜单数据响应解析失败: {response.text[:200]}...")
        return None

def _format_best_data(self, best_data: Dict, rank_type: str, period: str, cat: Optional[str], industry: Optional[str]) -> Dict:
    """格式化榜单数据"""
    # 榜单元信息
    rank_info = {
        "rank_type": rank_type,
        "rank_type_name": self._get_rank_type_name(rank_type),
        "period": period,
        "period_name": self._get_period_name(period),
        "category_id": cat,
        "category_name": best_data.get("category_name", ""),
        "industry_id": industry,
        "industry_name": best_data.get("industry_name", ""),
        "update_time": best_data.get("update_time", time.strftime("%Y-%m-%d %H:%M:%S"))
    }
    
    # 分页信息
    pagination = {
        "total_items": int(best_data.get("total_results", 0)),
        "total_pages": (int(best_data.get("total_results", 0)) + int(best_data.get("page_size", 20)) - 1) // int(best_data.get("page_size", 20)),
        "current_page": int(best_data.get("page", 1)),
        "page_size": int(best_data.get("page_size", 20))
    }
    
    # 格式化商品列表
    items = []
    for item in best_data.get("items", []):
        # 处理排名变化
        rank_change = item.get("rank_change", 0)
        rank_change_type = "up" if rank_change > 0 else "down" if rank_change < 0 else "same"
        
        # 处理价格信息
        price_info = self._parse_price_info(item)
        
        # 处理供应商信息
        supplier_info = {
            "supplier_id": item.get("supplier_id"),
            "supplier_name": item.get("supplier_name"),
            "credit_level": item.get("credit_level"),
            "years": int(item.get("operating_years", 0)),
            "is_gold_supplier": item.get("is_gold_supplier", False)
        }
        
        items.append({
            "rank": int(item.get("rank", 0)),
            "rank_change": rank_change,
            "rank_change_type": rank_change_type,
            "item_id": item.get("offer_id"),
            "title": item.get("title"),
            "image_url": item.get("image_url"),
            "detail_url": item.get("detail_url"),
            "price_info": price_info,
            "sales_info": {
                "sales_30d": int(item.get("sales_count_30d", 0)),
                "turnover_30d": float(item.get("turnover_30d", 0)),
                "growth_rate": float(item.get("growth_rate", 0)) if item.get("growth_rate") else 0
            },
            "supplier_info": supplier_info,
            "category": {
                "cid": item.get("category_id"),
                "name": item.get("category_name")
            },
            "tags": item.get("tags", "").split(",") if item.get("tags") else [],
            "hot_score": int(item.get("hot_score", 0)),
            "reason": item.get("reason", "")  # 上榜理由
        })
    
    return {
        "rank_info": rank_info,
        "pagination": pagination,
        "items": items,
        "raw_data": best_data  # 保留原始数据
    }

def _get_rank_type_name(self, rank_type: str) -> str:
    """转换榜单类型为中文名称"""
    rank_type_map = {
        "best": "热销榜",
        "rise": "飙升榜",
        "new": "新品榜"
    }
    return rank_type_map.get(rank_type, rank_type)

def _get_period_name(self, period: str) -> str:
    """转换时间周期为中文名称"""
    period_map = {
        "day": "日榜",
        "week": "周榜",
        "month": "月榜"
    }
    return period_map.get(period, period)

def _parse_price_info(self, item: Dict) -> Dict:
    """解析价格信息"""
    # 处理批发价格区间
    wholesale_prices = []
    if item.get("wholesale_price_list"):
        for price in item["wholesale_price_list"]:
            wholesale_prices.append({
                "min_quantity": int(price.get("min_quantity", 0)),
                "price": float(price.get("price", 0))
            })
    
    return {
        "min_price": float(item.get("min_price", 0)),
        "max_price": float(item.get("max_price", 0)),
        "price_unit": item.get("price_unit", "个"),
        "wholesale_prices": wholesale_prices,
        "mix_batch": item.get("support_mix_batch", False)
    }

def get_full_rank_list(self, rank_type: str = "best", max_pages: int = 5, **kwargs) -> Dict:
    """
    获取完整的榜单数据
    :param rank_type: 榜单类型
    :param max_pages: 最大页数限制
    :return: 完整的榜单数据
    """
    all_items = []
    page = 1
    rank_info = None
    
    while page <= max_pages:
        logging.info(f"获取榜单第 {page} 页数据")
        result = self.search_best_items(
            rank_type=rank_type,
            page=page,** kwargs
        )
        
        if not result or not result["items"]:
            break
            
        # 保存榜单元信息
        if not rank_info:
            rank_info = result["rank_info"]
            
        all_items.extend(result["items"])
        
        # 检查是否已到最后一页
        if page >= result["pagination"]["total_pages"]:
            break
            
        page += 1
        # 控制请求频率
        time.sleep(2)
        
    logging.info(f"共获取到 {len(all_items)} 条榜单数据")
    
    return {
        "rank_info": rank_info,
        "total_items": len(all_items),
        "items": all_items
    }

def analyze_rank_data(self, rank_data: Dict) -> Dict:
    """分析榜单数据"""
    if not rank_data or not rank_data["items"]:
        return {}
        
    items = rank_data["items"]
    total = len(items)
    
    # 价格分析
    price_analysis = self._analyze_prices(items)
    
    # 类目分布分析
    category_analysis = self._analyze_categories(items)
    
    # 供应商分析
    supplier_analysis = self._analyze_suppliers(items)
    
    # 销售增长分析（针对飙升榜）
    growth_analysis = {}
    if rank_data["rank_info"]["rank_type"] == "rise":
        growth_analysis = self._analyze_growth(items)
    
    # 排名变化分析
    rank_change_analysis = self._analyze_rank_changes(items)
    
    # 提取表现突出的商品
    top_performers = self._get_top_performers(items, rank_data["rank_info"]["rank_type"])
    
    return {
        "summary": {
            "rank_type": rank_data["rank_info"]["rank_type_name"],
            "period": rank_data["rank_info"]["period_name"],
            "category": rank_data["rank_info"]["category_name"] or "全类目",
            "total_items": total,
            "update_time": rank_data["rank_info"]["update_time"]
        },
        "price_analysis": price_analysis,
        "category_analysis": category_analysis,
        "supplier_analysis": supplier_analysis,
        "growth_analysis": growth_analysis,
        "rank_change_analysis": rank_change_analysis,
        "top_performers": top_performers
    }

def _analyze_prices(self, items: List[Dict]) -> Dict:
    """分析价格分布"""
    prices = [item["price_info"]["min_price"] for item in items if item["price_info"]["min_price"] > 0]
    if not prices:
        return {}
        
    min_price = min(prices)
    max_price = max(prices)
    avg_price = round(sum(prices) / len(prices), 2)
    
    # 价格区间分布
    price_ranges = self._get_price_ranges(min_price, max_price)
    range_counts = defaultdict(int)
    for price in prices:
        for r in price_ranges:
            if r[0] <= price < r[1]:
                range_counts[f"{r[0]}-{r[1]}"] += 1
                break
        else:
            range_counts[f"{price_ranges[-1][1]}+"] += 1
    
    # 起订量分析
    min_order_quantities = []
    for item in items:
        if item["price_info"]["wholesale_prices"]:
            min_order_quantities.append(item["price_info"]["wholesale_prices"][0]["min_quantity"])
    
    order_analysis = {}
    if min_order_quantities:
        order_analysis = {
            "min": min(min_order_quantities),
            "max": max(min_order_quantities),
            "avg": round(sum(min_order_quantities) / len(min_order_quantities), 1),
            "distribution": self._analyze_order_quantities(min_order_quantities)
        }
    
    return {
        "min_price": min_price,
        "max_price": max_price,
        "avg_price": avg_price,
        "median_price": self._calculate_median(prices),
        "range_distribution": dict(range_counts),
        "order_quantity": order_analysis,
        "mix_batch_ratio": round(sum(1 for item in items if item["price_info"]["mix_batch"]) / len(items) * 100, 1)
    }

def _analyze_categories(self, items: List[Dict]) -> Dict:
    """分析类目分布"""
    category_counts = defaultdict(int)
    category_sales = defaultdict(int)
    
    for item in items:
        cat_name = item["category"]["name"] or "未分类"
        category_counts[cat_name] += 1
        category_sales[cat_name] += item["sales_info"]["sales_30d"]
    
    # 按商品数量排序
    sorted_categories = sorted(category_counts.items(), key=lambda x: x[1], reverse=True)
    
    return {
        "total_categories": len(category_counts),
        "distribution": dict(category_counts),
        "sales_by_category": dict(category_sales),
        "top_categories": sorted_categories[:5]
    }

def _analyze_suppliers(self, items: List[Dict]) -> Dict:
    """分析供应商特征"""
    supplier_counts = defaultdict(int)
    gold_supplier_count = 0
    years_operating = []
    
    for item in items:
        supplier_id = item["supplier_info"]["supplier_id"]
        supplier_counts[supplier_id] += 1
        
        if item["supplier_info"]["is_gold_supplier"]:
            gold_supplier_count += 1
            
        if item["supplier_info"]["years"] > 0:
            years_operating.append(item["supplier_info"]["years"])
    
    # 计算平均经营年限
    avg_years = round(sum(years_operating) / len(years_operating), 1) if years_operating else 0
    
    # 多上榜商品的供应商
    multi_item_suppliers = [(k, v) for k, v in supplier_counts.items() if v > 1]
    multi_item_suppliers.sort(key=lambda x: x[1], reverse=True)
    
    # 提取供应商名称
    supplier_names = {item["supplier_info"]["supplier_id"]: item["supplier_info"]["supplier_name"] for item in items}
    top_suppliers = []
    for sid, count in multi_item_suppliers[:5]:
        top_suppliers.append((supplier_names.get(sid, "未知供应商"), count))
    
    return {
        "total_suppliers": len(supplier_counts),
        "gold_supplier_ratio": round(gold_supplier_count / len(items) * 100, 1),
        "avg_operating_years": avg_years,
        "multi_item_suppliers_count": len(multi_item_suppliers),
        "top_suppliers": top_suppliers
    }

def _analyze_growth(self, items: List[Dict]) -> Dict:
    """分析销售增长情况（针对飙升榜）"""
    growth_rates = [item["sales_info"]["growth_rate"] for item in items if item["sales_info"]["growth_rate"] is not None]
    if not growth_rates:
        return {}
        
    avg_growth = round(sum(growth_rates) / len(growth_rates), 2)
    max_growth = max(growth_rates)
    min_growth = min(growth_rates)
    
    # 增长率分布
    growth_ranges = [(-float('inf'), 50), (50, 100), (100, 200), (200, 500), (500, float('inf'))]
    growth_distribution = defaultdict(int)
    for rate in growth_rates:
        for r in growth_ranges:
            if r[0] < rate <= r[1]:
                growth_distribution[f"{r[0] if r[0] != -float('inf') else ''}-{r[1] if r[1] != float('inf') else '+'}%"] += 1
                break
    
    # 增长率与价格相关性
    price_growth_correlation = self._calculate_correlation(
        [item["price_info"]["min_price"] for item in items],
        [item["sales_info"]["growth_rate"] for item in items]
    )
    
    return {
        "avg_growth_rate": avg_growth,
        "max_growth_rate": max_growth,
        "min_growth_rate": min_growth,
        "distribution": dict(growth_distribution),
        "price_correlation": round(price_growth_correlation, 4)
    }

def _analyze_rank_changes(self, items: List[Dict]) -> Dict:
    """分析排名变化"""
    up_count = sum(1 for item in items if item["rank_change_type"] == "up")
    down_count = sum(1 for item in items if item["rank_change_type"] == "down")
    same_count = sum(1 for item in items if item["rank_change_type"] == "same")
    
    # 排名变化幅度分析
    up_changes = [abs(item["rank_change"]) for item in items if item["rank_change_type"] == "up"]
    down_changes = [abs(item["rank_change"]) for item in items if item["rank_change_type"] == "down"]
    
    return {
        "up_ratio": round(up_count / len(items) * 100, 1),
        "down_ratio": round(down_count / len(items) * 100, 1),
        "same_ratio": round(same_count / len(items) * 100, 1),
        "avg_up_change": round(sum(up_changes) / len(up_changes), 1) if up_changes else 0,
        "avg_down_change": round(sum(down_changes) / len(down_changes), 1) if down_changes else 0
    }

def _get_top_performers(self, items: List[Dict], rank_type: str) -> List[Dict]:
    """获取表现突出的商品"""
    if rank_type == "best":
        # 热销榜按销量排序
        return sorted(items, key=lambda x: x["sales_info"]["sales_30d"], reverse=True)[:10]
    elif rank_type == "rise":
        # 飙升榜按增长率排序
        return sorted(items, key=lambda x: x["sales_info"]["growth_rate"], reverse=True)[:10]
    else:  # new
        # 新品榜按热度排序
        return sorted(items, key=lambda x: x["hot_score"], reverse=True)[:10]

# 工具方法
def _get_price_ranges(self, min_price: float, max_price: float) -> List[Tuple[float, float]]:
    """生成合理的价格区间"""
    if min_price >= max_price:
        return [(min_price - 1, max_price + 1)]
        
    # 计算区间数量，最多8个区间
    range_count = min(8, int(max_price - min_price) // 10 + 1)
    step = (max_price - min_price) / range_count
    
    ranges = []
    for i in range(range_count):
        start = min_price + i * step
        end = min_price + (i + 1) * step
        ranges.append((round(start, 1), round(end, 1)))
        
    return ranges

def _calculate_median(self, data: List[float]) -> float:
    """计算中位数"""
    sorted_data = sorted(data)
    n = len(sorted_data)
    if n % 2 == 1:
        return round(sorted_data[n//2], 2)
    else:
        return round((sorted_data[n//2 - 1] + sorted_data[n//2]) / 2, 2)

def _analyze_order_quantities(self, quantities: List[int]) -> Dict:
    """分析起订量分布"""
    ranges = [(1, 5), (6, 20), (21, 100), (101, 500), (501, float('inf'))]
    distribution = defaultdict(int)
    
    for qty in quantities:
        for r in ranges:
            if r[0] <= qty <= r[1]:
                distribution[f"{r[0]}-{r[1] if r[1] != float('inf') else '+'}"] += 1
                break
    
    return dict(distribution)

def _calculate_correlation(self, x: List[float], y: List[float]) -> float:
    """计算皮尔逊相关系数"""
    if len(x) != len(y) or len(x) < 2:
        return 0.0
        
    n = len(x)
    sum_x = sum(x)
    sum_y = sum(y)
    sum_xy = sum(xi * yi for xi, yi in zip(x, y))
    sum_x2 = sum(xi **2 for xi in x)
    sum_y2 = sum(yi** 2 for yi in y)
    
    numerator = n * sum_xy - sum_x * sum_y
    denominator = ((n * sum_x2 - sum_x **2) * (n * sum_y2 - sum_y** 2)) **0.5
    
    return numerator / denominator if denominator != 0 else 0.0

def visualize_analysis(self, analysis: Dict, output_dir: str = "rank_analysis") -> None:
    """可视化分析结果"""
    # 创建输出目录
    if not os.path.exists(output_dir):
        os.makedirs(output_dir)
        
    # 设置中文显示
    plt.rcParams["font.family"] = ["SimHei", "WenQuanYi Micro Hei", "Heiti TC"]
    plt.rcParams["axes.unicode_minus"] = False
    
    # 1. 价格分布直方图
    plt.figure(figsize=(10, 6))
    if analysis["price_analysis"]["range_distribution"]:
        ranges = list(analysis["price_analysis"]["range_distribution"].keys())
        counts = list(analysis["price_analysis"]["range_distribution"].values())
        plt.bar(ranges, counts, color='skyblue')
        plt.title(f"商品价格区间分布 (平均价格: {analysis['price_analysis']['avg_price']}元)")
        plt.xlabel("价格区间 (元)")
        plt.ylabel("商品数量")
        plt.xticks(rotation=45)
        plt.tight_layout()
        plt.savefig(f"{output_dir}/price_distribution.png")
        plt.close()
    
    # 2. 类目分布饼图
    plt.figure(figsize=(10, 6))
    top_cats = analysis["category_analysis"]["top_categories"]
    if top_cats:
        labels = [cat[0] for cat in top_cats]
        sizes = [cat[1] for cat in top_cats]
        # 其他分类合并
        if len(analysis["category_analysis"]["distribution"]) > 5:
            other_count = sum(analysis["category_analysis"]["distribution"].values()) - sum(sizes)
            labels.append("其他")
            sizes.append(other_count)
        plt.pie(sizes, labels=labels, autopct='%1.1f%%', startangle=90)
        plt.title("商品类目分布")
        plt.axis('equal')
        plt.tight_layout()
        plt.savefig(f"{output_dir}/category_distribution.png")
        plt.close()
    
    # 3. 排名变化分析饼图
    plt.figure(figsize=(8, 8))
    change_labels = ['排名上升', '排名下降', '排名不变']
    change_sizes = [
        analysis["rank_change_analysis"]["up_ratio"],
        analysis["rank_change_analysis"]["down_ratio"],
        analysis["rank_change_analysis"]["same_ratio"]
    ]
    plt.pie(change_sizes, labels=change_labels, autopct='%1.1f%%', 
            startangle=90, colors=['#4CAF50', '#F44336', '#9E9E9E'])
    plt.title("排名变化分布")
    plt.axis('equal')
    plt.tight_layout()
    plt.savefig(f"{output_dir}/rank_change_distribution.png")
    plt.close()
    
    # 4. 供应商类型分布
    plt.figure(figsize=(8, 6))
    supplier_labels = ['金牌供应商', '普通供应商']
    supplier_sizes = [
        analysis["supplier_analysis"]["gold_supplier_ratio"],
        100 - analysis["supplier_analysis"]["gold_supplier_ratio"]
    ]
    plt.bar(supplier_labels, supplier_sizes, color=['#FFC107', '#E0E0E0'])
    plt.title("供应商类型占比")
    plt.ylabel('占比 (%)')
    plt.ylim(0, 100)
    for i, v in enumerate(supplier_sizes):
        plt.text(i, v + 1, f'{v}%', ha='center')
    plt.tight_layout()
    plt.savefig(f"{output_dir}/supplier_type_ratio.png")
    plt.close()
    
    # 5. 增长率分布（仅针对飙升榜）
    if analysis["growth_analysis"]:
        plt.figure(figsize=(10, 6))
        growth_ranges = list(analysis["growth_analysis"]["distribution"].keys())
        growth_counts = list(analysis["growth_analysis"]["distribution"].values())
        plt.bar(growth_ranges, growth_counts, color='#FF5722')
        plt.title(f"销售增长率分布 (平均增长率: {analysis['growth_analysis']['avg_growth_rate']}%)")
        plt.xlabel("增长率区间")
        plt.ylabel("商品数量")
        plt.xticks(rotation=45)
        plt.tight_layout()
        plt.savefig(f"{output_dir}/growth_rate_distribution.png")
        plt.close()
    
    logging.info(f"分析图表已保存至 {output_dir} 目录")

示例调用

if name == "main": # 替换为实际的appkey和appsecret（从1688开放平台获取） APPKEY = "your_appkey" APPSECRET = "your_appsecret" # 可选：指定类目ID，为空则返回全类目 CATEGORY_ID = "" # 榜单类型：best（热销榜）、rise（飙升榜）、new（新品榜） RANK_TYPE = "best" # 时间周期：day（日榜）、week（周榜）、month（月榜） PERIOD = "week"

# 初始化API客户端
api = Alibaba1688BestSearchAPI(APPKEY, APPSECRET)

# 获取完整榜单数据
rank_data = api.get_full_rank_list(
    rank_type=RANK_TYPE,
    cat=CATEGORY_ID,
    period=PERIOD,
    max_pages=3  # 最多获取3页
)

if rank_data and rank_data["items"]:
    # 分析榜单数据
    analysis = api.analyze_rank_data(rank_data)
    
    print(f"=== 1688{analysis['summary']['rank_type']}分析报告 ===")
    print(f"榜单类型: {analysis['summary']['rank_type']} ({analysis['summary']['period']})")
    print(f"类目: {analysis['summary']['category']}")
    print(f"更新时间: {analysis['summary']['update_time']}")
    print(f"总商品数: {analysis['summary']['total_items']}件")
    
    # 价格分析
    print("n价格分析:")
    print(f"  价格范围: {analysis['price_analysis']['min_price']}-{analysis['price_analysis']['max_price']}元")
    print(f"  平均价格: {analysis['price_analysis']['avg_price']}元")
    print(f"  支持混批商品占比: {analysis['price_analysis']['mix_batch_ratio']}%")
    print(f"  平均起订量: {analysis['price_analysis']['order_quantity']['avg']}件" if analysis['price_analysis']['order_quantity'] else "")
    
    # 类目分析
    print("n类目分析:")
    print(f"  总类目数: {analysis['category_analysis']['total_categories']}个")
    print("  上榜商品最多的5个类目:")
    for i, (cat, count) in enumerate(analysis['category_analysis']['top_categories'][:5], 1):
        print(f"    {i}. {cat}: {count}件")
    
    # 供应商分析
    print("n供应商分析:")
    print(f"  总供应商数: {analysis['supplier_analysis']['total_suppliers']}家")
    print(f"  金牌供应商占比: {analysis['supplier_analysis']['gold_supplier_ratio']}%")
    print(f"  平均经营年限: {analysis['supplier_analysis']['avg_operating_years']}年")
    if analysis['supplier_analysis']['top_suppliers']:
        print("  上榜商品最多的供应商:")
        for i, (supplier, count) in enumerate(analysis['supplier_analysis']['top_suppliers'][:3], 1):
            print(f"    {i}. {supplier}: {count}件商品上榜")
    
    # 排名变化分析
    print("n排名变化分析:")
    print(f"  排名上升: {analysis['rank_change_analysis']['up_ratio']}%")
    print(f"  排名下降: {analysis['rank_change_analysis']['down_ratio']}%")
    print(f"  排名不变: {analysis['rank_change_analysis']['same_ratio']}%")
    
    # 飙升榜特有分析
    if analysis["growth_analysis"]:
        print("n增长分析:")
        print(f"  平均增长率: {analysis['growth_analysis']['avg_growth_rate']}%")
        print(f"  最高增长率: {analysis['growth_analysis']['max_growth_rate']}%")
    
    # 表现突出商品
    print("n表现突出的商品TOP3:")
    for i, item in enumerate(analysis['top_performers'][:3], 1):
        print(f"  {i}. {item['title'][:30]}...")
        print(f"     排名: {item['rank']} ({'上升' if item['rank_change_type'] == 'up' else '下降' if item['rank_change_type'] == 'down' else '不变'}{abs(item['rank_change']) if item['rank_change'] !=0 else ''})")
        print(f"     价格: {item['price_info']['min_price']}-{item['price_info']['max_price']}元")
        print(f"     30天销量: {item['sales_info']['sales_30d']}件")
        print(f"     供应商: {item['supplier_info']['supplier_name']}")
    
    # 生成可视化图表
    api.visualize_analysis(analysis)

三、接口调用注意事项

1. 调用限制与规范

• QPS 限制：1688 开放平台对榜单接口的 QPS 限制通常为 5 次 / 秒，批量获取时需控制频率
• 数据时效性：榜单数据具有较强时效性，日榜通常每 2 小时更新一次，周榜和月榜每日更新
• 权限差异：部分行业榜单和高级数据需要企业认证账号才能访问
• 缓存策略：建议根据榜单类型设置不同的缓存周期（日榜 2 小时，周榜 1 天）
• 调用频率：避免频繁获取相同榜单数据，建议按更新周期定时获取

2. 常见错误及解决方案

3. 数据解析要点

• 排名变化：注意区分排名变化的正负含义（正值通常表示排名上升）
• 价格体系：1688 的批发价格为区间价格，需正确解析不同起订量对应的价格
• 销量统计：30 天销量可能包含批发和零售数据，需根据业务场景区分使用
• 类目映射：类目 ID 和名称可能存在多级结构，需构建完整类目路径
• 增长率计算：不同榜单的增长率计算基准可能不同（日环比、周同比等）

四、应用场景与扩展建议

典型应用场景

• 市场趋势预测系统：基于榜单变化预测行业发展趋势和热门商品
• 智能选品工具：结合多维度榜单数据，为商家提供选品建议
• 竞品监控平台：追踪竞争对手商品在榜单中的表现和排名变化
• 采购决策系统：基于热销榜单优化采购计划和库存管理
• 行业分析报告：定期生成特定行业的榜单分析报告，发现市场机会

扩展建议

• 实现榜单趋势追踪：记录历史榜单数据，分析商品排名变化趋势
• 开发异常检测功能：识别榜单中的异常波动商品，及时发现市场变化
• 构建商品潜力预测模型：基于飙升榜数据预测未来可能成为爆款的商品
• 实现多维度对比分析：横向对比不同类目、不同时间段的榜单特征
• 开发定制化榜单：根据特定指标（如利润率、增长率）生成自定义榜单
• 构建供应链推荐系统：基于供应商在榜单中的表现推荐优质供应商

通过合理使用 1688 item_search_best 接口，开发者可以构建功能丰富的市场分析系统，深入了解 B2B 电商平台的商品趋势和市场动态，为商业决策提供数据支持。在实际应用中，需结合业务场景合理选择榜单类型和时间周期，并关注数据的时效性和变化趋势。