广播数据集接口

获取当前登录用户及其所关注用户的最新广播

说明

获取当前登录用户及其所关注用户的最新广播消息。

URL

shuo/statuses/home_timeline

支持格式

JSON

HTTP请求方式

GET

请求参数

必选类型及范围说明
since_idfalseint64若指定此参数,则只返回ID比since_id大的广播消息(即比since_id发表时间晚的广播消息)。
until_idfalseint64若指定此参数,则返回ID小于或等于until_id的广播消息
countfalseint默认20,最大200
categoryfalsestringarticle: 9点、日记、小组话题; photo: 相册、照片; culture: 书影音;shopping: 团购、优惠券

调用示例

shuo/statuses/home_timeline?until_id=57983275

返回结果

[
    {
        "created_at" : "Tue Nov 30 16:21:13 +0800 2010",
        "text" : "转发广播。",
        "retshared_status" : 
        {
            "created_at" : "Tue Nov 30 16:05:41 +0800 2010",
            "text" : "基本结构是这样 但不包括所有广播类型。",
            "user" : 
            {
                "followers_count" : 66710,
                "statuses_count" : 77,
                "favourites_count" : 0,
                "city" : "1",
                "description" : "心存慈悲 身奉善行 出世入世 修己助人",
                "id" : 1799833402,
                "following_count" : 4,
                "screen_name" : "归元隆印",
                "following" : false,
                "url" : "http://www.guiyuanchansi.net",
                "icon" : "http://img3.douban.com/icon/u2728291-2.jpg",
                "created_at" : "Tue Aug 24 00:00:00 +0800 2010",
                "country" : "42",
                "location" : "湖北 武汉"
            },
            "favorited" : false,
            "id" : 3980364843,
            "source" : "<a href=\"http://t.douban.com\" rel=\"nofollow\">豆瓣广播</a>"
        },
        "user" : 
        {
            "followers_count" : 56,
            "statuses_count" : 333,
            "favourites_count" : 1,
            "city" : "5",
            "description" : "在这里,我只管把话发出去,有没有人理就不管我的事了!",
            "signature" : "",
            "id" : 1799824787,
            "friends_count" : 76,
            "screen_name" : "半拉拖鞋",
            "following" : false,
            "url" : "http://blog.sina.com.cn/lingdianjingq",
            "icon" : "http://img3.douban.com/icon/u1000037-7.jpg",
            "created_at" : "Sun Sep 05 00:00:00 +0800 2010",
            "country" : "11",
            "location" : "北京 朝阳区"
        },
        "favorited" : false,
        "id" : 3980654229,
        "source" : "<a href=\"http://t.douban.com\" rel=\"nofollow\">豆瓣广播</a>"
    },
...
]

获取用户发布的广播列表

说明

返回用户最新发表的广播消息列表。

URL

shuo/statuses/user_timeline/:user_id
或者:
shuo/statuses/user_timeline/@me

支持格式

JSON

HTTP请求方式

GET

请求参数

必选类型及范围说明
:idfalseint64根据用户ID(int64)或者uid(string)返回指定用户的最新广播消息列表。该参数为REST风格参数,参见注意事项
since_idfalseint64若指定此参数,则只返回ID比since_id大(即比since_id发表时间晚的)的广播消息。
until_idfalseint64若指定此参数,则返回ID小于或等于until_id的广播消息

* 如果:id、user_id、screen_name三个参数均未指定,则返回当前登录用户最近发表的广播消息列表。*

调用示例

shuo/satuses/user_timeline/2770683

*返回结果(JSON示例) *

[
    {
        "created_at" : "Mon Nov 29 16:08:43 +0800 2008",
        "text" : "豆瓣新广播",
        "user" : 
        {
            "name" : "倔倔",
            "followers_count" : 13034,
            "statuses_count" : 157,
            "favourites_count" : 0,
            "city" : "8",
            "description" : "这里是豆瓣新广播数据接口文档",
            "id" : 2770683,
            "friends_count" : 5,
            "screen_name" : "imdonkey",
            "allow_all_act_msg" : true,
            "following" : false,
            "url" : "http://www.imdonkey.com/",
            "profile_image_url" : "http://img3.douban.com/icon/ul2770683-11.jpg",
            "created_at" : "Wed Jan 20 00:00:00 +0800 2010",
            "province" : "11",
            "location" : "北京 朝阳区"
        },
        "favorited" : false,
        "id" : 3958728723,
        "source" : ""
    },
...
]

获取@当前用户的广播和回应列表

说明

  • 返回最新n条提到登录用户的广播消息(即包含@username的广播消息)
  • 还有提到用户的回复

URL

shuo/statuses/mentions

支持格式

JSON

HTTP请求方式

GET

请求参数

必选类型及范围说明
since_idfalseint64若指定此参数,则只返回ID比since_id大的提到当前登录用户的广播消息(比since_id发表时间晚)。
until_idfalseint64若指定此参数,则返回ID小于或等于until_id的提到当前登录用户广播消息
countfalseint默认20,最大200

调用示例

shuo/statuses/mentions?max_id=5829382

返回结果

 [     
{
    'id': 9879834751934,
    'create_at': '2011-03-02 09:31:33',
    'unread': True,
    'status': {
        "created_at" : "Tue Nov 30 16:21:13 +0800 2010",
        "text" : "这是一条@XXX的广播。",
        "user" : 
           {
                               "followers_count" : 56,
                              "statuses_count" : 333,
                              "favourites_count" : 1,
                              "city" : "5",
                              "description" : "在这里,我只管把话发出去,有没有人理就不管我的事了!",
                              "signature" : "",
                              "id" : 1799824787,
                              "friends_count" : 76,
                              "screen_name" : "半拉拖鞋",
                              "following" : false,
                              "url" : "http://blog.sina.com.cn/lingdianjingq",
                              "icon" : "http://img3.douban.com/icon/u1000037-7.jpg",
                              "created_at" : "Sun Sep 05 00:00:00 +0800 2010",
                              "country" : "11",
                              "location" : "北京 朝阳区"
                          },
                "favorited" : false,
                "id" : 3980654229,
                "source" : "<a href=\"http://t.douban.com\" rel=\"nofollow\">豆瓣广播</a>"
           },
           'comment': {
                 'id': 984719285,
                 'text': '这是一条在XX广播中 @XX 的回复',
                 "user" : 
                          {
                              "followers_count" : 56,
                              "statuses_count" : 333,
                              "favourites_count" : 1,
                              "city" : "5",
                              "description" : "在这里,我只管把话发出去,有没有人理就不管我的事了!",
                              "signature" : "",
                              "id" : 1799824787,
                              "friends_count" : 76,
                              "screen_name" : "半拉拖鞋",
                              "following" : false,
                              "url" : "http://blog.sina.com.cn/lingdianjingq",
                              "icon" : "http://img3.douban.com/icon/u1000037-7.jpg",
                              "created_at" : "Sun Sep 05 00:00:00 +0800 2010",
                              "country" : "11",
                              "location" : "北京 朝阳区"
                          },
                  'status': {
                           "created_at" : "Tue Nov 30 16:21:13 +0800 2010",
                           "text" : "这是一条@XXX的广播。",
                           "user" : 
                                              {
                                                   "followers_count" : 56,
                                                  "statuses_count" : 333,
                                                  "favourites_count" : 1,
                                                  "city" : "5",
                                                  "description" : "在这里,我只管把话发出去,有没有人理就不管我的事了!",
                                                  "signature" : "",
                                                  "id" : 1799824787,
                                                  "friends_count" : 76,
                                                  "screen_name" : "半拉拖鞋",
                                                  "following" : false,
                                                  "url" : "http://blog.sina.com.cn/lingdianjingq",
                                                  "icon" : "http://img3.douban.com/icon/u1000037-7.jpg",
                                                  "created_at" : "Sun Sep 05 00:00:00 +0800 2010",
                                                  "country" : "11",
                                                  "location" : "北京 朝阳区"
                                              },
                                    "favorited" : false,
                                    "id" : 3980654229,
                                    "source" : "<a href=\"http://t.douban.com\" rel=\"nofollow\">豆瓣广播</a>"
                          }
           }
     },
     ...
  ]

单条广播接口

读取(或者删除)一条广播

说明

1. 读取一条广播
2. 删除一条广播

URL

shuo/statuses/:id

支持格式

JSON

HTTP请求方式

GET/DELETE
  • GET 为获取单条广播内容

  • DELETE 为删除单条广播,只有删除自己的广播

请求参数

必选类型及范围说明
packfalsebool是否打包 resharers 和 comments 数据

调用示例

shuo/statuses/:id

返回结果

1. 该条广播数据

当 pack 为真时:
2. {"status": 广播数据, "reshare_users": 转播的用户列表, "comments": 评论列表, "like_users": 赞的用户列表}

获取一条广播的回复列表 或者 添加一条评论

说明

操作一条广播的回复(包括获取评论列表和添加评论)

URL

shuo/statues/:id/comments

支持格式

JSON

HTTP请求方式

GET 返回一条广播的回复列表
支持参数:page, count

POST 回复一条广播

调用示例

shuo/statues/:id/comments

返回结果

POST: 返回comment 对象
GET: 返回comment对象列表

获取单条回复的内容或者删除该回复

说明

操作一条回复(获取其内容或者是删除)

URL

shuo/statuses/comment/:id

支持格式

JSON

HTTP请求方式

GET/DELETE
  • GET 为获取单条回复内容(可能没用)
  • DELETE 为删除单条回复,楼主、发帖人、管理员能删除

调用示例

shuo/statuses/comment/:id

返回结果

该条comment数据(包含相关的statuses)

转播

说明

1. 获取一条广播的转发相关信息 GET
2. 转播一条广播信息。请求必须用POST方式提交。
3. 取消转播等价于删除一条广播

URL

shuo/statuses/:id/reshare

支持格式

JSON

HTTP请求方式

GET  获取最近转播的用户列表
POST 转播

调用示例

shuo/statuses/:id/reshare

返回结果

发送成功的广播数据

说明

1. 获取一条广播的赞相关信息 GET
2. 赞一条广播 POST
3. 取消赞 DELETE

URL

shuo/statuses/:id/like

支持格式

JSON

HTTP请求方式

+ GET  获取最近赞的用户列表
+ POST 赞
+ DELETE 取消赞

调用示例

shuo/statuses/:id/like

返回结果

对应的广播数据

发送一条广播

说明

发布一条广播信息。请求必须用POST方式提交。
豆瓣广播类型繁多,但是对外只支持‘我说’和‘推荐网址’两种。

URL

shuo/statuses/

支持格式

JSON

HTTP请求方式

POST
‘我说’类型的广播中如果需要附带图片,注意采用multipart/form-data编码方式上传,上传图片大小限制为<3M,name 是 image

请求参数

必选类型及范围说明
sourcetruestringappkey
texttruestring广播内容
imagefalsebytes我说的图
attachmentsfalsestring描述goods

attachments

attachments是一个json array格式的字符串, array里面的元素称为物, 目前每条广播只支持单个物,物是每条广播表述的行为中的那个宾语,例如: xx推荐网址, 网址就是这个‘物’, 它的结构如下:

title标题,如果传空,会显示‘无标题’, 最大长度100字节(50汉字或100字母)
href链接,url最大长度1024,需要分析并展示网站域名
description描述,可以为空,最大长度200字节(100汉字或200字母)
media富媒体,允许 image, flash, music 单条广播所有[[BR]]图片无最小值限制,文件最大不超过3M[[BR]]缩略图:最大边150px[[BR]]点击展开后:宽度最大460px,高度不限[[BR]]原图大小无宽高限制
caption子标题
type分类,预留字段
properties如果有分类,这里存放对应类别的详细数据,具体的字段由该类别自行定义

== media 类型 ==

image

{"media":[
    { 
        "src": "http://icanhascheezburger.files.wordpress.com/2009/03/funny-pictures-kitten-finished-his-milk-and-wants-a-cookie.jpg", 
        "href": "http://icanhascheezburger.com/2009/03/30/funny-pictures-awlll-gone-cookie-now/",
        "type: "image",
        "sizes": {"small": (160, 160), "media": (400, 900), "raw": (700, 1000)}
    }, 
    {
        "src": "http://photos.icanhascheezburger.com/completestore/2009/1/18/128768048603560273.jpg", 
        "href": "http://ihasahotdog.com/upcoming/?pid=20869",
        "type: "image"
    }]
}

flash

{"media": [{
    "src": "http://www.mapsofwar.com/photos/EMPIRE17.swf", 
    "imgsrc": "http://icanhascheezburger.files.wordpress.com/2009/04/funny-pictures-hairless-cat-phones-    home.jpg", 
    "type": "flash"
}]
}

music

{"media":[{
    "src": "http://www.looptvandfilm.com/blog/Radiohead%20-%20In%20Rainbows/01%20-      %20Radiohead%20-%2015%20Step.MP3", 
    "title": "15 Step", 
    "artist": "Radiohead", 
    "album": "In Rainbows",
    "type": "music"
}]
}

一个例外是如果media是图片,如果图片来自网络,则直接提供url,如下:

{"media": [
    { 
        "type": "image", 
        "src": "http://photos.icanhascheezburger.com/completestore/2009/1/18/128768048603560273.jpg"
        "href": "http://icanhascheezburger.com/2009/03/30/funny-pictures-awlll-gone-cookie-now/"
    }, 
  ]
}

若来自本机上传,这改为:

{"media": [
    { 
        "type": "image",         
        "href": "http://icanhascheezburger.com/2009/03/30/funny-pictures-awlll-gone-cookie-now/"
    }, 
  ]
}

图片的具体对象由单独的pic参数提交,仅支持JPEG,GIF,PNG图片,为空返回400错误。目前上传图片大小限制为<3M

调用示例

shuo/statuses/

返回结果

发送成功的广播数据

用户接口

根据ID获取用户资料

说明

返回一个用户

URL

shuo/users/:id
  • 支持格式 *

    JSON

  • HTTP请求方式 *

    GET

  • 调用示例 *

    shuo/users/:id

    id为@me表示为当前用户

返回结果

返回符合要求的user对象

获取用户关注列表

说明

返回一个用户follow的用户列表
  • URL *

    users/:id/following

  • 支持格式 *

    JSON

  • HTTP请求方式 *

    GET

  • 请求参数 *

    必选类型及范围说明
    tagfalseint该tag的id
  • 调用示例 *

    shuo/users/:id/following

返回结果

返回一个用户follow的用户列表

获取用户关注者列表

说明

返回follow一个用户的用户列表
  • URL *

    users/:id/followers

  • 支持格式 *

    JSON

  • HTTP请求方式 *

    GET

  • 调用示例 *

    shuo/users/:id/followers

返回结果

返回follow一个用户的用户列表

获取共同关注的用户列表

说明

返回共同关注的用户列表
  • URL *

    users/:id/follow_in_common

  • 支持格式 *

    JSON

  • HTTP请求方式 *

    GET

  • 调用示例 *

    shuo/users/:id/follow_in_common

返回结果

返回共同关注的用户列表

获取关注的人关注了该用户的列表

说明

返回当前用户关注的人中也关注了该用户的列表

  • URL *

    users/suggestions

  • 支持格式 *

    JSON

  • HTTP请求方式 *

    GET

  • 调用示例 *

    shuo/users/:id/following_followers_of

返回结果

返回当前用户关注的人中也关注了该用户的列表

搜索用户

说明

搜索用户
  • URL *

    users/search

  • 支持格式 *

    JSON

  • HTTP请求方式 *

    GET

  • 请求参数 *

必选类型及范围说明
qtruestring搜索字符串
  • 调用示例 *

    shuo/users/search?q=ahbei

返回结果

返回符合要求的user列表

block用户

说明

将指定用户加入黑名单
  • URL *

    users/:id/block

  • 支持格式 *

    JSON

  • HTTP请求方式 *

    POST

  • 请求参数 *

必选类型及范围说明
user_idtruestring用户 ID
  • 调用示例 *

    shuo/users/:id/block

返回结果

  • 成功:{"r": 1}
  • 失败:{"r": 0}

关系接口

建立关注

说明

follow一个用户
  • URL *

    friendships/create

  • 支持格式 *

    JSON

  • HTTP请求方式 *

    POST

  • 请求参数 *

必选类型及范围说明
sourcetruestringappkey
user_idtruestring用户id

返回结果

发送follow用户的user对象

取消关注

说明

unfollow一个用户
  • URL *

    friendships/destroy

  • 支持格式 *

    JSON

  • HTTP请求方式 *

    POST

  • 请求参数 *

必选类型及范围说明
sourcetruestringappkey
user_idtruestring用户id

返回结果

发送unfollow用户的user对象

获取两个用户的关系

说明

follow一个用户
  • URL *

    friendships/show

  • 支持格式 *

    JSON

  • HTTP请求方式 *

    GET

  • 请求参数 *

必选类型及范围说明
sourcetruestringappkey
source_idtruestring用户id
target_idtruestring用户id

其中source_id如果没有,则使用当前用户

返回结果

{
 "source": {
    "id": "3407397647969193784",
    "screen_name": "Tux",
    "following": false,
    "followed_by": true
    },
 "target": {
    "id": "-7325997749471485394",
    "screen_name": "001",
    "following": true,
    "followed_by": false
    }
}