View on GitHub

doubanapi

豆瓣API文档备份

图书 Api V2

回 Api V2 首页

注意: 1. 下文中提到的图书并不包括杂志。 2. count 最大为 100,大于 100 的 count 会被置为 100。

scope: book_basic_r

name Method endpoint
获取图书信息 GET /v2/book/:id
根据 isbn 获取图书信息 GET /v2/book/isbn/:name
搜索图书 GET /v2/book/search
获取某个图书中标记最多的标签 GET /v2/book/:id/tags
获取用户对图书的所有标签 GET /v2/book/user/:name/tags
获取某个用户的所有图书收藏信息 GET /v2/book/user/:name/collections
获取用户对某本图书的收藏信息 GET /v2/book/:id/collection
获取某个用户的所有笔记 GET /v2/book/user/:name/annotations
获取某本图书的所有笔记 GET /v2/book/:id/annotations
获取某篇笔记的信息 GET /v2/book/annotation/:id
获取丛书书目信息 GET /v2/book/series/:id/books

scope: book_basic_w

name Method endpoint
用户收藏某本图书 POST /v2/book/:id/collection
用户修改对某本图书的收藏 PUT /v2/book/:id/collection
用户删除对某本图书的收藏 DELETE /v2/book/:id/collection
用户给某本图书写笔记 POST /v2/book/:id/annotations
用户修改某篇笔记 PUT /v2/book/annotation/:id
用户删除某篇笔记 DELETE /v2/book/annotation/:id

scope: douban_basic_common

name Method endpoint
发表新评论 POST /v2/book/reviews
修改评论 PUT /v2/book/review/:id
删除评论 DELETE /v2/book/review/:id
获取用户对图书的所有标签(deprecated) GET /v2/book/user_tags/:id

图书信息 Book

{
  "id": "1003078",
  "isbn10": "7505715666",
  "isbn13": "9787505715660",
  "title": "小王子",
  "origin_title": "",
  "alt_title": "",
  "subtitle": "",
  "url": "http://api.douban.com/v2/book/1003078",
  "alt": "http://book.douban.com/subject/1003078/",
  "image": "http://img1.douban.com/mpic/s1001902.jpg",
  "images": {
    "small": "http://img1.douban.com/spic/s1001902.jpg",
    "large": "http://img1.douban.com/lpic/s1001902.jpg",
    "medium": "http://img1.douban.com/mpic/s1001902.jpg"
  },
  "author": ["(法)圣埃克苏佩里"],
  "translator": ["胡雨苏"],
  "publisher": "中国友谊出版公司",
  "pubdate": "2000-9-1",
  "rating": { "max": 10, "numRaters": 9438, "average": "9.1", "min": 0 },
  "tags": [
    { "count": 2416, "name": "小王子" },
    { "count": 1914, "name": "童话" },
    { "count": 1185, "name": "圣埃克苏佩里" },
    { "count": 863, "name": "法国" },
    { "count": 647, "name": "经典" },
    { "count": 597, "name": "外国文学" },
    { "count": 495, "name": "感动" },
    { "count": 368, "name": "寓言" }
  ],
  "binding": "平装",
  "price": "19.8",
  "series": {
    "id": "2065",
    "title": "新史学&多元对话系列"
  },
  "pages": "111",
  "author_intro": "圣埃克苏佩里(1900-1944)1900年,尼采逝世。这一年,安德烈・纪德在布鲁塞尔一次会议上宣称:“当今文学土地的面貌可以说是一片沼泽。”1900年,圣埃克苏佩里诞生。净化沼泽的意愿和能力历史地落在这个“世纪儿”的身上,圣埃克苏佩里是尼采式的第二代法国作家,拿但业的儿子,琐罗亚斯德的孙子,这个飞行员受到极大的遗传影响。灾种影响使他在探索、忧虑和英雄主义的道路上走到尽头。如尼采所说:“你应该超截止自己,走得更远,登得更高,直至群星在你脚下。”尼采成为他座舱中想象的伙伴。这个飞越沙漠和海洋的年轻驾驶员同样也遵循着纪德的教诲:“与其过宁静的生活,不如过悲怆的生活。”圣埃克苏佩里在他整个的一生中都在反复思考力量和热诚的真谛。\n圣埃克苏佩里(AntoinedeSaiot-Exupery),1900年出生于法国里昂,1921-1923年在法国空军中服役,曾是后备飞行员,后来又成为民用航空驾驶员,参加了开辟法国――非洲――南美国际航线的工作,其间他还从事文学写作,作品有《南线班机》(1930),《夜航》(1931)等等。\n1939年德国法西斯入侵法国,鉴于圣埃克苏佩里曾多次受伤,医生认为他不能再入伍参战;但经他坚决要求,参加了抗德战争,被编入2/33空军侦察大队。1940年法国在战争中溃败,他所在的部队损失惨重,该部被调往阿尔及尔,随后即被复员,他只身流亡美国。在美国期间,他继续从事写作,1940年发表了《战斗飞行员》,1943年发表了《给一个人质的信》以及《小王子》。\n1943年,在他的强烈要求下,他回到法国在北非的抗战基地阿尔及尔。他的上级考虑到他的身体和年龄状况,只同意他执行五次飞行任务,他却要求到八次,1944年7月31日上午,他出航执行第八次任务,从此再也没有回来,牺牲时,年仅44岁。\n在欧洲某地的一个湖中,发现了圣・德克旭贝里的飞机残骸。这次搜索是经过对他最后一次出航的线路和德军当时的空军记录研究以后进行的,经过认证确认是那架失踪了半个世纪的侦察机。为了纪念这位伟大的战士和文学家,当地决定为这架飞机的残骸建立一个博物馆,以他的名字命名,陈列他的作品和遗物。",
  "summary": "小王子驾到!大家好,我是小王子,生活在B612星球,别看我是王子出生,我要做的事也不少,有时给花浇水,有时我还得耐心地把火山口通一通。实在闷得发慌的时候,为了找些事做,学点东西,我也访问一些其他的星球,像325号、326号、327号之类的。当然,我经历的事情也不少,有开心的,也有不开心的。这些事我通常会向地球上一个叫圣埃克苏佩里的人倾诉。对了,你可不要小瞧他,他是拿但业的儿子,琐罗亚斯德的孙子。他还被人们认为尼采式的第二代法国作家。他一生有两大爱好:飞行和写作。我之所以能够这样受欢迎也是他的功劳。因为他把我在其他星球的所见所闻编成了一本小书,也就是你们即将看到的这一本。它不但被誉为有史以来阅读仅次于《圣经》的书,全球发行的语言更是超过100种。可惜的是,在这本书出版后没多久,他在一次架机执行任务时一去不复返了,没有人知道他去了哪里。今天我第一次来到中国,还希望大家同样能够喜欢我。在这本书里他收藏了很多我在其他星球的精美彩图,而且,值得一提的是,中国著名的评论家周国平先生也特意为我作序。可以说,这本书不仅小朋友们爱不释手,就连大人们也会看得如痴如醉。糟糕,我还忘了告诉你,你只有在卓越网(www.joyo.com)才能找到我。有缘的话,我们很快就能相见了。\n尼采、纪德、圣埃克苏佩里是同一家庭的成员,由无可否认的联系连在一起。圣埃克苏佩里热爱尼采。纪德热爱圣埃克苏佩里。\n1945年2月1日《费加罗报》上,他谈到这位飞行员:\"他无论在何处着陆,都是为了带去欢乐。\"\n但是圣埃克苏佩里将公正置于友谊之上。他在《札记》中写道:\"纪德评价,却不曾体验。\"确切的见解。这是行动者面对思想者所感到的骄傲。尼采和纪德孕育了一种道德,并用美妙的文学冲动表现出来。只有圣埃克苏佩里一人在危险和充实中体验了这种道德。他是翱翔于九天的琐罗亚斯德,是乘风飞去的拿但业。他的书房便是机舱。他的格言:事事体验。他的作品:生活。圣埃克苏佩里对尼采的力量和纪德的热诚做作了合理的总结:他的冒险为职业,把写作当嗜好,他在飞行员的位置上实现着克尔桤郭尔的愿望:\"做一个思想家和做一个人,二者尽量不要区别开来,这样才是明智的。\"--(法)玛雅·戴斯特莱姆",
  "catalog": "序言:法兰西玫瑰\n小王子\n圣埃克苏佩里年表\n",
  "ebook_url": "https://read.douban.com/ebook/1234567/(该字段只在存在对应电子书时提供)",
  "ebook_price": "12.00"
}

评论信息 Review

{
  "id": 1000104,
  "title": "长大就笨了",
  "alt": "http://book.douban.com/review/1000104/",
  "author": User,
  "book": Book,
  "rating": {
    "max": 5,
    "value": "5",
    "min": 1
  },
  "votes": 1376,
  "useless": 36,
  "comments": 292,
  "summary": "「我在」:http://www.bighead.cn/?p=67\r\n\r\n\r\n那天我第一次打开《小王子》,就呆了。不是因为它的清新剔透,而是圣...",
  "published": "2005-04-06 11:51:52",
  "updated": "2012-08-30 20:48:23"
}

标签信息 Tag

{
  "count": 20,
  "title": "经典"
}

收藏信息 Collection

{
  "book": Book,
  "book_id": "7056972",
  "comment": "各种成长的喜悦与痛苦,讲故事的功力比起过往短篇经典有过之而无不及,依旧是巅峰之作!",
  "id": 593151296,
  "rating": {
    "max": 5,
    "min": 0,
    "value": "5"
  },
  "status": "read",
  "tags": ["吴淼", "奇幻", "中国", "塔希里亚"],
  "updated": "2012-10-19 15:29:41",
  "user_id": "33388491"
}

笔记信息 Annotation

{
  "id": "18484568",
  "book_id": "4238362",
  "book": Book,
  "author_id": "49745852",
  "author_user": User,
  "chapter": "一个人要像一支队伍",
  "page_no": 194,
  "privacy": 2,
  "abstract": "我其实并不孤僻,甚至可以说开朗活泼。但大多时候我很懒,懒得经营一个关系。还有一些时候,就是爱自由,觉得任何一种关系都会束缚自己。当然最主要的,还是知音难觅。 我老觉得自己跟大多数人交往,总是只能拿出...",
  "content": "<原文开始>我其实并不孤僻,甚至可以说开朗活泼。但大多时候我很懒,懒得经营一个关系。还有一些时候,就是爱自由,觉得任何一种关系都会束缚自己。当然最主要的,还是知音难觅。 我老觉得自己跟大多数人交往,总是只能拿出自己的一个维度,很难找到一个像我一样兴趣一望无际的人。</原文结束> 读到这里的时候,内心里有种很强烈的冲动,觉得我应该把它抄下来,贴在我的额头上,脸上,肚皮上,腿上,胳膊上...以提醒自己,原来自己不是那么孤独,原来这种孤独还可以被人理解,甚至原来还有人坚持孤独也是一种方式. <原文开始>但另一些时候,又惊诧于人的生命力。在这样缺乏沟通、交流、刺激、辩论、玩笑、聊天、绯闻、传闻、小道消息、八卦、msn...的生活里,没有任何圈子,多年来仅仅凭着自己跟自己对话,我也坚持了思考,保持了表达欲,还能写小说政论论文博客,可见要把一个人意志的皮筋给撑断,也没有那么容易。 忍受的极限会是什么样的结果? 让我告诉你,忍受是没有极限的。 年少的时候,我觉得孤单是很酷的一件事,长大以后,我觉得孤单是很凄凉的一件事。现在,我觉得孤单不是一件事。至少,努力不让它成为一件事。</原文结束> 忍受的极限会是什么样子?我不知道,如果有极限的话,我愿意尝尝,让自己在孤单到死之前明白孤单的幸福,或者不幸。 我一直想不明白的问题,是究竟从何时起,我开始接受孤单。 我记得开始的时候,孤单只是一种不屈服,一种对现状的无声抗议,一种不愿意被同质化的沉默宣言。 可是,有些东西,一旦你学会了,它就成为你习惯的一部分,譬如发呆,譬如抽烟。但是,孤单这东西,来得更可怕,它开始成为你行为的一部分,接着成为你精神的一部分。在你做出每个决定之前,它都环绕左右,使你隐藏自己的表达欲,使你疏离群体,使你逃避责任和分享。 从这一刻起,孤单不再是致命的吸引,而成为挥之不去的阴影。 <原文开始>当然还有书、报纸、电影电视、网络、DVD、CD,那里面有他人的生活、关于这个世界的道理、音乐的美、知识的魔术、爱的可能性、令人愤怒的政治家..我们九九八十一生都不可能穷尽这些道理、美、爱、魔术的一个小指甲盖,怎么还能抱怨生活给予我们的太少。 我想自己终究是幸运的,不仅仅因为那些外在的所得,而且因为我还挺结实的。总是被打得七零八落,但总还能在上帝他老人家数到“九”之前重新站起来,再看到眼前那个大海时,还是一样兴奋,欢天喜地地跳进去。在辽阔的世界面前,一个人有多谦卑,他就会有多快乐。当罗素说知识、爱、同情心是他生活的动力时,我觉得简直可以和这个风流成性的老不死称兄道弟。</原文结束> 知识、爱、同情心。在爱成为我的寄托,同情心成为我衡量好坏的标准之前,我只有钻到知识的密室里,寻找关于梦想的秘密,让孤单变成一种洒脱,让孤单也变成一种学识。 <原文开始>因为这种幸运,我原谅自己经受的挫折、孤单,原谅自己的敏感、焦虑和神经质,原谅上帝他老人家让X不喜欢我,让我不喜欢Y,让那么多人长得比我美,或者比我智慧,原谅他让我变老变胖,因为他把世界上美好的品质给了我:不气馁,有召唤,爱自由。 如果你还在为自己孤单寂寞怀才不遇举世皆浊我独醒而深深叹息的话,那么让我告诉你,你买不到那个彩票的,别在把你时间的积蓄两块、两块的花出去,回到你的内心,寻找你自己,与心灵深处的他、他们一起出发去旅行。如果你有足够的好奇心,你可以足不出户而周游世界,身无分文而腰缠万贯。人生若有知己相伴固然妙不可言,但那可遇而不可求,真的,也许既不可遇又不可求,可求的只有你自己,你要俯下身去,朝着幽暗深处的自己伸出手去。</原文结束> 不气馁,有召唤,爱自由。",
  "abstract_photo": "",
  "photos": {},
  "last_photo": 0,
  "comments_count": 169,
  "hasmath": false,
  "time": "2012-10-13 17:42:10"
}

图书错误码

错误码 错误信息 含义 status code
6000 book_not_found 图书不存在 404
6002 unauthorized_error 没有修改权限 403
6004 review_content_short(should more than 150) 书评内容过短(需多于 150 字) 400
6006 review_not_found 书评不存在 404
6007 not_book_request 不是豆瓣读书相关请求 403
6008 people_not_found 用户不存在 404
6009 function_error 服务器调用异常 400
6010 comment_too_long(should less than 350) 短评字数过长(需少于 350 字) 400
6011 collection_exist(try PUT if you want to update) 该图书已被收藏(如需更新请用 PUT 方法而不是 POST) 409
6012 invalid_page_number(should be digit less than 1000000) 非法页码(页码需要是小于 1000000 的数字) 400
6013 chapter_too_long(should less than 100) 章节名过长(需小于 100 字) 400

fields 参数选择需要的指定字段

对于使用 GET 方式的获取数据 API,可以通过 fields 参数指定返回数据中的信息项的字段,以减少返回数据中开发者并不关心的部分。

fields 参数的格式目前只支持逗号分隔的字段名,没有 fields 参数或 fields 参数为 all 表示不做过滤。

对于获取单条数据的 API,例如:

GET https://api.douban.com/v2/book/17604305?fields=id,title,url

返回数据:

{
  "url": "http://api.douban.com/v2/book/17604305",
  "id": "17604305",
  "title": "塔希里亚故事集"
}

对于获取多条数据的 API,例如:

GET https://api.douban.com/v2/book/search?q=python&fields=id,title

返回数据:

{
    "count":20,
    "start":0,
    "total":641,
    "books":[
        {
            "id":"4866934",
            "title":"Python基础教程"
        },
        {
            "id":"3117898",
            "title":"Python源码剖析"
        },
        {
            "id":"3948354",
            "title":"Python学习手册"
        },
        {
            "id":"3884108",
            "title":"可爱的Python"
        },
        
        ]
}

获取图书信息

GET  https://api.douban.com/v2/book/:id

返回图书信息,返回 status=200

对于授权用户,返回数据中会带有该用户对该图书的收藏信息:

{
     (图书信息的其他部分)
    "current_user_collection": {
        "status":"read",
        "rating": {
            "max":5,
            "value":"5",
            "min":0
        },
        "updated":"2012-11-2012:08:04",
        "user_id":"33388491",
        "book_id":"6548683",
        "id":605519800
    }
}

根据 isbn 获取图书信息

GET  https://api.douban.com/v2/book/isbn/:name

同上,返回图书信息,返回 status=200

搜索图书

GET  https://api.douban.com/v2/book/search
参数 意义 备注
q 查询关键字 q 和 tag 必传其一
tag 查询的 tag q 和 tag 必传其一
start 取结果的 offset 默认为 0
count 取结果的条数 默认为 20,最大为 100

返回:返回 status=200,

{
  "start": 0,
  "count": 10,
  "total": 30,
  "books": [Book]
}

注:对于登录用户,若搜索结果图书在当前用户的图书收藏中,会在对应搜索结果信息中附加当前用户对此书的收藏信息,改部分的 Book 数据结构如下:

{
     (图书信息的其他部分)
    "current_user_collection": {
        "status":"read",
        "rating": {
            "max":5,
            "value":"5",
            "min":0
        },
        "updated":"2012-11-2012:08:04",
        "user_id":"33388491",
        "book_id":"6548683",
        "id":605519800
    }
}

某个图书中标记最多的标签

GET  https://api.douban.com/v2/book/:id/tags

返回:返回 status=200,最多返回前 50 个 tag

{
  "start": 0,
  "count": 10,
  "total": 30,
  "tags": [Tag]
}

发表新评论

POST  https://api.douban.com/v2/book/reviews
参数 意义 备注
book 评论所针对的 book id 必传
title 评论头 必传
content 评论内容 必传,且多于 150 字
rating 打分 非必传,数字 1 ~ 5 为合法值,其他信息默认为不打分

返回: 返回 status=201, 图书评论 Review 信息

注意:此处的 Review 肯定是当前用户的书评,所以其返回的不是 summary(摘要),而是 content(全文)

修改评论

PUT  https://api.douban.com/v2/book/review/:id
参数 意义 备注
title 评论头 必传
content 评论内容 必传,且多于 150 字
rating 打分 非必传,数字 1 ~ 5 为合法值,其他信息默认为不打分

返回: status = 202, 图书评论 Review 信息

注意:此处的 Review 肯定是当前用户的书评,所以其返回的不是 summary(摘要),而是 content(全文)

删除评论

DELETE  https://api.douban.com/v2/book/review/:id

返回:返回 status=200, OK

获取用户对图书的所有标签

GET  https://api.douban.com/v2/book/user/:name/tags

或者

GET  https://api.douban.com/v2/book/user_tags/:id

返回:返回 status=200,

{
  "start": 0,
  "count": 10,
  "total": 30,
  "tags": [Tag]
}

获取某个用户的所有图书收藏信息

GET  https://api.douban.com/v2/book/user/:name/collections
参数 意义 备注
status 收藏状态 选填(想读:wish 在读:reading 读过:read)默认为所有状态
tag 收藏标签 选填
from 按收藏更新时间过滤的起始时间 选填,格式为符合 rfc3339 的字符串,例如”2012-10-19T17:14:11”,其他信息默认为不传此项
to 按收藏更新时间过滤的结束时间 同上
rating 星评 选填,数字 1 ~ 5 为合法值,其他信息默认为不区分星评

返回: status = 200,

{
  "start": 0,
  "count": 20,
  "total": 23,
  "collections": [Collection]
}

获取用户对某本图书的收藏信息

GET  https://api.douban.com/v2/book/:id/collection
参数 意义 备注
user_id 用户 id 选填(uid 或者数字 id 均可)

带有 user_id 参数时,获取的收藏信息为该用户对该图书的公开收藏信息,如为私有收藏,返回 404

返回: status = 200 图书收藏 Collection 信息

注意:如果该用户未收藏此图书,会认为该资源不存在,返回如下信息:

status code: 404
{
  "code": 1001,
  "msg": "uri_not_found",
  "request": "GET /v2/book/<请求图书的id>/collection"
}

用户收藏某本图书

POST  https://api.douban.com/v2/book/:id/collection
参数 意义 备注
status 收藏状态 必填(想读:wish 在读:reading 或 doing 读过:read 或 done)
tags 收藏标签字符串 选填,用空格分隔
comment 短评文本 选填,最多 350 字
privacy 隐私设置 选填,值为’private’为设置成仅自己可见,其他默认为公开
rating 星评 选填,数字 1 ~ 5 为合法值,其他信息默认为不评星

返回: status = 201 图书收藏 Collection 信息

用户修改对某本图书的收藏

PUT  https://api.douban.com/v2/book/:id/collection
参数 意义 备注
status 收藏状态 必填(想读:wish 在读:reading 或 doing 读过:read 或 done)
tags 收藏标签字符串 选填,用空格分隔
comment 短评文本 选填,最多 350 字
privacy 隐私设置 选填,值为’private’为设置成仅自己可见,其他默认为公开
rating 星评 选填,数字 1 ~ 5 为合法值,其他信息默认为不评星

返回: status = 202 图书收藏 Collection 信息

用户删除对某本图书的收藏

DELETE  https://api.douban.com/v2/book/:id/collection

返回: status = 204 无返回信息

获取某个用户的所有笔记

GET  https://api.douban.com/v2/book/user/:name/annotations

默认按 update_time 倒序排列

返回: status = 200,

{
  "start": 0,
  "count": 20,
  "total": 23,
  "annotations": [Annotation]
}

获取某本图书的所有笔记

GET  https://api.douban.com/v2/book/:id/annotations
参数 意义 备注
format 返回 content 字段格式 选填(编辑伪标签格式:text, HTML 格式:html),默认为 text
order 排序 选填(最新笔记:collect, 按有用程度:rank, 按页码先后:page),默认为 rank
page 按页码过滤 选填

此数据仅显示公开笔记

返回: status = 200,

{
  "start": 0,
  "count": 20,
  "total": 23,
  "annotations": [Annotation]
}

获取某篇笔记的信息

GET  https://api.douban.com/v2/book/annotation/:id
参数 意义 备注
format 返回 content 字段格式 选填(编辑伪标签格式:text, HTML 格式:html),默认为 text

返回: status = 200, 笔记 Annotation 信息

获取丛书书目信息

GET  https://api.douban.com/v2/book/series/:id/books

返回: status = 200, 图书信息

用户给某本图书写笔记

POST  https://api.douban.com/v2/book/:id/annotations
参数 意义 备注
content 笔记内容 必填,需多于 15 字
page 页码 页码或章节名选填其一,最多 6 位正整数
chapter 章节名 页码或章节名选填其一,最多 100 字
privacy 隐私设置 选填,值为’private’为设置成仅自己可见,其他默认为公开

笔记目前支持上传图片功能,采用 multipart/form-data 编码方式,上传图片大小限制为<3M,name 推荐为用从 1 开始的图片编号(用 pic1,pic2 亦可),举个简单的例子如下:

curl "https://api.douban.com/v2/book/:id/annotations" -H "Authorization: Bearer <access_token>" -F "content=这是测试文本<图片1>需要多于15个字,凑字数凑字数" -F "[email protected]" -F "page=13"

返回: status = 201 该笔记 Annotation 信息

用户修改某篇笔记

PUT  https://api.douban.com/v2/book/annotation/:id
参数 意义 备注
content 笔记内容 必填,需多于 15 字
page 页码 页码或章节名选填其一,最多 6 位正整数
chapter 章节名 页码或章节名选填其一,最多 100 字
privacy 隐私设置 选填,值为’private’为设置成仅自己可见,其他默认为公开

笔记中的指定编号图片不允许重新上传,如需更新可以添加新图片并替换掉<图片 n="">。 未被用的图片数据仍旧可以从 photos 字段找到,且不会显示在 content 里。

返回: status = 202 更新后的该笔记 Annotation 信息

用户删除某篇笔记

DELETE  https://api.douban.com/v2/book/annotation/:id

只能删除用户自己的笔记

返回: status = 204 无返回信息