孔夫子舊書網 API 實戰：古籍與二手書數據獲取及接口調用方案

孔夫子舊書網作為國內知名的古籍、二手書交易平臺，其商品數據對于圖書收藏、學術研究及二手書電商系統具有重要價值。本文將詳細介紹孔夫子平臺接口的調用方法，涵蓋認證機制、搜索參數配置、數據解析及反爬策略，并提供可直接使用的 Python 代碼實現，幫助開發者合規獲取古籍和二手書數據。

一、孔夫子平臺接口基礎信息

孔夫子舊書網提供的開放接口主要包括圖書搜索、商品詳情、店鋪信息等功能，其中/api/v1/books/search是獲取圖書列表的核心接口，特別適用于古籍、珍本、二手書的檢索。

接口特點：

采用 API Key 認證機制，部分接口需要商業合作授權
支持按書名、作者、出版社、年代、品相等級等多維度篩選
包含古籍特有的版本信息、刻印年代、裝幀形式等字段
提供賣家信譽、交易記錄等二手書交易關鍵數據

接口端點：https://api.kongfz.com/api/v1/books/search

二、認證機制與核心參數

1. 認證方式

孔夫子接口采用簡單直接的 API Key 認證：

在孔夫子開發者平臺注冊并申請應用，獲取 API Key
在所有請求的 Header 中攜帶X-API-Key參數
商業用戶可申請更高權限的 Secret Key 進行簽名認證

2. 核心搜索參數

keyword：搜索關鍵字（書名、作者、ISBN 等，必填）
category：圖書分類（古籍 / 二手書 / 期刊等，可選）
year_min/year_max：出版年代范圍（可選）
condition：品相等級（1-10 級，10 為全新，可選）
price_min/price_max：價格區間（可選）
publisher：出版社（可選）
sort：排序方式（price_asc/price_desc/time_desc/credit_desc）
page：頁碼（默認 1）
limit：每頁條數（1-20，默認 10）
rare：是否僅顯示珍本（true/false，可選）

3. 響應數據結構

total：總結果數
page/limit：分頁信息
books：圖書列表數組
filters：可用篩選條件

三、完整代碼實現

以下是 Python 實現的孔夫子舊書網圖書搜索功能，包含 API 調用、數據解析和反爬策略：

import requests
import time
import random
from typing import Dict, List, Optional, Any
from user_agent import generate_user_agent
import logging# 配置日志
logging.basicConfig(level=logging.INFO,format='%(asctime)s - %(levelname)s - %(message)s'
)
logger = logging.getLogger('kongfz_api')class KongfzBookAPI:def __init__(self, api_key: str, use_proxy: bool = False, proxy_pool: List[str] = None):"""初始化孔夫子舊書網API客戶端:param api_key: 平臺申請的API Key:param use_proxy: 是否使用代理:param proxy_pool: 代理IP池列表"""self.api_key = api_keyself.base_url = "https://api.kongfz.com"self.search_endpoint = "/api/v1/books/search"self.detail_endpoint = "/api/v1/books/detail"self.max_limit = 20  # 最大每頁條數self.use_proxy = use_proxyself.proxy_pool = proxy_pool or []self.session = self._init_session()def _init_session(self) -> requests.Session:"""初始化請求會話，配置持久連接"""session = requests.Session()session.headers.update({"Accept": "application/json","Content-Type": "application/json","X-API-Key": self.api_key,"Connection": "keep-alive"})return sessiondef _get_random_headers(self) -> Dict[str, str]:"""生成隨機請求頭，降低反爬風險"""return {"User-Agent": generate_user_agent(),"Accept-Language": random.choice(["zh-CN,zh;q=0.9", "zh-TW,zh;q=0.9,en;q=0.8"]),"Referer": "https://www.kongfz.com/"}def _get_proxy(self) -> Optional[Dict[str, str]]:"""從代理池獲取隨機代理"""if self.use_proxy and self.proxy_pool:proxy = random.choice(self.proxy_pool)return {"http": proxy, "https": proxy}return Nonedef search_books(self,keyword: str,category: Optional[str] = None,year_min: Optional[int] = None,year_max: Optional[int] = None,condition: Optional[int] = None,price_min: Optional[float] = None,price_max: Optional[float] = None,publisher: Optional[str] = None,sort: str = "time_desc",page: int = 1,limit: int = 10) -> Dict[str, Any]:"""搜索孔夫子舊書網圖書:param keyword: 搜索關鍵字:param category: 圖書分類:param year_min: 最小出版年份:param year_max: 最大出版年份:param condition: 品相等級(1-10):param price_min: 最低價格:param price_max: 最高價格:param publisher: 出版社:param sort: 排序方式:param page: 頁碼:param limit: 每頁條數:return: 搜索結果"""# 限制每頁最大條數limit = min(limit, self.max_limit)# 構建查詢參數params: Dict[str, Any] = {"keyword": keyword,"sort": sort,"page": page,"limit": limit}# 添加可選參數if category:params["category"] = categoryif year_min is not None:params["year_min"] = year_minif year_max is not None:params["year_max"] = year_maxif condition is not None:params["condition"] = conditionif price_min is not None:params["price_min"] = price_minif price_max is not None:params["price_max"] = price_maxif publisher:params["publisher"] = publisher# 準備請求配置headers = self._get_random_headers()proxy = self._get_proxy()try:# 隨機延遲，模擬人類行為time.sleep(random.uniform(0.8, 1.5))# 發送請求response = self.session.get(f"{self.base_url}{self.search_endpoint}",params=params,headers=headers,proxies=proxy,timeout=15)response.raise_for_status()# 解析響應result = response.json()# 處理API錯誤if result.get("code") != 0:logger.error(f"API錯誤: {result.get('msg')}")return {"success": False,"error_code": result.get("code"),"error_msg": result.get("msg")}# 解析搜索結果return self._parse_search_result(result.get("data", {}))except requests.exceptions.RequestException as e:logger.error(f"請求異常: {str(e)}")return {"success": False,"error_msg": f"請求異常: {str(e)}"}except Exception as e:logger.error(f"處理響應失敗: {str(e)}")return {"success": False,"error_msg": f"處理響應失敗: {str(e)}"}def _parse_search_result(self, raw_data: Dict[str, Any]) -> Dict[str, Any]:"""解析搜索結果為結構化數據"""# 分頁信息pagination = {"total": raw_data.get("total", 0),"page": raw_data.get("page", 1),"limit": raw_data.get("limit", 10),"pages": (raw_data.get("total", 0) + raw_data.get("limit", 10) - 1) // raw_data.get("limit", 10)}# 解析圖書列表books = []for item in raw_data.get("books", []):# 處理古籍特有的版本信息ancient_info = Noneif item.get("is_ancient"):ancient_info = {"edition": item.get("ancient_edition"),  # 版本"engraving_year": item.get("engraving_year"),  # 刻印年代"binding": item.get("binding"),  # 裝幀"seal_info": item.get("seal_info")  # 鈐印信息}books.append({"book_id": item.get("id"),"title": item.get("title"),"author": item.get("author"),"publisher": item.get("publisher"),"publish_year": item.get("publish_year"),"category": item.get("category"),"is_ancient": item.get("is_ancient", False),  # 是否古籍"ancient_info": ancient_info,"condition": {"level": item.get("condition_level"),  # 品相等級"description": item.get("condition_desc")  # 品相描述},"price": {"current": item.get("price"),"original": item.get("original_price"),"currency": "CNY"},"seller": {"id": item.get("seller_id"),"name": item.get("seller_name"),"credit": item.get("seller_credit"),  # 信譽等級"score": item.get("seller_score")  # 好評率},"images": {"main": item.get("main_image"),"thumbnail": item.get("thumbnail")},"url": item.get("url"),"tags": item.get("tags", [])})# 解析可用篩選條件filters = self._parse_filters(raw_data.get("filters", {}))return {"success": True,"pagination": pagination,"books": books,"filters": filters}def _parse_filters(self, raw_filters: Dict[str, Any]) -> Dict[str, Any]:"""解析篩選條件"""filters = {}# 分類篩選if "categories" in raw_filters:filters["categories"] = [{"id": item.get("id"), "name": item.get("name"), "count": item.get("count")}for item in raw_filters["categories"]]# 品相篩選if "conditions" in raw_filters:filters["conditions"] = [{"level": item.get("level"), "name": item.get("name"), "count": item.get("count")}for item in raw_filters["conditions"]]# 年代篩選if "years" in raw_filters:filters["years"] = raw_filters["years"]return filtersdef batch_search(self,keyword: str,max_pages: int = 3,**kwargs) -> Dict[str, Any]:"""批量獲取多頁搜索結果:param keyword: 搜索關鍵字:param max_pages: 最大獲取頁數:param**kwargs: 其他搜索參數:return: 合并的搜索結果"""all_books = []current_page = 1total_pages = 1while current_page <= max_pages and current_page <= total_pages:logger.info(f"搜索第 {current_page} 頁，關鍵字: {keyword}")# 搜索當前頁result = self.search_books(keyword=keyword,page=current_page,**kwargs)if not result.get("success"):return result# 收集圖書數據all_books.extend(result.get("books", []))# 更新分頁信息pagination = result.get("pagination", {})total_pages = pagination.get("pages", 1)# 準備下一頁current_page += 1# 增加頁數間隔，降低反爬風險if current_page <= max_pages:time.sleep(random.uniform(1.5, 2.5))return {"success": True,"total_books": len(all_books),"books": all_books,"summary": {"total_available": pagination.get("total", 0),"fetched_pages": current_page - 1}}# 使用示例
if __name__ == "__main__":# 替換為你的API KeyAPI_KEY = "your_api_key"# 代理配置（可選）PROXY_POOL = [# "http://ip1:port",# "http://ip2:port"]# 初始化API客戶端kongfz_api = KongfzBookAPI(api_key=API_KEY,use_proxy=False,  # 根據需要開啟proxy_pool=PROXY_POOL)# 示例1：搜索古籍ancient_result = kongfz_api.search_books(keyword="論語",category="ancient",  # 古籍分類year_min=1949,year_max=2023,condition=8,  # 8級及以上品相sort="price_asc",page=1,limit=10)if ancient_result["success"]:print(f"古籍搜索: 找到 {ancient_result['pagination']['total']} 本相關圖書")if ancient_result["books"]:book = ancient_result["books"][0]print(f"書名: {book['title']}")print(f"作者: {book['author']}")print(f"價格: {book['price']['current']}元")print(f"品相: {book['condition']['level']}級 - {book['condition']['description']}")if book["is_ancient"]:print(f"版本: {book['ancient_info']['edition']}")# 示例2：批量搜索二手書# batch_result = kongfz_api.batch_search(#     keyword="魯迅全集",#     category="secondhand",  # 二手書分類#     price_min=50,#     price_max=500,#     max_pages=2# )# # if batch_result["success"]:#     print(f"\n批量搜索: 共獲取 {batch_result['total_books']} 本圖書")