?

孔夫子舊書(shū)網(wǎng)作為國(guó)內(nèi)知名的古籍、二手書(shū)交易平臺(tái)，其商品數(shù)據(jù)對(duì)于圖書(shū)收藏、學(xué)術(shù)研究及二手書(shū)電商系統(tǒng)具有重要價(jià)值。本文將詳細(xì)介紹孔夫子平臺(tái)接口的調(diào)用方法，涵蓋認(rèn)證機(jī)制、搜索參數(shù)配置、數(shù)據(jù)解析及反爬策略，并提供可直接使用的 Python 代碼實(shí)現(xiàn)，幫助開(kāi)發(fā)者合規(guī)獲取古籍和二手書(shū)數(shù)據(jù)。

一、孔夫子平臺(tái)接口基礎(chǔ)信息

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

接口特點(diǎn)：

采用 API Key 認(rèn)證機(jī)制，部分接口需要商業(yè)合作授權(quán)
支持按書(shū)名、作者、出版社、年代、品相等級(jí)等多維度篩選
包含古籍特有的版本信息、刻印年代、裝幀形式等字段
提供賣(mài)家信譽(yù)、交易記錄等二手書(shū)交易關(guān)鍵數(shù)據(jù)

接口端點(diǎn)：https://api.kongfz.com/api/v1/books/search

二、認(rèn)證機(jī)制與核心參數(shù)

1. 認(rèn)證方式

孔夫子接口采用簡(jiǎn)單直接的 API Key 認(rèn)證：

在孔夫子開(kāi)發(fā)者平臺(tái)注冊(cè)并申請(qǐng)應(yīng)用，獲取 API Key
在所有請(qǐng)求的 Header 中攜帶X-API-Key參數(shù)
商業(yè)用戶可申請(qǐng)更高權(quán)限的 Secret Key 進(jìn)行簽名認(rèn)證

2. 核心搜索參數(shù)

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

3. 響應(yīng)數(shù)據(jù)結(jié)構(gòu)

total：總結(jié)果數(shù)
page/limit：分頁(yè)信息
books：圖書(shū)列表數(shù)組
filters：可用篩選條件

三、完整代碼實(shí)現(xiàn)

以下是 Python 實(shí)現(xiàn)的孔夫子舊書(shū)網(wǎng)圖書(shū)搜索功能，包含 API 調(diào)用、數(shù)據(jù)解析和反爬策略：

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):
"""
初始化孔夫子舊書(shū)網(wǎng)API客戶端

:param api_key: 平臺(tái)申請(qǐng)的API Key
:param use_proxy: 是否使用代理
:param proxy_pool: 代理IP池列表
"""
self.api_key = api_key
self.base_url = "https://api.kongfz.com"
self.search_endpoint = "/api/v1/books/search"
self.detail_endpoint = "/api/v1/books/detail"
self.max_limit = 20 # 最大每頁(yè)條數(shù)
self.use_proxy = use_proxy
self.proxy_pool = proxy_pool or []
self.session = self._init_session()

def _init_session(self) -> requests.Session:
"""初始化請(qǐng)求會(huì)話，配置持久連接"""
session = requests.Session()
session.headers.update({
"Accept": "application/json",
"Content-Type": "application/json",
"X-API-Key": self.api_key,
"Connection": "keep-alive"
})
return session

def _get_random_headers(self) -> Dict[str, str]:
"""生成隨機(jī)請(qǐng)求頭，降低反爬風(fēng)險(xiǎn)"""
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]]:
"""從代理池獲取隨機(jī)代理"""
if self.use_proxy and self.proxy_pool:
proxy = random.choice(self.proxy_pool)
return {"http": proxy, "https": proxy}
return None

def 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]:
"""
搜索孔夫子舊書(shū)網(wǎng)圖書(shū)

:param keyword: 搜索關(guān)鍵字
:param category: 圖書(shū)分類
:param year_min: 最小出版年份
:param year_max: 最大出版年份
:param condition: 品相等級(jí)(1-10)
:param price_min: 最低價(jià)格
:param price_max: 最高價(jià)格
:param publisher: 出版社
:param sort: 排序方式
:param page: 頁(yè)碼
:param limit: 每頁(yè)條數(shù)
:return: 搜索結(jié)果
"""
# 限制每頁(yè)最大條數(shù)
limit = min(limit, self.max_limit)

# 構(gòu)建查詢參數(shù)
params: Dict[str, Any] = {
"keyword": keyword,
"sort": sort,
"page": page,
"limit": limit
}

# 添加可選參數(shù)
if category:
params["category"] = category
if year_min is not None:
params["year_min"] = year_min
if year_max is not None:
params["year_max"] = year_max
if condition is not None:
params["condition"] = condition
if price_min is not None:
params["price_min"] = price_min
if price_max is not None:
params["price_max"] = price_max
if publisher:
params["publisher"] = publisher

# 準(zhǔn)備請(qǐng)求配置
headers = self._get_random_headers()
proxy = self._get_proxy()

try:
# 隨機(jī)延遲，模擬人類行為
time.sleep(random.uniform(0.8, 1.5))

# 發(fā)送請(qǐng)求
response = self.session.get(
f"{self.base_url}{self.search_endpoint}",
params=params,
headers=headers,
proxies=proxy,
timeout=15
)
response.raise_for_status()

# 解析響應(yīng)
result = response.json()

# 處理API錯(cuò)誤
if result.get("code") != 0:
logger.error(f"API錯(cuò)誤: {result.get('msg')}")
return {
"success": False,
"error_code": result.get("code"),
"error_msg": result.get("msg")
}

# 解析搜索結(jié)果
return self._parse_search_result(result.get("data", {}))

except requests.exceptions.RequestException as e:
logger.error(f"請(qǐng)求異常: {str(e)}")
return {
"success": False,
"error_msg": f"請(qǐng)求異常: {str(e)}"
}
except Exception as e:
logger.error(f"處理響應(yīng)失敗: {str(e)}")
return {
"success": False,
"error_msg": f"處理響應(yīng)失敗: {str(e)}"
}

def _parse_search_result(self, raw_data: Dict[str, Any]) -> Dict[str, Any]:
"""解析搜索結(jié)果為結(jié)構(gòu)化數(shù)據(jù)"""
# 分頁(yè)信息
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)
}

# 解析圖書(shū)列表
books = []
for item in raw_data.get("books", []):
# 處理古籍特有的版本信息
ancient_info = None
if 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"), # 品相等級(jí)
"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"), # 信譽(yù)等級(jí)
"score": item.get("seller_score") # 好評(píng)率
},
"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 filters

def batch_search(self,
keyword: str,
max_pages: int = 3,
**kwargs) -> Dict[str, Any]:
"""
批量獲取多頁(yè)搜索結(jié)果

:param keyword: 搜索關(guān)鍵字
:param max_pages: 最大獲取頁(yè)數(shù)
:param**kwargs: 其他搜索參數(shù)
:return: 合并的搜索結(jié)果
"""
all_books = []
current_page = 1
total_pages = 1

while current_page <= max_pages and current_page <= total_pages:
logger.info(f"搜索第 {current_page} 頁(yè)，關(guān)鍵字: {keyword}")

# 搜索當(dāng)前頁(yè)
result = self.search_books(
keyword=keyword,
page=current_page,
**kwargs
)

if not result.get("success"):
return result

# 收集圖書(shū)數(shù)據(jù)
all_books.extend(result.get("books", []))

# 更新分頁(yè)信息
pagination = result.get("pagination", {})
total_pages = pagination.get("pages", 1)

# 準(zhǔn)備下一頁(yè)
current_page += 1

# 增加頁(yè)數(shù)間隔，降低反爬風(fēng)險(xiǎn)
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 Key
API_KEY = "your_api_key"

# 代理配置（可選）
PROXY_POOL = [
# "http://ip1:port",
# "http://ip2:port"
]

# 初始化API客戶端
kongfz_api = KongfzBookAPI(
api_key=API_KEY,
use_proxy=False, # 根據(jù)需要開(kāi)啟
proxy_pool=PROXY_POOL
)

# 示例1：搜索古籍
ancient_result = kongfz_api.search_books(
keyword="論語(yǔ)",
category="ancient", # 古籍分類
year_min=1949,
year_max=2023,
condition=8, # 8級(jí)及以上品相
sort="price_asc",
page=1,
limit=10
)

if ancient_result["success"]:
print(f"古籍搜索: 找到 {ancient_result['pagination']['total']} 本相關(guān)圖書(shū)")
if ancient_result["books"]:
book = ancient_result["books"][0]
print(f"書(shū)名: {book['title']}")
print(f"作者: {book['author']}")
print(f"價(jià)格: {book['price']['current']}元")
print(f"品相: {book['condition']['level']}級(jí) - {book['condition']['description']}")
if book["is_ancient"]:
print(f"版本: {book['ancient_info']['edition']}")

# 示例2：批量搜索二手書(shū)
# batch_result = kongfz_api.batch_search(
# keyword="魯迅全集",
# category="secondhand", # 二手書(shū)分類
# price_min=50,
# price_max=500,
# max_pages=2
# )
#
# if batch_result["success"]:
# print(f"n批量搜索: 共獲取 {batch_result['total_books']} 本圖書(shū)")

四、代碼核心功能解析

1. 反爬策略實(shí)現(xiàn)

隨機(jī)生成 User-Agent 和請(qǐng)求頭，模擬不同瀏覽器行為
加入隨機(jī)請(qǐng)求延遲，避免固定訪問(wèn)頻率被識(shí)別
支持代理 IP 池配置，分散請(qǐng)求來(lái)源
使用持久化 Session，模擬正常用戶瀏覽行為

2. 古籍?dāng)?shù)據(jù)特色處理

專門(mén)解析古籍特有的版本、刻印年代、裝幀等信息
區(qū)分古籍與普通二手書(shū)的數(shù)據(jù)結(jié)構(gòu)
提取鈐印信息等古籍收藏關(guān)鍵維度

3. 搜索功能設(shè)計(jì)

支持完整的圖書(shū)篩選參數(shù)，滿足古籍和二手書(shū)的搜索需求
提供單頁(yè)搜索和多頁(yè)批量搜索兩種模式
批量搜索時(shí)動(dòng)態(tài)調(diào)整間隔時(shí)間，平衡效率與安全性

4. 數(shù)據(jù)結(jié)構(gòu)化

按圖書(shū)類型組織數(shù)據(jù)，區(qū)分普通二手書(shū)和古籍
提取賣(mài)家信譽(yù)、品相描述等二手交易關(guān)鍵信息
解析可用篩選條件，便于前端實(shí)現(xiàn)高級(jí)篩選功能

五、實(shí)戰(zhàn)注意事項(xiàng)

1. 接口權(quán)限與申請(qǐng)

孔夫子 API 分為免費(fèi)版和商業(yè)版，免費(fèi)版有調(diào)用頻率限制（通常 QPS≤2）
古籍珍本等敏感數(shù)據(jù)需要申請(qǐng)商業(yè)授權(quán)
個(gè)人開(kāi)發(fā)者需提供身份證明，企業(yè)開(kāi)發(fā)者需提供營(yíng)業(yè)執(zhí)照

2. 反爬與合規(guī)

免費(fèi)版接口請(qǐng)勿進(jìn)行高頻次調(diào)用，建議單 IP 日調(diào)用不超過(guò) 1000 次
數(shù)據(jù)使用需遵守孔夫子平臺(tái)的版權(quán)協(xié)議，不得用于商業(yè)競(jìng)品
尊重古籍?dāng)?shù)據(jù)的知識(shí)產(chǎn)權(quán)，引用時(shí)需注明來(lái)源

3. 搜索策略優(yōu)化

古籍搜索建議結(jié)合年代和版本篩選，提高精準(zhǔn)度
批量獲取數(shù)據(jù)時(shí)，合理設(shè)置max_pages參數(shù)，避免觸發(fā)限制
對(duì)稀缺古籍建立緩存機(jī)制，緩存周期建議 7-30 天

4. 數(shù)據(jù)處理建議

書(shū)名和作者可能存在異體字、通假字，需進(jìn)行文字規(guī)范化處理
品相描述為文本信息，可通過(guò) NLP 技術(shù)提取關(guān)鍵評(píng)價(jià)
出版年代可能存在模糊表述（如 "民國(guó)年間"），需特殊處理

六、功能擴(kuò)展方向

開(kāi)發(fā)古籍版本比對(duì)工具，基于多本同書(shū)數(shù)據(jù)進(jìn)行版本差異分析
構(gòu)建賣(mài)家信譽(yù)評(píng)估系統(tǒng)，結(jié)合歷史交易和評(píng)價(jià)數(shù)據(jù)
實(shí)現(xiàn)圖書(shū)價(jià)格趨勢(shì)分析，追蹤古籍市場(chǎng)價(jià)格波動(dòng)
開(kāi)發(fā)古籍修復(fù)需求識(shí)別功能，基于品相描述自動(dòng)判斷修復(fù)需求

?
審核編輯 黃宇