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。