Douban APIbook.douban.com ↗
Access Douban Books data via 9 endpoints: book search, metadata, ratings, long reviews, short comments, Top 250, tag browsing, and monthly charts.
What is the Douban API?
The Douban Books API provides 9 endpoints covering book search, detailed metadata, user reviews, short comments, curated charts, and tag-based browsing from book.douban.com. The get_book_detail endpoint returns structured publication metadata — author, publisher, ISBN, page count, binding — alongside a 10-point average rating and vote count. Whether you're building a reading tracker, recommendation engine, or research tool, this API gives you direct access to one of China's largest book community datasets.
curl -X GET 'https://api.parse.bot/scraper/25fc1543-1fce-4d05-a285-00e4d45dad81/get_books_by_tag?tag=%E5%B0%8F%E8%AF%B4&sort=T&start=0' \ -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 book-douban-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: Douban Books SDK — bounded, re-runnable; every call capped."""
from parse_apis.douban_books_api import DoubanBooks, TagSort, BookNotFound
client = DoubanBooks()
# Browse Top 250 — limit caps total items fetched
for book in client.topbooks.list(limit=3):
print(book.title, book.rating, book.quote)
# Search by keyword, take first result, then drill into full detail
result = client.searchresults.search(query="三体", limit=1).first()
if result:
detail = result.details()
print(detail.title, detail.rating, detail.tags)
# Discover tags by category
cat = client.tagcategories.list(limit=1).first()
if cat:
print(cat.category, [t.name for t in cat.tags[:3]])
# Constructible tag: browse books by tag with sort enum
for book in client.tag("小说").books(sort=TagSort.TOP_RATED, limit=3):
print(book.title, book.rating, book.count)
# Sub-resources: get a book's reviews
target = client.book("1007305")
for review in target.reviews.list(limit=2):
print(review.user, review.rating, review.date)
# Typed error handling
try:
client.books.get(id="9999999999")
except BookNotFound as exc:
print(f"Book not found: {exc}")
print("exercised: topbooks.list / searchresults.search / tagcategories.list / tag.books / book.reviews.list / books.get")
Fetch a paginated list of books for a given tag. Returns books with title, rating, publication info, and reader count. Paginated via offset; each page returns up to 20 books.
| Param | Type | Description |
|---|---|---|
| tagrequired | string | Tag name to browse (e.g. '小说', '文学', '历史'). Browse available tags via get_tag_list endpoint. |
| sort | string | Sort order. Accepted values: 'T' (popular), 'R' (recent), 'S' (top rated). |
| start | integer | Pagination offset (number of items to skip). |
{
"type": "object",
"fields": {
"tag": "string, the tag name queried",
"books": "array of book objects with keys: title, url, id, image, pub, rating, count, desc",
"start": "integer, pagination offset used"
},
"sample": {
"data": {
"tag": "小说",
"books": [
{
"id": "35494160",
"pub": "[美] 安迪·威尔 / 耿辉 / 译林出版社 / 2021-9 / 68.00",
"url": "https://book.douban.com/subject/35494160/",
"desc": "科技宅男+跨星系好（基）友联袂上演太空大救援",
"count": "25880",
"image": "https://img9.doubanio.com/view/subject/s/public/s33958826.jpg",
"title": "挽救计划",
"rating": "9.1"
}
],
"start": 0
},
"status": "success"
}
}About the Douban API
Book Metadata and Search
The search_books endpoint accepts a keyword query and returns matching books with id, title, author_name, year, and a cover image URL. Once you have a subject ID, get_book_detail returns the full record: a metadata object keyed by Chinese publication labels (作者, 出版社, 出版年, ISBN, 页数, 装帧, 定价), a rating string out of 10, votes, tags array, intro, and author_intro. Subject IDs are numeric strings like '1007305'.
Charts, New Releases, and Tag Browsing
get_top250 returns the Douban Books Top 250 list, paginated in groups of 25 via the start parameter (0, 25, 50, … 225). Each book entry includes title, id, pub, rating, votes, and a one-line quote. get_monthly_hot_chart and get_new_books require no inputs and return current trending and recently published titles respectively, each with title, id, info, and rating fields.
For tag-based discovery, get_tag_list returns the full tag cloud organized into named categories — 文学, 流行, 文化, 生活, 经管, 科技 — each with a list of tags and their associated book counts. get_books_by_tag then takes a tag string and an optional sort parameter (T for popular, R for recent, S for top rated) plus a start offset for pagination, returning title, url, id, image, pub, rating, count, and desc for each book.
Reviews and Comments
Two endpoints cover user-generated content. get_book_reviews returns long-form reviews for a given book ID, each with user, rating, title, content (excerpt), and date. get_book_short_comments returns brief user comments with user, rating, time, content, and a votes count indicating how many readers found the comment useful. Both endpoints require the Douban subject id as input.
The Douban API is a managed, monitored endpoint for book.douban.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when book.douban.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 book.douban.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?+
- Build a Chinese book recommendation engine using tag categories and Top 250 ratings from
get_top250andget_tag_list - Populate a reading list app with full publication metadata — ISBN, publisher, page count — via
get_book_detail - Aggregate sentiment for a title by collecting long reviews from
get_book_reviewsalongside short comments fromget_book_short_comments - Track monthly trending books in China using
get_monthly_hot_chartfor content or market research - Seed a book database with cover images, author names, and publication years using
search_booksandget_book_detail - Analyze the distribution of reader ratings across genre tags by combining
get_books_by_tagwith theratingandcountfields - Monitor new releases in the Chinese book market using the
get_new_booksendpoint
| 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 Douban provide an official developer API for book data?+
What does `get_book_detail` return and how granular is the publication metadata?+
metadata object whose keys are the Chinese field labels shown on the book page — typically 作者 (author), 出版社 (publisher), 出版年 (publication year), ISBN, 页数 (pages), 装帧 (binding), and 定价 (price). Not all fields are present for every book; coverage depends on what the source record includes. The endpoint also returns rating, votes, intro, author_intro, tags, and a cover image URL.How does pagination work for tag browsing and the Top 250?+
get_books_by_tag and get_top250 both use a start integer offset. For get_top250 valid values are 0 through 225 in steps of 25, giving 25 books per page. For get_books_by_tag you increment start by the number of results returned per page. There is no limit parameter — page size is fixed by the source.Does the API return user reading lists, want-to-read counts, or personal bookshelves?+
Are the reviews and comments returned in full, or only excerpts?+
get_book_reviews returns a content field that is an excerpt of each long-form review, not the full text. get_book_short_comments returns the complete short comment since those are inherently brief. Full review body text is not currently returned by get_book_reviews. You can fork the API on Parse and revise it to retrieve the full review text from individual review pages.