从 0 到 1”用 Python 调用 1688 关键词搜索 API 的完整解析

以下示例演示了“从 0 到 1”用 Python 调用 1688 关键词搜索 API 的完整思路。
示例基于 1688 官方开放平台接口（item_search），全部代码可一次性复制运行，只需把
AppKey / AppSecret / AccessToken 换成自己后台申请的即可。

一、接口速览

接口英文名	作用	调用方式	返回格式
item_search	关键词搜索商品列表	GET / POST	JSON

核心请求参数

q：关键词（必填）
page：页码，从 1 开始
page_size：每页条数（官方最大 50）
sort：排序，如 sale 销量、price 价格
sign：签名（算法见下文）

二、签名生成（官方 MD5 模式）

1688 要求所有私有参数必须拼接后做 MD5，否则直接 403。

import hashlib, urllib.parse

def generate_sign(params: dict, app_secret: str) -> str:
    """
    官方签名算法：AppSecret + 自然序拼接串 + AppSecret → MD5 → 大写
    """
    # 1) 自然序排序
    sorted_pairs = sorted(params.items(), key=lambda x: x[0])
    # 2) 拼接成 k1v1&k2v2
    query_str = urllib.parse.urlencode(sorted_pairs, safe=',')
    # 3) 前后加 Secret
    raw = f"{app_secret}{query_str}{app_secret}"
    # 4) MD5 大写
    return hashlib.md5(raw.encode()).hexdigest().upper()

三、单页搜索函数

import requests, time, json

# ===== 全局变量 =====
APP_KEY = "你的AppKey"
APP_SECRET = "你的AppSecret"
ACCESS_TOKEN = "你的AccessToken"     # OAuth2 获取，见官方文档
API_GATEWAY = "https://open.1688.com/api/param2/1/com.alibaba.product/search/"

def search_1688(keyword: str, page: int = 1, page_size: 50):
    """返回一页商品列表（list[dict]）"""
    params = {
        "access_token": ACCESS_TOKEN,
        "q": keyword,
        "page": page,
        "pageSize": page_size,
        "sort": "sale",          # 按销量排序
        "timestamp": int(time.time()),
    }
    params["sign"] = generate_sign(params, APP_SECRET)

    resp = requests.get(API_GATEWAY, params=params, timeout=15)
    resp.raise_for_status()
    data = resp.json()

    if data.get("error_code"):
        raise RuntimeError(f"API 错误：{data}")
    # 不同版本字段略有区别，这里取最常见路径
    return data["result"]["products"]   # list[dict]

四、批量 + 落盘：10 行代码抓 1000 条

import pandas as pd

KEYWORD = "连衣裙"
MAX_PAGE = 20          # 20×50=1000 条，按需调整

all_prods = []
for p in range(1, MAX_PAGE + 1):
    try:
        page_data = search_1688(KEYWORD, page=p)
        all_prods.extend(page_data)
        print(f"第 {p} 页 OK，累计 {len(all_prods)} 条")
    except Exception as e:
        print(f"第 {p} 页失败：{e}")
        break
    time.sleep(1.5)      # 友好限速

# 只保留常用字段
df = pd.DataFrame(all_prods)[
    ["productId", "subject", "price", "saleCount", "imageUrl", "detailUrl"]
]
df.to_csv(f"1688_{KEYWORD}.csv", index=False, encoding="utf-8-sig")
print("已保存 >>> 1688_连衣裙.csv")