Twitter API中文文档

目前的国内的微博客很多，不少微博客都提供Open API ，然而，很多微博提供的API 和Twitter 的API 有一些或多或少的差别，调用格式上并不完全相同。

　 　我建议所有提供API 的微博客系统，都将各自的API 统一为Twitter 的API 调用格式，例如目前较有影响的开源微博系统 StatusNet （Laconica ）的API 格式就完全兼容Twitter ，这种统一API 对于开发者和用户都有很大的好处。对于开发者，针对某一个 微博的应用可以快速移植到另一个微博，节省开发时间。对于用户，用户可以自定义客户端应用程序，只要换一下API 地址，就能使用同一个应用程序，来访问各 个不同的微博。例如目前很多人通过StatusNet 的客户端来访问Twitter 一样，使用起来很方便。

　　Twitter 的API 具体是什么格式的呢？根据Twitter API 文档 和新浪微博开放平台的文档，这里提供了一个Twitter API 的中文翻译文档，供开发者们参考。

　

Twitter 开放API 文档

　

　　Twitter 通过API 的方式开放一些应用接口，这篇文档用来介绍Twitter 目前开放的接口，为希望开发基于Twitter 服务扩展的工具或应用的开发人员提供技术和文档服务。

　　认证

　　除了部分API( 如：公共时间线 ( public timeline ) ) 外，所有的API 方法都必须要求用户认证，所有的返回都与认证用户相关。例如，尝试获取一个设置为私密的且不是您的好友的用户信息时，将会返回失败状态。

　　Twitter 目前仅支持HTTP Basic Authentication 验证机制。当使用HTTP Basic Authentication 时，请使用您在Twitter 注册的“ 用户名” 作为Session 或Cookie 的“ 用户名” 部分的内容。

　　多状态[RESTFull] 结果传输

　　Twitter API 力求根据用户特定的请求返回对应特定格式的数据，您可以发现我们提供的API 中有一个重要的便利之处，通过简单的更改URI 中的文件后缀名，您可以获得您想要的返回结果的格式，这篇文档中将说明每个方法中有哪些格式可以用。

　　Twitter 目前支持以下的四种数据返回格式：XML 、JSON 、RSS 、Atom ，您可以在每次请求时使用不同的请求方法指定不同的返回结果。

　　参数

　　一些API 接受可选和必须的参数，当参数可用时，我们会在接下来的文档中提到这些参数。注意：当传送复杂字串时，请一定先将字串编码为UTF-8 格式，并再做一次URL 编码 ( Encode ) 。

　　HTTP 请求

　　除非特意指明，Twitter 的开放API 通过HTTP GET 方式的调用，需要提交信息或传送私密消息时使用POST 方法。

　 　以下将说明API 返回的信息格式的组成，一些API 将返回与用户请求“ 内容” 相关的信息，而有一些将返回与客户端发送的“HTTP 头信息” 相关的一些信 息。例如，多数支持since 参数的方法，同样会对HTTP 头中的If-Modified-Since 这个 HTTP 头 感兴趣。需要注意的是，当某些行为既可以通过参数又可以通过HTTP 头进行控制时，优先接受通过参数方式设定的值。

　　当请求返回数据时，返回数据的编码统一为UTF-8 格式，且我们会将一些外部符号编码为HTML 实体（&#number; 或&text ）格式。

　　限制

　　每一个客户端每小时最多允许150 次请求。

　　HTTP 状态码

　　Twitter API 会对每次请求返回合适的HTTP 状态。例如，当请求一个不存在的用户信息时，API 会返回404 Not Found ；当一次请求没有被认证并授权时，API 会返回401 Not Authorized 状态。 

　　使用API 的简便方法

　　如果您的系统安装有curl ，您已经有了一个非常强大的使用微博 API 的工具。以下是使用curl 的例子，非常简单： 

　　非授权情况下访问public_timeline ： curl http://api.twitter.com/statuses/public_timeline.xml

　　获取朋友的timeline, 使用认证： curl -u email:password http://api.twitter.com/statuses/friends_timeline.xml

　　仅获取头部信息： curl --head email:password http://api.twitter.com/statuses/friends_timeline.json

　　 用户状态相关方法

　　 statuses/public_timeline

　　返回未设置私密的用户 ( 必须有自定义的用户头像 ) 的最近20 条消息，该方法不需要身份认证。

　　访问地址： http://api.twitter.com/statuses/public_timeline.format

　　支持格式(format) ： xml, json, rss, atom

　　参数列表：

　　无。

　　 statuses/friends_timeline

　　返回最近24 小时内的最新的20 条认证用户及其好友更新的消息。

　　访问地址 ：http://api.twitter.com/statuses/friends_timeline.format

　　支持格式 ( format ) ：xml, json, rss, atom

　　参数列表：

　　since_id: 可选参数（微博信息ID ）. 只返回ID 比since_id 大（比since_id 时间晚的）的微博信息内容。

　　示例: http://api.twitter.com/statuses/friends_timeline.xml?since_id=12345

　　max_id: 可选参数（微博信息ID ）. 返回ID 不大于max_id 的微博信息内容。

　　示例: http://api.twitter.com/statuses/friends_timeline.xml?max_id=54321

　　count: 可选参数. 每次返回的最大记录数，不能超过200 ，默认20.

　　示例: http://api.twitter.com/statuses/friends_timeline.xml?count=5

　　page: 可选参数. 返回结果的页序号。注意：有分页限制。根据用户关注对象发表的数量，通常最多返回1,000 条最新微博分页内容, 默认1

　　示例: http://api.twitter.com/statuses/friends_timeline.xml?page=3

　　 statuses/user_timeline

　　返回认证用户最近24 小时内最新更新的20 条消息，同样，通过给定userIdOrName 参数，可以用来请求其他用户的最近的消息更新。该API 可以不认证。

　　访问地址 ：http://api.twitter.com/statuses/user_timeline.format

　　支持格式 ( format ) ：xml, json, rss, atom

　　参数列表 ：

　　id ： 可选参数. 根据指定用户UID 或微博昵称来返回微博信息。

　　示例: http://api.twitter.com/statuses/user_timeline/12345.xml

　　user_id ： 可选参数. 用户UID ，主要是用来区分用户UID 跟微博昵称一样，产生歧义的时候，特别是在微博昵称为数字导致和用户Uid 发生歧义。

　　示例: http://api.twitter.com/statuses/user_timeline.xml?user_id=1401881

　　screen_name ：可选参数. 微博昵称，主要是用来区分用户UID 跟微博昵称一样，产生歧义的时候。

　　示例: http://api.twitter.com/statuses/user_timeline.xml?screen_name=101010

　　since_id ：可选参数（微博信息ID ）. 只返回ID 比since_id 大（比since_id 时间晚的）的微博信息内容

　　示例: http://api.twitter.com/statuses/user_timeline.xml?since_id=12345

　　max_id: 可选参数（微博信息ID ）. 返回ID 不大于max_id 的微博信息内容。

　　示例: Example: http://api.twitter.com/statuses/user_timeline.xml?max_id=54321

　　count: 可选参数. 每次返回的最大记录数，最多返回200 条，默认20 。

　　示例: http://api.twitter.com/statuses/user_timeline.xml?count=200

　　page ： 可选参数. 分页返回。注意：最多返回200 条分页内容。

　　示例: http://api.twitter.com/statuses/user_timeline.xml?page=3

　　 statuses/mentions

　　显示20 条最近的对用户的回复消息， ( 消息前缀为 @username ) 。该API 只开放给认证用户，请求其他用户的收到的回复消息列表是非法的，无论其他用户设置私密与否。

　　访问地址 ：http://api.twitter.com/statuses/replies.format

　　支持格式 ( format ) ：xml, json, rss, atom

　　参数列表 ：

　　since_id. 可选参数. 返回ID 比数值since_id 大（比since_id 时间晚的）的提到。

　　示例: http://api.twitter.com/statuses/mentions.xml?since_id=12345

　　max_id. 可选参数. 返回ID 不大于max_id( 时间不晚于max_id) 的提到。

　　示例: http://api.twitter.com/statuses/mentions.xml?max_id=54321

　　count. 可选参数. 每次返回的最大记录数（即页面大小），不大于200 ，默认为20 。

　　示例: http://api.twitter.com/statuses/mentions.xml?count=200

　　page. 可选参数. 返回结果的页序号。注意：有分页限制。

　　示例: http://api.twitter.com/statuses/mentions.xml?page=3

　　 用户消息相关方法

　　 statuses/show

　　返回指定Id 的一条消息，返回信息中包含作者信息。

　　访问地址 ：http://api.twitter.com/statuses/show/id.format 或者

　　http://api.twitter.com/statuses/show.format?id={id}

　　支持格式 ( format ) ：xml, json

　　参数列表:

　　id. 必须参数( 微博信息ID) ，要获取已发表的微博ID, 如ID 不存在返回空

　　示例: http://api.twitter.com/statuses/show/142277.xml

　　 statuses/update

　　更新认证用户的消息，必须包含content 参数，且必须以POST 方式请求。 成功时按指定格式返回当前的消息。

　　访问地址： http://api.twitter.com/statuses/update.format

　　支持格式 ( format ) ：xml, json

　　参数列表:

　　status. 必填参数， 要更新的微博信息。必须做URLEncode, 信息内容部超过140 个汉字, 为空返回400 错误。

　　in_reply_to_status_id. 可选参数，@ 需要回复的微博信息ID, 这个参数只有在微博内容以 @username 开头才有意义。

　　lat. 可选参数，纬度，发表当前微博所在的地理位置，有效范围 -90.0 到+90.0, + 表示北纬。只有用户设置中geo_enabled=true 时候地理位置才有效。

　　long. 可选参数，经度。有效范围-180.0 到+180.0, + 表示东经。

　　 statuses/destroy

　　根据指定的id 删除一条消息，认证用户必须是消息的作者。

　　访问地址 ：http://api.twitter.com/statuses/destroy/id.format

　　支持格式 ( format ) ：xml, json

　　参数列表:

　　id 必须，待删除的消息Id ， 例如：

　　http://api.twitter.com/statuses/destroy/12345.json

　　或者

　　http://api.twitter.com/statuses/destroy.xml?id=23456

　　 用户操作接口

　　 users/show

　　显示指定用户的扩展信息，需要给定用户的id 或显示名称。扩展信息包括用户的页面设置、微博次数等，因此第三方应用的开发者可以根据这些信息为用户提供合适的主题。

　　注意：本API 调用请求必须发自合法微博用户，不论请求自己/ 他人的扩展信息。

　　访问地址 ：http://api.twitter.com/users/show.format

　　支持格式 ( format ) ：xml, json

　　参数列表：

　　id. 用户UID 或微博昵称。

　　示例: http://api.twitter.com/users/show/12345.json 或 http://api.twitter.com/users/show/bob.xml

　　user_id. 指定用户UID, 主要是用来区分用户UID 跟微博昵称一样，产生歧义的时候，特别是在用户账号为数字导致和用户Uid 发生歧义。

　　示例: http://api.twitter.com/users/show.xml?user_id=1401881

　　screen_name. 指定微博昵称，主要是用来区分用户UID 跟微博昵称一样，产生歧义的时候。

　　示例: http://api.twitter.com/users/show.xml?screen_name=101010

　　 statuses/friends

　　返回认证用户的朋友列表，内含每个用户的当前微博信息。这个方法同样可以用来请求其他用户的朋友列表，通过下面指明的方法传递id 参数。

　　访问地址 ：http://api.twitter.com/statuses/friends.format

　　支持格式 ( format ) ：xml, json

　　参数列表:

　　id. 选填参数. 要获取的 UID 或微博昵称

　　示例: http://api.twitter.com/statuses/friends/12345.json

　　http://api.twitter.com/statuses/friends/12345.xml

　　user_id. 选填参数. 要获取的UID

　　示例: http://api.twitter.com/statuses/friends.xml?user_id=1401881

　　screen_name. 选填参数. 要获取的微博昵称

　　示例: http://api.twitter.com/statuses/friends.xml?screen_name=101010

　　cursor. 选填参数. 单页只能包含100 个关注列表，为了获取更多则cursor 默认从-1 开始，通过增加或减少cursor 来获取更多, 如果没有下一页，则next_cursor 返回0

　　的关注列表

　　示例: http://api.twitter.com/statuses/friends/williamlong.xml?cursor=-1

　　示例: http://api.twitter.com/statuses/friends/williamlong.xml?cursor=1300794057949944903

　　count. 可选参数. 每次返回的最大记录数（即页面大小），不大于200, 默认返回20 。

　　示例: http://api.twitter.com/statuses/friends/bob.xml?&count=200

　　 statuses/followers

　　返回认证用户的订阅者，内含每个订阅者的当前消息。与friends 一样，只需要把friends 地址中的friends 替换为followers 即可，其余一切包括参数都不需要改变，都是一样的用法。

　　访问地址： http://api.twitter.com/statuses/followers.format

　　支持格式 ( format ) ：xml, json

　　参数列表:

　　id. 选填参数. 要获取粉丝的 UID 或微博昵称

　　示例: http://api.twitter.com/statuses/followers/12345.json or http://api.twitter.com/statuses/followers/bob.xml

　　user_id. 选填参数. 要获取的UID

　　示例: http://api.twitter.com/statuses/followers.xml?user_id=1401881

　　screen_name. 选填参数. 要获取的微博昵称

　　示例: http://api.twitter.com/statuses/followers.xml?screen_name=101010

　　cursor. 选填参数. 单页只能包含100 个粉丝列表，为了获取更多则cursor 默认从-1 开始，通过增加或减少cursor 来获取更多的，如果没有下一页，则next_cursor 返回0

　 　粉丝列表 示例: http://api.twitter.com/statuses/followers/barackobama.xml?cursor=-1 示例: http://api.twitter.com/statuses/followers/barackobama.xml?cursor=1300794057949944903

　　count. 可选参数. 每次返回的最大记录数（即页面大小），不大于200, 默认返回20 。

　　示例: http://api.twitter.com/statuses/followers/bob.xml?&count=200

　　 私信操作方法

　　 direct_messages

　　返回用户的消息列表

　　访问地址： http://api.twitter.com/direct_messages.format

　　支持格式 ( format ) ：xml, json, rss, atom

　　参数列表:

　　since_id. 可选参数. 返回ID 比数值since_id 大（比since_id 时间晚的）的私信。

　　示例: http://api.twitter.com/direct_messages.xml?since_id=12345

　　max_id. 可选参数. 返回ID 不大于max_id( 时间不晚于max_id) 的私信。

　　示例: http://api.twitter.com/direct_messages.xml?max_id=54321

　　count. 可选参数. 每次返回的最大记录数（即页面大小），不大于200 。

　　示例: http://api.twitter.com/direct_messages.xml?count=200

　　page. 可选参数. 返回结果的页序号。注意：有分页限制。

　　示例: http://api.twitter.com/direct_messages.xml?page=3

　　 direct_messages/sent

　　返回用户的已发送消息列表

　　访问地址： http://api.twitter.com/direct_messages/sent.format

　　支持格式 ( format ) ：xml, json, rss, atom

　　参数列表:

　　since_id. 可选参数. 返回ID 比数值since_id 大（比since_id 时间晚的）的私信。

　　示例: http://api.twitter.com/direct_messages.xml?since_id=12345

　　max_id. 可选参数. 返回ID 不大于max_id( 时间不晚于max_id) 的私信。

　　示例: http://api.twitter.com/direct_messages.xml?max_id=54321

　　count. 可选参数. 每次返回的最大记录数（即页面大小），不大于200 。

　　示例: http://api.twitter.com/direct_messages.xml?count=200

　　page. 可选参数. 返回结果的页序号。注意：有分页限制。

　　 direct_messages/new

　　以认证用户的身份向指定的其他用户发送一条有向消息，必须包含参数user 和text, 请求必须使用POST 方式提交。成功将返回完整的发送消息必须包含参数user 和text ，必须使用POST 方式提交。成功将返回完整的发送消息。

　　访问地址 ：http://api.twitter.com/direct_messages/new.format

　　支持格式 ( format ) ：xml, json

　　参数列表：

　　user: user_id 或者screen_name

　　text: 必须参数. 要发生的消息内容，需要做URLEncode ，文本大小必须小于300 个汉字

　　 direct_messages/destroy

　　       通过给定的消息id ，删除指定的有向消息，认证用户只能删除其作为接受者收到的消息。使用POST 和GET 方法都可以
访问地址： http://api.twitter.com/direct_messages/destroy/id.format

　　支持格式 ( format ) ：xml, json

　　参数列表：

　　id. 必填参数，要删除的私信主键ID.

　　示例: http://api.twitter.com/direct_messages/destroy/12345.json

　　 好友关系操作方法

　　 friendships/create

　　创建认证用户与给定的id 参数指定的用户之间的好友关系；该操作执行成功时返回被加为好友的用户信息，执行失败则返回失败的状态字串。

　　访问地址： http://api.twitter.com/friendships/create/id.format

　　支持格式 ( format ) ：xml, json

　　参数列表：

　　下面的参数必须有其中一个:

　　id. 必填参数. 要关注的用户UID 或微博昵称

　　示例: http://api.twitter.com/friendships/create/12345.json or http://api.twitter.com/friendships/create/bob.xml

　　user_id. 必填参数. 要关注的用户UID, 主要是用在区分用户UID 跟微博昵称一样，产生歧义的时候。

　　示例: http://api.twitter.com/friendships/create.xml?user_id=1401881

　　screen_name. 必填参数. 要关注的微博昵称, 主要是用在区分用户UID 跟微博昵称一样，产生歧义的时候。

　　示例: http://api.twitter.com/friendships/create.xml?screen_name=101010

　　follow. 可选参数。暂不支持。

　　 friendships/destroy

　　用来注销同指定id 的用户的好友关系，当操作成功时，将返回被取消好友关系的用户，当失败时，将会返回失败信息。

　　访问地址 ：http://api.twitter.com/friendships/destroy/id.format

　　支持格式 ( format ) ：xml, json

　　参数列表：

　　下面的参数必须有其中一个:

　　id. 必填参数. 要取消关注的用户UID 或微博昵称

　　示例: http://api.twitter.com/friendships/destroy/12345.json or http://api.twitter.com/friendships/destroy/bob.xml

　　user_id. 必填参数. 要取消关注的用户UID, 主要是用在区分用户UID 跟微博昵称一样，产生歧义的时候。

　　示例: http://api.twitter.com/friendships/destroy.xml?user_id=1401881

　　screen_name. 必填参数. 要取消的微博昵称, 主要是用在区分用户UID 跟微博昵称一样，产生歧义的时候。

　　示例: http://api.twitter.com/friendships/destroy.xml?screen_name=101010

　　 friendships/exists

　 　用来检验两个用户的关系是否是朋友关系或者跟随与被跟随的关系。返回相互跟随的关系结果。比如：A 跟随了B 。B 没有跟随A 。将返回对应的格式数据：如 xml ，<result><AFollowB>true</AFollowB><BFollowA>false< /BFollowA></result>

　　访问地址： http://api.twitter.com/friendships/exists.format

　　支持格式： xml, json

　　参数列表：

　　user_a. 必填参数，要判断的用户UID

　　user_b. 必填参数，要判断的被关注人用户UID

　　 friendships/show

　　返回两个用户关系的详细情况

　　访问地址： http://api.twitter.com/friendships/show.format

　　支持格式： xml, json

　　参数列表：

　　以下参数可不填写，如不填，则取当前用户

　　source_id. 源用户UID

　　示例: http://api.twitter.com/friendships/show.xml?source_id=10502

　　source_screen_name. 源微博昵称

　　示例: http://api.twitter.com/friendships/show.xml?source_screen_name=bob

　　下面参数必须选填一个:

　　target_id. 要判断的目的用户UID

　　示例: http://api.twitter.com/friendships/show.xml?target_id=10503

　　target_screen_name. 要判断的目的微博昵称

　　示例: http://api.twitter.com/friendships/show.xml?target_screen_name=williamlong

　　 获取用户列表方法

　　 friends/ids

　　用来获取指定的用户的朋友用户id 。即自己跟随的人的id

　　访问地址 ：http://api.twitter.com/friends/ids.format

　　支持格式： xml, json

　　参数列表：

　　id. 选填参数. 要获取好友的UID 或微博昵称

　　示例: http://api.twitter.com/friends/ids/12345.xml or http://api.twitter.com/statuses/friends/bob.xml

　　user_id. 选填参数. 要获取的UID

　　示例: http://api.twitter.com/friends/ids.xml?user_id=1401881

　　screen_name. 选填参数. 要获取的微博昵称

　　示例: http://api.twitter.com/friends/ids.xml?screen_name=101010

　　cursor. 选填参数. 单页只能包含5000 个id ，为了获取更多则cursor 默认从-1 开始，通过增加或减少cursor 来获取更多的关注列表

　　示例: http://api.twitter.com/friends/ids.xml?cursor=-1 示例: http://api.twitter.com/friends/ids.xml?cursor=1300794057949944903

　　count. 可选参数. 每次返回的最大记录数（即页面大小），不大于5000 ，默认返回500 。

　　示例: http://api.twitter.com/friends/ids.xml?count=200

　　 followers/ids

　　用来获取指定的用户被跟随的用户id 。

　　访问地址 ：http://api.twitter.com/followers/ids.format

　　支持格式： xml,json

　　参数列表：

　　id. 选填参数. 要获取好友的UID 或微博昵称

　　示例: http://api.twitter.com/followers/ids/12345.xml or http://api.twitter.com/statuses/friends/bob.xml

　　user_id. 选填参数，要获取的UID

　　示例: http://api.twitter.com/followers/ids.xml?user_id=1401881

　　screen_name. 选填参数，要获取的微博昵称

　　示例: http://api.twitter.com/followers/ids.xml?screen_name=101010

　　cursor. 选填参数. 单页只能包含5000 个id ，为了获取更多则cursor 默认从-1 开始，通过增加或减少cursor 来获取更多的关注列表

　　示例: http://api.twitter.com/followers/ids.xml?cursor=-1

　　示例: http://api.twitter.com/followers/ids.xml?cursor=1300794057949944903

　　count. 可选参数. 每次返回的最大记录数（即页面大小），不大于5000 ，默认返回500 。

　　示例: http://api.twitter.com/followers/ids.xml?count=200

　　 用户帐号方法

　　 account/verify_credentials

　　如果用户身份验证成功则返回 http 状态为 200 ；如果是不则返回401 的状态和错误信息。此方法用了判断用户身份是否合法。

　　访问地址： http://api.twitter.com/account/verify_credentials.format

　　支持格式： xml, json

　　参数列表：

　　 account/update_profile

　　自定义微博页面的参数。只会修改参数更新项。

　　访问地址： http://api.twitter.com/account/update_profile.format

　　支持格式： xml, json

　　参数列表：

　　必须有一下参数中的一个或多个，参数值为字符串. 进一步的限制，请参阅下面的各个参数描述.

　　name. 昵称，可选参数. 不超过20 个汉字

　　gender 性别，可选参数. m, 男，f, 女。

　　province 可选参数. 参考省份城市编码表

　　city 可选参数. 参考省份城市编码表,1000 为不限

　　description. 可选参数. 不超过160 个汉字.

　　 收藏相关方法

　　 favorites

　　返回授权用户的最新的20 条收藏的状态信息。也可以通过id 或者用户名来指定一个用户，查询他最新的20 条收藏的状态信息。

　　访问地址 ：http://api.twitter.com/favorites.format

　　支持格式： xml, json, rss, atom

　　参数列表：

　　page ： 可选参数. 返回结果的页序号。注意：有分页限制。

　　示例: http://api.twitter.com/favorites/11075.xml?page=3

　　 favorites/create

　　收藏一条状态信息POST 提交

　　访问地址：

　　http://api.twitter.com/favorites/create.format

　　支持格式： xml, json

　　参数列表：

　　id 必须，授权用户要收藏的状态信息id 。

　　 favorites/destroy

　　删除授权用户收藏的一条状态信息

　　访问地址 ：http://api.twitter.com/favorites/destroy/id.format

　　支持格式： xml, json

　　参数列表：

　　id 授权用户收藏的状态信息id 。