Kongfz APIsearch.kongfz.com ↗
Search China's largest used-book marketplace, Kongfz (孔夫子旧书网), by keyword or ISBN. Get pricing, condition, seller details, and category facets via 3 endpoints.
What is the Kongfz API?
The Kongfz API exposes 3 endpoints for querying the 孔夫子旧书网 used-book marketplace. The search_books endpoint accepts any keyword or ISBN and returns structured listings covering title, author, publisher, price in RMB, condition rating (品相), seller name, and a direct listing URL. Results are paginated, and total match counts let you gauge supply depth for any title or ISBN across thousands of sellers.
curl -X GET 'https://api.parse.bot/scraper/09fd851c-4cb5-4831-992c-b905461c7f44/search_books?page=1&keyword=%E4%B8%89%E4%BD%93&page_size=10' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace search-kongfz-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Kongfz Used Book Search — search listings, browse categories, and explore facets."""
from parse_apis.Kongfz_Used_Book_Search_API import Kongfz, Keyword, ParseError
client = Kongfz()
# Search for a book by keyword, iterate with limit cap.
for listing in client.listings.search(keyword=Keyword.__, page_size=10, limit=3):
print(listing.title, listing.price, listing.condition, listing.shop_name)
# Browse category listings (英文书) sorted by price ascending.
for item in client.category_listings.list(cat_id=6001, sort_type="5", limit=3):
print(item.title, item.price, item.isbn)
# Drill into a single search result using .first()
hit = client.listings.search(keyword=Keyword._9787540418250, limit=1).first()
if hit:
print(hit.title, hit.isbn, hit.listing_url)
# Get category facet counts for 图书 (catId=1)
try:
facets = client.category_facets.get(cat_id=1)
print(facets.total_found, facets.total_found_text)
for group in facets.facet_groups:
print(group.group_name)
for facet in group.facets[:3]:
print(f" {facet.name}: {facet.count}")
except ParseError as e:
print(f"error: {e.code}")
print("exercised: listings.search, category_listings.list, category_facets.get")
Search for used book listings by keyword or ISBN. Returns all matching product listings with title, author, publisher, ISBN, price in RMB, condition/品相, seller/shop name, and direct listing URL. Results are paginated. Pagination via integer page counter; each page returns up to page_size items. Empty results are possible for obscure queries.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination. |
| keywordrequired | string | Search keyword — can be a book title, author name, or ISBN (e.g. '9787540418250' or '三体'). |
| page_size | integer | Number of results per page, between 1 and 50. |
{
"type": "object",
"fields": {
"page": "integer — current page number",
"keyword": "string — the search keyword echoed back",
"listings": "array of Listing objects with book details, pricing, condition, and seller info",
"page_size": "integer — number of results per page",
"total_found": "integer — total number of matching listings across all pages",
"total_pages": "integer — total number of pages available"
},
"sample": {
"data": {
"page": 1,
"keyword": "三体",
"listings": [
{
"isbn": "9787229100605",
"price": 12.9,
"title": "三体",
"author": "刘慈欣 著；姚海军 编",
"item_id": 6929327279,
"shop_id": 788052,
"condition": "九五品",
"image_url": "https://www0.kfzimg.com/G06/M00/12/8B/p4YBAFqaFJOAAwNuAADZSdO-vJc627_n.jpg",
"publisher": "重庆出版社",
"shop_area": "甘肃省白银市",
"shop_name": "會州舊書鋪",
"price_text": "12.90",
"description": "",
"is_sold_out": false,
"listed_date": "2024-05-02 上书",
"listing_url": "https://book.kongfz.com/788052/6929327279",
"publish_date": "2016-06",
"condition_score": 95
}
],
"page_size": 50,
"total_found": 35140,
"total_pages": 200
},
"status": "success"
}
}About the Kongfz API
Search by Keyword or ISBN
The search_books endpoint takes a keyword parameter — a book title, author name, or ISBN string such as 9787540418250 — and returns an array of Listing objects. Each listing includes title, author, publisher, isbn, price (in RMB), condition (品相), seller shop name, and a direct listing_url. The response also echoes back keyword, page, page_size, total_found, and total_pages, so you can drive paginated retrieval by incrementing the integer page parameter up to the returned total_pages value. page_size can be set between 1 and 50.
Category Browsing and Facets
The get_category_listings endpoint returns a page of listings scoped to a specific Kongfz category by cat_id. Useful category IDs include 6001 (英文书), 6002 (日文书), and 6004 (俄文书). Each listing carries item_id, title, author, publisher, isbn, price, and cat_id. An optional sort_type parameter controls ordering — for example '5' for price ascending or '1' for sales rank — though some sort types and deep page numbers require authentication on the source site and will return a limited result set.
Facet Counts by Category
The get_category_facets endpoint takes a single cat_id (e.g. 1 for 图书, 8 for 线装古籍, 9 for 民国旧书) and returns total_found, a human-readable total_found_text, and a facet_groups array. Each facet group has a group_name and an array of facets with name, count, and optionally a sub-category ID. This is useful for understanding the distribution of listings across subcategories, condition grades, and stock status before executing a full listing query.
The Kongfz API is a managed, monitored endpoint for search.kongfz.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when search.kongfz.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official search.kongfz.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Look up all used copies of a specific ISBN to compare prices and condition ratings across sellers before purchasing.
- Monitor price trends for Chinese-language textbooks by periodically querying
search_bookswith a title keyword and recording thepricefield. - Build a cross-border book sourcing tool that queries foreign-language categories (英文书, 日文书) via
get_category_listingsfiltered bycat_id. - Aggregate seller inventory counts by category using
get_category_facetsto identify which subcategories have the most active listings. - Catalog availability of rare Republican-era (民国旧书) or thread-bound (线装古籍) books using
cat_idvalues 9 and 8. - Check whether a book is available in collectible condition by filtering
search_booksresults by thecondition(品相) field. - Enumerate sub-category IDs from
facet_groupsto build a category tree for a used-book discovery interface.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Kongfz (孔夫子旧书网) have an official developer API?+
What does the `search_books` endpoint return, and how do I paginate through results?+
listings array of objects each containing title, author, publisher, isbn, price, condition, seller, and listing_url, along with total_found and total_pages. Increment the integer page parameter from 1 up to total_pages to retrieve all matching results. Set page_size between 1 and 50 to control how many listings appear per page.Are there any limitations when browsing category listings with `get_category_listings`?+
sort_type values and requests for deep page numbers may return limited or empty results because those views require authentication on the Kongfz site. Stick to lower page numbers and default or price-ascending sort types ('4' or '5') for the most reliable responses.