豆瓣 API 快速入门

豆瓣 API 快速入门

本文档为需要快速了解豆瓣API的用户提供一个概览, 更为完整的豆瓣API信息请参阅 豆瓣API 参考手册。

如果你编写了一个有趣的API应用，欢迎到API小组发布, 另外也欢迎到API小组参与豆瓣API的讨论，提出你对豆瓣API各种意见和建议。

快速入门

下面通过一个简单的示例来演示豆瓣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://book.douban.com/subject/1220562/" />
    <link rel="image" href="http://t.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参数值包括：

通过将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://book.douban.com/subject/1220562/"},
        {"@rel":"image","@href":"http://t.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}
}

豆瓣API 客户端

Python客户端

google code douban-python项目

Java客户端

google code douban-java项目

PHP客户端

google code douban-php-client项目

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'];
    ...
});

豆瓣 API 参考手册

本文档提供豆瓣 API 的详细说明， 建议你在阅读本文档之前，先阅读豆瓣 API 使用指南来快速了解豆瓣 API。

豆瓣 API 遵循 Atom 和 GData 规范，了解这两个规范有助于你更好地使用豆瓣 API。不过这不是必须的。 Atom 和 GData 规范的详细信息可以参阅The Atom Syndication Format 和 Google Data APIs。

API进行增删改操作时，需要进行OAuth认证，详见API OAuth认证。

目录