Kongfz (孔夫子旧书网) Used Books Scraper

Scrapes kongfz.com — China's largest used/antiquarian book marketplace — for listings, categories, sellers and book detail pages.

Data Source

• Search / category / seller lists: the public pc-gw/search-web JSON API on search.kongfz.com (verified accessible without auth). The API soft-blocks CJK keyword queries from non-Chinese IPs unless the userArea geo parameter is present, so the actor always sends the site's default userArea=1006000000 (Beijing district) on keyword/seller queries.
• Listing detail: book.kongfz.com/{shopId}/{itemId}/ HTML pages

Modes

Mode	Inputs	Source
search (default)	searchQuery	.../product/keyword/list?keyword=...
byCategory	categoryId (current site taxonomy: 1 文学, 3 历史, 8 线装古籍, 43 小说, 31 计算机与互联网…)	.../product/category/list?catId=...
byBookUrl	bookUrls	book.kongfz.com/{shop}/{item}/ (canonical)
bySeller	shopName and/or sellerShopId	keyword list filtered by shopName

Output fields

book records: itemId, title, author, publisher, publishDate, isbn, price, condition (品相: 全新/九五品/…), conditionScore, binding (装帧), seller, shopId, shopNickname, shopArea, sellerReputation, shippingTime, listDate, remark, postage, isSoldOut, officialStore, images (verified kfzimg.com URLs), url, shopUrl, shopkeeperUrl.

Detail records add originalPrice, discount (折), shipping.

Every record carries recordType, sourceUrl and scrapedAt.

Filters

• minPrice / maxPrice — price range (client-side)
• condition — 品相 enum, e.g. brandNew (全新) … five (五品), client-side

Reliability

• Exponential-backoff retries on 429/5xx and the intermittent DNS/TLS failures this Chinese CDN produces.
• On 403/429 the actor lazily engages the free Apify AUTO datacenter proxy group.
• Invalid URLs / unparseable pages produce typed recordType: "error" records. Every record — including errors — carries sourceUrl: fetch/parse errors point at the failing URL, validation errors at the mode's canonical source page (https://search.kongfz.com/, https://book.kongfz.com/, https://shop.kongfz.com/).

Limitations

• bySeller filters server-side by shop name only: the search gateway ignores shopId (returns 0 rows). When only sellerShopId is provided the actor resolves it to the shop name via shop.kongfz.com/{id} (falling back to the m.kongfz.com/shop/{id} mobile page when the desktop host is TCP-blocked from datacenter IPs); if resolution fails a typed SHOP_RESOLVE_FAILED error is emitted — provide shopName instead.
• item.kongfz.com/book/{id}.html is a client-side SPA with no server-rendered data; such URLs produce a typed SPA_SHELL_URL error — use the canonical book.kongfz.com/{shop}/{item}/ form (returned by the search API).
• The search API caps total at 10,000 rows.