Mikel
豆瓣 API 使用指南
豆瓣API是豆瓣为第三方开发人员提供的编程接口。利用豆瓣API，你可以在你的网站或程序中使用豆瓣的数据和功能。 目前的豆瓣API支持的功能包括：
- 搜索并查看书籍、电影、音乐信息
- 搜索并查看用户信息
- 查看用户收藏
- 添加、更新、删除用户收藏
- 查看评论
- 发布、修改、删除评论
在未来我们会支持更多的功能，例如查看、增删友邻.
本文档为需要快速了解豆瓣API的用户提供一个概览, 更为完整的豆瓣API信息请参阅 豆瓣API 参考手册. 现在可以使用Python 或者Javascript客户端进行开发，欢迎爱好者提供其他语言的客户端。
如果你编写了一个有趣的API应用，欢迎到API小组发布, 另外也欢迎到API小组参与豆瓣API的讨论，提出你对豆瓣API各种意见和建议。
Python客户端: http://code.google.c
Java客户端: http://code.google.c
ActionScript客户端: http://code.google.c
目录
API Key
为了保护豆瓣用户的数据；防止API被滥用或恶意使用，豆瓣要求每个API的使用者申请一个API Key, 而每个API Key唯一标识一个API使用者. 你可以在申请页面获得API Key， 在页面中填写必要信息后提交，你会得到你的API Key，例如
c4579586f41a90372f762cb65c78be5d
在之后的API使用过程中，你需要在请求中包括apikey参数，例如
http://api.douban.com/people/1345767?apikey={apikey}
注：如果只是想试验一下API，豆瓣也允许在不申请API Key的情况下进行API调用。不过在这种情况下，API调用被限制为每分钟请求不超过10次。使用API Key时，对访问的限制较为宽松，为每分钟40次，超过限制的话会被封禁(包括豆瓣主站的访问)。
快速入门
示例
下面通过一个简单的示例来演示豆瓣API的使用.
这个示例中展示了使用API获得ID为1220562的书的信息, 请求的url如下（注意将{yourapikey}替换为你的API Key）
http://api.douban.com/book/subject/1220562?apikey={yourkeyapi}
返回值为XML文档
<?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:gd="http://schemas.google.com/g/2005" xmlns:opensearch="http://a9.com/-/spec/opensearchrss/1.0/" xmlns:db="http://www.douban.com/xmlns/"> <category scheme="http://www.douban.com/2007#kind" term="http://www.douban.com/2007#book" /> <db:tag count="20" name="片山恭一" /> <db:tag count="14" name="日本" /> <db:tag count="10" name="小说" /> <db:tag count="8" name="日本文学" /> <db:tag count="4" name="爱情" /> <title>满月之夜白鲸现</title> <author> <name>（日）片山恭一</name> </author> <content> 冷静地想一想吧！公寓的一个房间里只有两上人，连被褥都铺好了，理应是犯 错误的时候，我为什么却这么拘谨？一直胆小的毛病又犯了。事到如今，不要 说上床，就连接吻也还差得很远。这就是横亘在男人和女人之间的又深又暗的 河流吗？ 如果有可能，我希望把手伸进她的心里，把她内心所有的东西都掏出来。她对 我究竟是一种什么感觉呢？我在她的心昊确实占有一席之地吗？抑或只是她生 命中的匆匆过客？ </content> <link rel="self" href="http://api.douban.com/book/subject/1220562" /> <link rel="alternate" href="http://www.douban.com/subject/1220562/" /> <link rel="image" href="http://otho.douban.com/spic/s1747553.jpg" /> <db:attribute name="author">（日）片山恭一</db:attribute> <db:attribute name="isbn10">7543632608</db:attribute> <db:attribute name="isbn13">9787543632608</db:attribute> <db:attribute name="pages">180</db:attribute> <db:attribute name="tranlator">豫人</db:attribute> <db:attribute name="price">18.00</db:attribute> <db:attribute name="publisher">青岛出版社</db:attribute> <db:attribute name="binding">平装(无盘)</db:attribute> <db:attribute name="author-intro"> 片山恭一，1959年生于日本爱媛县，九州大学农学系农业经济学专业毕业。 学生时代通读了包括夏目漱石和大江健三郎在内的日本近现代文学全集， 同时读了笛卡尔、莱布尼茨到结构主义的欧洲近现代哲学。也读了马克思。 学士论文写的是马克思，硕士论文写的是恩格斯。二十二三岁开始创作小说。 代表作有《在世界中心呼唤爱》、《世界在你不知道的地方运转》、《气息》、 《别相信约翰·列侬》、《满月之夜白鲸现》、《空镜头》以及新作 《倘若我在彼岸》、《雨天的海豚们》等。 </db:attribute> <id>http://api.douban.com/book/subject/1220562</id> <gd:rating min="1" numRaters="39" average="3.69" max="5" /> </entry>
通过请求中包括alt参数，你可以改变返回值的格式。 目前支持的alt参数值包括：
- atom (默认)
- json
通过将alt设置为json来获得json格式的返回值:
{"category":{
"@scheme":"http://www.douban.com/2007#kind",
"@term":"http://www.douban.com/2007#book"},
"db:tag":[
{"@count":20,"@name":"片山恭一"},
{"@count":14,"@name":"日本"},
{"@count":10,"@name":"小说"},
{"@count":8,"@name":"日本文学"},
{"@count":4,"@name":"爱情"}
],
"title":{"$t":"满月之夜白鲸现"},
"author":[
{"name":{"$t":"（日）片山恭一"}}
],
"content":{"$t":"冷静地想一想吧！公寓的一个房间里只有两上人，连被褥都铺
好了，理应是犯错误的时候，我为什么却这么拘谨？一直胆小的毛病又犯了。事到
如今，不要说上床，就连接吻也还差得很远。这就是横亘在男人和女人之间的又深
又暗的河流吗？\n 如果有可能，我希望把手伸进她的心里，把她内心所有的东
西都掏出来。她对我究竟是一种什么感觉呢？我在她的心昊确实占有一席之地吗？
抑或只是她生命中的匆匆过客？"},
"link":[
{"@rel":"self","@href":"http://api.douban.com/book/subject/1220562"},
{"@rel":"alternate","@href":"http://www.douban.com/subject/1220562/"},
{"@rel":"image","@href":"http://otho.douban.com/spic/s1747553.jpg"}
],
"db:attribute":[
{"$t":"（日）片山恭一","@name":"author"},
{"$t":"7543632608","@name":"isbn10"},
{"$t":"9787543632608","@name":"isbn13"},
{"$t":"180","@name":"pages"},
{"$t":"豫人","@name":"tranlator"},
{"$t":"18.00","@name":"price"},
{"$t":"青岛出版社","@name":"publisher"},
{"$t":"平装(无盘)","@name":"binding"},
{"$t":"片山恭一，1959年生于日本爱媛县，九州大学农学系农业经济学专业
毕业。学生时代通读了包括夏目漱石和大江健三郎在内的日本近现代文学全集，
同时读了笛卡尔、莱布尼茨到结构主义的欧洲近现代哲学。也读了马克思。
学士论文写的是马克思，硕士论文写的是恩格斯。二十二三岁开始创作小说。
代表作有《在世界中心呼唤爱》、《世界在你不知道的地方运转》、《气息》、
《别相信约翰·列侬》、《满月之夜白鲸现》、《空镜头》以及新作《倘若我在
彼岸》、《雨天的海豚们》等。","@name":"author-intro"}
],
"id":{"$t":"http://api.douban.com/book/subject/1220562"},
"gd:rating":{"@min":1,"@numRaters":39,"@average":"3.69","@max":5}
}
JavaScript 支持
对于JavaScript开发人员，豆瓣API提供一种更简单的方式可以直接在HTML页面中使用API, 下面给出这种使用方式的简单示例。
首先你需要在HTML页面中如下script标签:
<script type="text/javascript" src="http://www.douban.com/js/api.js?v=2" />
之后你需要在javascript中设置好你的apikey:
DOUBAN.apikey = 'c4579586f41a90372f762cb65c78be5d'
而后你就可以调用豆瓣API，其中通过定义callback函数来操作返回的JSON数据:
DOUBAN.getMovie({
id:'2340927',
callback:function(movie){
var title = movie.title['$t'];
...
}
})
此外，豆瓣也提供了解析函数来帮助你更容易地使用JSON格式的返回值。使用豆瓣提供的解析函数，你需要在页面中添加如下的script标签：
<script type="text/javascript" src="http://www.douban.com/js/api-parser.js?v=1"></script>
接下来你就可以使用豆瓣提供的解析函数来处理返回值，例如：
var book = DOUBAN.parseSubject(result)
解析函数返回更容易使用的javascript对象，例如你可以这样得到书的封面图片：
book.link.image
下面HTML页面使用API获得ID为2340927电影的信息并展示在页面上（注意将{yourapikey}替换为你的API Key）
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML xmlns="http://www.w3.org/1999/xhtml">
<HEAD>
<TITLE></TITLE>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<style>
body {padding:0;margin: 0;background: #FEFEFE;}
body,td,th { font: 12px Arial, Helvetica, sans-serif; line-height: 150%; }
span.title {
margin:5px;
}
</style>
<script type="text/javascript" src="http://www.douban.com/js/api.js?v=2"></script>
<script type="text/javascript" src="http://www.douban.com/js/api-parser.js?v=1"></script>
<BODY>
</BODY>
<script>
DOUBAN.apikey = {yourapikey}
DOUBAN.getMovie({
id:'2340927',
callback:function(re){
var subj = DOUBAN.parseSubject(re)
var tl = subj.title ? subj.title : "";
var author = subj.author ? subj.author : "";
var di = subj.attribute.director ? subj.attribute.director.join(' / ') : "";
var tmp = "<img src="+subj.link.image+" style='margin:10px;float:left'>";
tmp += "<div>Title : <a href="+subj.link.alternate+" target='_blank'>"+tl+"</a></div>";
if (subj.attribute.author) tmp += "<div>Authors : "+(subj.attribute.author.join(' / '))+"</div>";
if (subj.attribute.director) tmp += "<div>Director : "+(subj.attribute.director.join(' / '))+"</div>";
if (subj.attribute.cast) tmp += "<div>Casts : "+(subj.attribute.cast.join(' / '))+"</div>";
if (subj.attribute.aka) tmp += "<div>A.k.a : "+(subj.attribute.aka.join(' <br/> '))+"</div>";
if (subj.attribute.language) tmp += "<div>Language : "+(subj.attribute.language.join(' / '))+"</div>";
if (subj.attribute.country) tmp += "<div>Country : "+(subj.attribute.country.join(' / '))+"</div>";
if (subj.rating.average)
tmp +="<div>Rating: "+subj.rating.average+" / "+subj.rating.numRaters+decodeURI("%E4%BA%BA")+ "</div>"
tmp += "<p>"+(subj.summary ? subj.summary : "")+"</p>";
document.body.innerHTML = tmp;
}
})
</script>
</HTML>
注：实现上，豆瓣API使用 JSONP 方式来支持跨域调用API 因此你也可以使用自己熟悉的javascript库来调用JSONP风格的豆瓣API. 此时，你需要将alt设置为xd同时提供callback参数。
例如使用JQuery，前面的例子则可以写为
$.getJSON("http://api.douban.com/movie/subject/2340927?alt=xd&callback=?", function(movie){
var title = movie.title['$t'];
...
});
