Twitter开放API文档

Twitter开放API文档Twitter通过API的方式开放一些应用接口，这篇文档用来介绍Twitter目前开放的接口，为希望开发基于Twitter服务扩展的工具或应用的开发人员提供技术和文档服务。认证除了部分API(如：公共时间线(publictimeline))外，所有的API方法都必须要求用户认证，所有的返回都与认证用户相关。例如，尝试获取一个设置为私密的且不是您的好友的用户信息时，将会返回失败状态。Twitter目前仅支持HTTPBasicAuthentication验证机制。当使用HTTPBasicAuthentication时，请使用您在Twitter注册的“用户名”作为Session或Cookie的“用户名”部分的内容。多状态[RESTFull]结果传输TwitterAPI力求根据用户特定的请求返回对应特定格式的数据，您可以发现我们提供的API中有一个重要的便利之处，通过简单的更改URI中的文件后缀名，您可以获得您想要的返回结果的格式，这篇文档中将说明每个方法中有哪些格式可以用。Twitter目前支持以下的四种数据返回格式：XML、JSON、RSS、Atom，您可以在每次请求时使用不同的请求方法指定不同的返回结果。参数一些API接受可选和必须的参数，当参数可用时，我们会在接下来的文档中提到这些参数。注意：当传送复杂字串时，请一定先将字串编码为UTF-8格式，并再做一次URL编码(Encode)。HTTP请求

除非特意指明，Twitter的开放API通过HTTPGET方式的调用，需要提交信息或传送私密消息时使用POST方法。以下将说明API返回的信息格式的组成，一些API将返回与用户请求“内容”相关的信息，而有一些将返回与客户端发送的“HTTP头信息”相关的一些信息。例如，多数支持since参数的方法，同样会对HTTP头中的If-Modified-Since这个HTTP头感兴趣。需要注意的是，当某些行为既可以通过参数又可以通过HTTP头进行控制时，优先接受通过参数方式设定的值。当请求返回数据时，返回数据的编码统一为UTF-8格式，且我们会将一些外部符号编码为HTML实体（&#number;或&text）格式。限制每一个客户端每小时最多允许150次请求。HTTP状态码TwitterAPI会对每次请求返回合适的HTTP状态。例如，当请求一个不存在的用户信息时，API会返回404NotFound；当一次请求没有被认证并授权时，API会返回401NotAuthorized状态。使用API的简便方法如果您的系统安装有curl，您已经有了一个非常强大的使用微博API的工具。以下是使用curl的例子，非常简单：非授权情况下访问public_timeline：curl/statuses/public_获取朋友的timeline,使用认证：curl-uemail:password/statuses/friends_仅获取头部信息：curl--heademail:password/statuses/friends_

用户状态相关方法statuses/public_timeline返回未设置私密的用户(必须有自定义的用户头像)的最近20条消息，该方法不需要身份认证。访问地址：/statuses/public_支持格式(format)：xml,json,rss,atom参数列表：无。statuses/friends_timeline返回最近24小时内的最新的20条认证用户及其好友更新的消息。访问地址：/statuses/friends_支持格式(format)：xml,json,rss,atom参数列表：since_id:可选参数（微博信息ID）.只返回ID比since_id大（比since_id时间晚的）的微博信息内容。示例:/statuses/friends_?since_id=12345max_id:可选参数.返回ID不大于max_id的微博信息内容。（微博信息ID）示例:/statuses/friends_?max_id=54321count:可选参数.每次返回的最大记录数，不能超过200，默认20.示例:/statuses/friends_?count=5page:可选参数.返回结果的页序号。注意：有分页限制。根据用户关注对

象发表的数量，通常最多返回1,000条最新微博分页内容,默认1示例:/statuses/friends_?page=3statuses/user_timeline返回认证用户最近24小时内最新更新的20条消息，同样，通过给定userIdOrName参数，可以用来请求其他用户的最近的消息更新。该API可以不认证。访问地址：/statuses/user_支持格式(format)：xml,json,rss,atom参数列表：id：可选参数.根据指定用户UID或微博昵称来返回微博信息。示例:/statuses/user_timeline/r_id：可选参数.用户UID，主要是用来区分用户UID跟微博昵称一样，产生歧义的时候，特别是在微博昵称为数字导致和用户Uid发生歧义。示例:/statuses/user_?user_id=1401881screen_name：可选参数.微博昵称，主要是用来区分用户UID跟微博昵称一样，产生歧义的时候。示例:/statuses/user_?screen_name=101010since_id：可选参数（微博信息ID）.只返回ID比since_id大（比since_id时间晚的）的微博信息内容示例:/statuses/user_?since_id=12345max_id:可选参数（微博信息ID）.返回ID不大于max_id的微博信息内容。示例:Example:/statuses/user_?max_id=54321

count:可选参数.每次返回的最大记录数，最多返回200条，默认20。示例:/statuses/user_?count=200page：可选参数.分页返回。注意：最多返回200条分页内容。示例:/statuses/user_?page=3statuses/mentions显示20条最近的对用户的回复消息，(消息前缀为@username)。该API只开放给认证用户，请求其他用户的收到的回复消息列表是非法的，无论其他用户设置私密与否。访问地址：/statuses/支持格式(format)：xml,json,rss,atom参数列表：since_id.可选参数.返回ID比数值since_id大（比since_id时间晚的）的提到。示例:/statuses/?since_id=12345max_id.可选参数.返回ID不大于max_id(时间不晚于max_id)的提到。示例:/statuses/?max_id=54321count.可选参数.每次返回的最大记录数（即页面大小），不大于200，默认为20。示例:/statuses/?count=200page.可选参数.返回结果的页序号。注意：有分页限制。示例:/statuses/?page=3

用户消息相关方法statuses/show返回指定Id的一条消息，返回信息中包含作者信息。访问地址：/statuses/show/或者/statuses/?id={id}支持格式(format)：xml,json参数列表:id.必须参数(微博信息ID)，要获取已发表的微博ID,如ID不存在返回空示例:/statuses/show/tuses/update更新认证用户的消息，必须包含content参数，且必须以POST方式请求。成功时按指定格式返回当前的消息。访问地址：/statuses/支持格式(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删除一条消息，认证用户必须是消息的作者。访问地址：/statuses/destroy/支持格式(format)：xml,json参数列表:id必须，待删除的消息Id，例如：/statuses/destroy/或者/statuses/?id=23456用户操作接口users/show显示指定用户的扩展信息，需要给定用户的id或显示名称。扩展信息包括用户的页面设置、微博次数等，因此第三方应用的开发者可以根据这些信息为用户提供合适的主题。注意：本API调用请求必须发自合法微博用户，不论请求自己/他人的扩展信息。访问地址：/users/支持格式(format)：xml,json参数列表：id.用户UID或微博昵称。

示例:/users/show/或/users/show/r_id.指定用户UID,主要是用来区分用户UID跟微博昵称一样，产生歧义的时候，特别是在用户账号为数字导致和用户Uid发生歧义。示例:/users/?user_id=1401881screen_name.指定微博昵称，主要是用来区分用户UID跟微博昵称一样，产生歧义的时候。示例:/users/?screen_name=101010statuses/friends返回认证用户的朋友列表，内含每个用户的当前微博信息。这个方法同样可以用来请求其他用户的朋友列表，通过下面指明的方法传递id参数。访问地址：/statuses/支持格式(format)：xml,json参数列表:id.选填参数.要获取的UID或微博昵称示例:/statuses/friends/tp:///statuses/friends/r_id.选填参数.要获取的UID示例:/statuses/?user_id=1401881screen_name.选填参数.要获取的微博昵称示例:/statuses/?screen_name=101010

cursor.选填参数.单页只能包含100个关注列表，为了获取更多则cursor默认从-1开始，通过增加或减少cursor来获取更多,如果没有下一页，则next_cursor返回0的关注列表示例:/statuses/friends/?cursor=-1示例:/statuses/friends/?cursor=1344903count.可选参数.每次返回的最大记录数（即页面大小），不大于200,默认返回20。示例:/statuses/friends/?&count=200statuses/followers返回认证用户的订阅者，内含每个订阅者的当前消息。与friends一样，只需要把friends地址中的friends替换为followers即可，其余一切包括参数都不需要改变，都是一样的用法。访问地址：/statuses/支持格式(format)：xml,json参数列表:id.选填参数.要获取粉丝的UID或微博昵称示例:/statuses/followers//statuses/followers/r_id.选填参数.要获取的UID示例:/statuses/?user_id=1401881

screen_name.选填参数.要获取的微博昵称示例:/statuses/?screen_name=101010cursor.选填参数.单页只能包含100个粉丝列表，为了获取更多则cursor默认从-1开始，通过增加或减少cursor来获取更多的，如果没有下一页，则next_cursor返回0粉丝列表示例:/statuses/followers/?cursor=-1示例:/statuses/followers/?cursor=1344903count.可选参数.每次返回的最大记录数（即页面大小），不大于200,默认返回20。示例:/statuses/followers/?&count=200私信操作方法direct_messages返回用户的消息列表访问地址：/direct_支持格式(format)：xml,json,rss,atom参数列表:since_id.可选参数.返回ID比数值since_id大（比since_id时间晚的）的私信。示例:/direct_?since_id=12345max_id.可选参数.返回ID不大于max_id(时间不晚于max_id)的私信。示例:/direct_?max_id=54321

count.可选参数.每次返回的最大记录数（即页面大小），不大于200。示例:/direct_?count=200page.可选参数.返回结果的页序号。注意：有分页限制。示例:/direct_?page=3direct_messages/sent返回用户的已发送消息列表访问地址：/direct_messages/支持格式(format)：xml,json,rss,atom参数列表:since_id.可选参数.返回ID比数值since_id大（比since_id时间晚的）的私信。示例:/direct_?since_id=12345max_id.可选参数.返回ID不大于max_id(时间不晚于max_id)的私信。示例:/direct_?max_id=54321count.可选参数.每次返回的最大记录数（即页面大小），不大于200。示例:/direct_?count=200page.可选参数.返回结果的页序号。注意：有分页限制。direct_messages/new以认证用户的身份向指定的其他用户发送一条有向消息，必须包含参数user和text,请求必须使用POST方式提交。成功将返回完整的发送消息必须包含参数user和text，必须使用POST方式提交。成功将返回完整的发送消息。

访问地址：/direct_messages/支持格式(format)：xml,json参数列表：user:user_id或者screen_nametext:必须参数.要发生的消息内容，需要做URLEncode，文本大小必须小于300个汉字direct_messages/destroy通过给定的消息id，删除指定的有向消息，认证用户只能删除其作为接受者收到的消息。使用POST和GET方法都可以访问地址：/direct_messages/destroy/支持格式(format)：xml,json参数列表：id.必填参数，要删除的私信主键ID.示例:/direct_messages/destroy/好友关系操作方法friendships/create创建认证用户与给定的id参数指定的用户之间的好友关系；该操作执行成功时返回被加为好友的用户信息，执行失败则返回失败的状态字串。访问地址：/friendships/create/支持格式(format)：xml,json参数列表：

下面的参数必须有其中一个:id.必填参数.要关注的用户UID或微博昵称示例:/friendships/create//friendships/create/r_id.必填参数.要关注的用户UID,主要是用在区分用户UID跟微博昵称一样，产生歧义的时候。示例:/friendships/?user_id=1401881screen_name.必填参数.要关注的微博昵称,主要是用在区分用户UID跟微博昵称一样，产生歧义的时候。示例:/friendships/?screen_name=101010follow.可选参数。暂不支持。friendships/destroy用来注销同指定id的用户的好友关系，当操作成功时，将返回被取消好友关系的用户，当失败时，将会返回失败信息。访问地址：/friendships/destroy/支持格式(format)：xml,json参数列表：下面的参数必须有其中一个:id.必填参数.要取消关注的用户UID或微博昵称示例:/friendships/destroy//friendships/destroy/r_id.必填参数.要取消关注的用户UID,主要是用在区分用户UID跟微

博昵称一样，产生歧义的时候。示例:/friendships/?user_id=1401881screen_name.必填参数.要取消的微博昵称,主要是用在区分用户UID跟微博昵称一样，产生歧义的时候。示例:/friendships/?screen_name=101010friendships/exists用来检验两个用户的关系是否是朋友关系或者跟随与被跟随的关系。返回相互跟随的关系结果。比如：A跟随了B。B没有跟随A。将返回对应的格式数据：如xml，truefalse访问地址：/friendships/支持格式：xml,json参数列表：user_a.必填参数，要判断的用户UIDuser_b.必填参数，要判断的被关注人用户UIDfriendships/show返回两个用户关系的详细情况访问地址：/friendships/支持格式：xml,json参数列表：以下参数可不填写，如不填，则取当前用户

source_id.源用户UID示例:/friendships/?source_id=10502source_screen_name.源微博昵称示例:/friendships/?source_screen_name=bob下面参数必须选填一个:target_id.要判断的目的用户UID示例:/friendships/?target_id=10503target_screen_name.要判断的目的微博昵称示例:/friendships/?target_screen_name=williamlong获取用户列表方法friends/ids用来获取指定的用户的朋友用户id。即自己跟随的人的id访问地址：/friends/支持格式：xml,json参数列表：id.选填参数.要获取好友的UID或微博昵称示例:/friends/ids/ttp:///statuses/friends/r_id.选填参数.要获取的UID示例:/friends/?user_id=1401881

screen_name.选填参数.要获取的微博昵称示例:/friends/?screen_name=101010cursor.选填参数.单页只能包含5000个id，为了获取更多则cursor默认从-1开始，通过增加或减少cursor来获取更多的关注列表示例:/friends/?cursor=-1示例:/friends/?cursor=1344903count.可选参数.每次返回的最大记录数（即页面大小），不大于5000，默认返回500。示例:/friends/?count=200followers/ids用来获取指定的用户被跟随的用户id。访问地址：/followers/支持格式：xml,json参数列表：id.选填参数.要获取好友的UID或微博昵称示例:/followers/ids/ttp:///statuses/friends/r_id.选填参数，要获取的UID示例:/followers/?user_id=1401881screen_name.选填参数，要获取的微博昵称示例:/followers/?screen_name=101010

cursor.选填参数.单页只能包含5000个id，为了获取更多则cursor默认从-1开始，通过增加或减少cursor来获取更多的关注列表示例:/followers/?cursor=-1示例:/followers/?cursor=1344903count.可选参数.每次返回的最大记录数（即页面大小），不大于5000，默认返回500。示例:/followers/?count=200用户帐号方法account/verify_credentials如果用户身份验证成功则返回http状态为200；如果是不则返回401的状态和错误信息。此方法用了判断用户身份是否合法。访问地址：/account/verify_支持格式：xml,json参数列表：account/update_profile自定义微博页面的参数。只会修改参数更新项。访问地址：/account/update_支持格式：xml,json参数列表：必须有一下参数中的一个或多个，参数值为字符串.进一步的限制，请参阅下面的各个参数描述.

name.昵称，可选参数.不超过20个汉字gender性别，可选参数.m,男，f,女。province可选参数.参考省份城市编码表city可选参数.参考省份城市编码表,1000为不限description.可选参数.不超过160个汉字.收藏相关方法favorites返回授权用户的最新的20条收藏的状态信息。也可以通过id或者用户名来指定一个用户，查询他最新的20条收藏的状态信息。访问地址：/支持格式：xml,json,rss,atom参数列表：page：可选参数.返回结果的页序号。注意：有分页限制。示例:/favorites/?page=3favorites/create收藏一条状态信息POST提交访问地址：/favorites/支持格式：xml,json参数列表：

id必须，授权用户要收藏的状态信息id。favorites/destroy删除授权用户收藏的一条状态信息访问地址：/favorites/destroy/支持格式：xml,json参数列表：id授权用户收藏的状态信息id。