Class: TwitterOAuth::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/twitter_oauth/spam.rb,
lib/twitter_oauth/user.rb,
lib/twitter_oauth/lists.rb,
lib/twitter_oauth/utils.rb,
lib/twitter_oauth/blocks.rb,
lib/twitter_oauth/client.rb,
lib/twitter_oauth/search.rb,
lib/twitter_oauth/status.rb,
lib/twitter_oauth/trends.rb,
lib/twitter_oauth/account.rb,
lib/twitter_oauth/timeline.rb,
lib/twitter_oauth/favorites.rb,
lib/twitter_oauth/friendships.rb,
lib/twitter_oauth/notifications.rb,
lib/twitter_oauth/saved_searches.rb,
lib/twitter_oauth/direct_messages.rb

Constant Summary collapse

CRLF =
"\r\n"

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Client

Returns a new instance of Client.



20
21
22
23
24
25
# File 'lib/twitter_oauth/client.rb', line 20

def initialize(options = {})
  @consumer_key = options[:consumer_key]
  @consumer_secret = options[:consumer_secret]
  @token = options[:token]
  @secret = options[:secret]
end

Instance Method Details

#add_member_to_list(user, list, member_id, options = {}) ⇒ Object

Add a member to a list. The authenticated user must own the list to be able to add members to it. Lists are limited to having 500 members.



60
61
62
# File 'lib/twitter_oauth/lists.rb', line 60

def add_member_to_list(user, list, member_id, options={})
  post("/#{user}/#{list}/members.json", options.merge(:id => member_id))
end

#all_followersObject

Returns all pages of followers



48
49
50
51
52
53
54
55
56
57
# File 'lib/twitter_oauth/user.rb', line 48

def all_followers
  users = []
  cursor = "-1"
  while cursor != 0 do 
    json = get("/statuses/followers.json?cursor=#{cursor}")
    cursor = json["next_cursor"]
    users += json["users"]
  end
  users
end

#all_friendsObject

Returns all pages of friends



22
23
24
25
26
27
28
29
30
31
# File 'lib/twitter_oauth/user.rb', line 22

def all_friends
  users = []
  cursor = "-1"
  while cursor != 0 do 
    json = get("/statuses/friends.json?cursor=#{cursor}")
    cursor = json["next_cursor"]
    users += json["users"]
  end
  users
end

#authentication_request_token(options = {}) ⇒ Object



50
51
52
53
# File 'lib/twitter_oauth/client.rb', line 50

def authentication_request_token(options={})
  consumer.options[:authorize_path] = '/oauth/authenticate'
  request_token(options)
end

#authorize(token, secret, options = {}) ⇒ Object



27
28
29
30
31
32
33
34
35
# File 'lib/twitter_oauth/client.rb', line 27

def authorize(token, secret, options = {})
  request_token = OAuth::RequestToken.new(
    consumer, token, secret
  )
  @access_token = request_token.get_access_token(options)
  @token = @access_token.token
  @secret = @access_token.secret
  @access_token
end

#authorized?Boolean

Returns an HTTP 200 OK response code and a representation of the requesting user if authentication was successful; returns a 401 status code and an error message if not.

Returns:

  • (Boolean)


6
7
8
9
# File 'lib/twitter_oauth/account.rb', line 6

def authorized?
  oauth_response = access_token.get('/account/verify_credentials.json')
  return oauth_response.class == Net::HTTPOK
end

#block(id) ⇒ Object

Blocks the user specified in the ID parameter as the authenticating user. Destroys a friendship to the blocked user if it exists. Returns the blocked user in the requested format when successful.



7
8
9
# File 'lib/twitter_oauth/blocks.rb', line 7

def block(id)
  post("/blocks/create/#{id}.json")
end

#blocked?(id) ⇒ Boolean

Returns if the authenticating user is blocking a target user.

Returns:

  • (Boolean)


18
19
20
# File 'lib/twitter_oauth/blocks.rb', line 18

def blocked?(id)
  get("/blocks/exists/#{id}.json")
end

#blockingObject

Returns an array of user objects that the authenticating user is blocking.



23
24
25
# File 'lib/twitter_oauth/blocks.rb', line 23

def blocking
  get("/blocks/blocking.json")
end

#blocking_idsObject

Returns an array of numeric user ids the authenticating user is blocking.



28
29
30
# File 'lib/twitter_oauth/blocks.rb', line 28

def blocking_ids
  get("/blocks/blocking/ids.json")
end

#create_list(user, list, options = {}) ⇒ Object

Creates a new list for the authenticated user. Accounts are limited to 20 lists.



9
10
11
# File 'lib/twitter_oauth/lists.rb', line 9

def create_list(user, list, options={})
  post("/#{user}/lists.json", options.merge(:name => list))
end

#create_saved_search(query) ⇒ Object

Creates a saved search for the authenticated user.



15
16
17
# File 'lib/twitter_oauth/saved_searches.rb', line 15

def create_saved_search(query)
  post("/saved_searches/create.json", :query => query)
end

Returns the current top 10 trending topics on Twitter.



15
16
17
# File 'lib/twitter_oauth/search.rb', line 15

def current_trends
  search_get("/trends/current.json")
end

Returns the top 20 trending topics for each hour in a given day.



20
21
22
# File 'lib/twitter_oauth/search.rb', line 20

def daily_trends
  search_get("/trends/daily.json")
end

#delete_list(user, list) ⇒ Object

Deletes the specified list. Must be owned by the authenticated user.



30
31
32
# File 'lib/twitter_oauth/lists.rb', line 30

def delete_list(user, list)
  delete("/#{user}/lists/#{list}.json")
end

#delete_saved_search(search_id) ⇒ Object



19
20
21
# File 'lib/twitter_oauth/saved_searches.rb', line 19

def delete_saved_search(search_id)
  post("/saved_searches/destroy/#{search_id}.json")
end

#favorite(id) ⇒ Object

Favorites the status specified in the ID parameter as the authenticating user. Returns the favorite status when successful.



11
12
13
# File 'lib/twitter_oauth/favorites.rb', line 11

def favorite(id)
  post("/favorites/create/#{id}.json")
end

#favorites(page = 1) ⇒ Object

Returns the 20 most recent favorite statuses for the authenticating user or user specified by the ID parameter.



5
6
7
# File 'lib/twitter_oauth/favorites.rb', line 5

def favorites(page=1)
  get("/favorites.json?page=#{page}")
end

#follow(id) ⇒ Object

Enables device notifications for updates from the specified user.

Returns the specified user when successful.



6
7
8
# File 'lib/twitter_oauth/notifications.rb', line 6

def follow(id)
  post("/notifications/follow/#{id}.json")
end

#followers(page = 1) ⇒ Object

Returns the 100 last followers



34
35
36
37
38
39
40
41
42
43
44
45
# File 'lib/twitter_oauth/user.rb', line 34

def followers(page=1)
  return get("/statuses/followers.json?page=#{page}") if page == 1
  users = []
  cursor = "-1"
  page.times do 
    return [] if cursor == 0 
    json = get("/statuses/followers.json?cursor=#{cursor}")
    cursor = json["next_cursor"]
    users = json["users"]
  end
  users
end

#followers_ids(options = {}) ⇒ Object

Returns an array of numeric IDs for every user following the specified user.



11
12
13
14
# File 'lib/twitter_oauth/friendships.rb', line 11

def followers_ids(options={})
  args = options.map{|k,v| "#{k}=#{v}"}.join('&')
  get("/followers/ids.json?#{args}")
end

#friend(id) ⇒ Object

Allows the authenticating user to follow the specified user. Returns the befriended user when successful.



17
18
19
# File 'lib/twitter_oauth/friendships.rb', line 17

def friend(id)
  post("/friendships/create/#{id}.json")
end

#friends(page = 1) ⇒ Object

Returns the 100 last friends The page parameter is implemented for legacy reasons, but use of this is slow as passing page is no longer supported by the Twitter API as the use of cursors is now obligitory. It is recommended that you use all_friends instead



8
9
10
11
12
13
14
15
16
17
18
19
# File 'lib/twitter_oauth/user.rb', line 8

def friends(page=1)
  return get("/statuses/friends.json?page=#{page}") if page == 1
  users = []
  cursor = "-1"
  page.times do 
    return [] if cursor == 0 
    json = get("/statuses/friends.json?cursor=#{cursor}")
    cursor = json["next_cursor"]
    users = json["users"]
  end
  users
end

#friends?(a, b) ⇒ Boolean

Tests for the existence of friendship between two users. Will return true if user_a follows user_b, otherwise will return false. You are better off using get_friendship as it returns more extended information.

Returns:

  • (Boolean)


28
29
30
31
# File 'lib/twitter_oauth/friendships.rb', line 28

def friends?(a, b)
  oauth_response = access_token.get("/friendships/exists.json?user_a=#{a}&user_b=#{b}")
  oauth_response.body.strip == 'true'
end

#friends_ids(options = {}) ⇒ Object

Returns an array of numeric IDs for every user the specified user is following.



5
6
7
8
# File 'lib/twitter_oauth/friendships.rb', line 5

def friends_ids(options={})
  args = options.map{|k,v| "#{k}=#{v}"}.join('&')
  get("/friends/ids.json?#{args}")
end

#friends_timeline(options = {}) ⇒ Object

Returns the 20 most recent statuses posted by the authenticating user and that user’s friends.



18
19
20
21
# File 'lib/twitter_oauth/timeline.rb', line 18

def friends_timeline(options={})
  args = options.map{|k,v| "#{k}=#{v}"}.join('&')
  get("/statuses/friends_timeline.json?#{args}")
end

#get_friendship(a, b) ⇒ Object

Returns detailed information about the relationship between two users.



34
35
36
# File 'lib/twitter_oauth/friendships.rb', line 34

def get_friendship(a, b)
  get("/friendships/show.json?source_screen_name=#{a}&target_screen_name=#{b}")
end

#get_list(user, list) ⇒ Object

Show the specified list. Private lists will only be shown if the authenticated user owns the specified list.



25
26
27
# File 'lib/twitter_oauth/lists.rb', line 25

def get_list(user, list)
  get("/#{user}/lists/#{list}.json")
end

#get_lists(user) ⇒ Object

List the lists of the specified user. Private lists will be included if the authenticated user is the same as the user whose lists are being returned.



20
21
22
# File 'lib/twitter_oauth/lists.rb', line 20

def get_lists(user)
  get("/#{user}/lists.json")
end

#get_member_of_list(user, list, member_id) ⇒ Object

Check if a user is a member of the specified list.



71
72
73
# File 'lib/twitter_oauth/lists.rb', line 71

def get_member_of_list(user, list, member_id)
  get("/#{user}/#{list}/members/#{member_id}.json")
end

#get_saved_search(search_id) ⇒ Object

Retrieve the data for a saved search owned by the authenticating user specified by the given id.



10
11
12
# File 'lib/twitter_oauth/saved_searches.rb', line 10

def get_saved_search(search_id)
  get("/saved_searches/show/#{search_id}.json")
end

#get_subscriber_of_list(user, list, subscriber_id) ⇒ Object

Check if the specified user is a subscriber of the specified list.



95
96
97
# File 'lib/twitter_oauth/lists.rb', line 95

def get_subscriber_of_list(user, list, subscriber_id)
  get("/#{user}/#{list}/subscribers/#{subscriber_id}.json")
end

#home_timeline(options = {}) ⇒ Object

Returns the 20 most recent statuses, including retweets, posted by the authenticating user and that user’s friends. This is the equivalent of /timeline/home on the Web.



12
13
14
15
# File 'lib/twitter_oauth/timeline.rb', line 12

def home_timeline(options={})
  args = options.map{|k,v| "#{k}=#{v}"}.join('&')
  get("/statuses/home_timeline.json?#{args}")
end

#infoObject

Returns client info



12
13
14
# File 'lib/twitter_oauth/account.rb', line 12

def info
  get('/account/verify_credentials.json')
end

#leave(id) ⇒ Object

Disables notifications for updates from the specified user to the authenticating user.

Returns the specified user when successful.



12
13
14
# File 'lib/twitter_oauth/notifications.rb', line 12

def leave(id)
  post("/notifications/leave/#{id}.json")
end

#list_members(user, list) ⇒ Object

Returns the members of the specified list.



54
55
56
# File 'lib/twitter_oauth/lists.rb', line 54

def list_members(user, list)
  get("/#{user}/#{list}/members.json")
end

#list_memberships(user) ⇒ Object

List the lists the specified user has been added to.



40
41
42
# File 'lib/twitter_oauth/lists.rb', line 40

def list_memberships(user)
  get("/#{user}/lists/memberships.json")
end

#list_statuses(user, list) ⇒ Object

Show tweet timeline for members of the specified list.



35
36
37
# File 'lib/twitter_oauth/lists.rb', line 35

def list_statuses(user, list)
  get("/#{user}/lists/#{list}/statuses.json")
end

#list_subscribers(user, list) ⇒ Object

Returns the subscribers of the specified list.



80
81
82
# File 'lib/twitter_oauth/lists.rb', line 80

def list_subscribers(user, list)
  get("/#{user}/#{list}/subscribers.json")
end

#list_subscriptions(user) ⇒ Object

List the lists the specified user follows.



45
46
47
# File 'lib/twitter_oauth/lists.rb', line 45

def list_subscriptions(user)
  get("/#{user}/lists/subscriptions.json")
end

#mentions(options = {}) ⇒ Object Also known as: replies

Returns the 20 most recent @replies (status updates prefixed with @username) for the authenticating user.



31
32
33
34
# File 'lib/twitter_oauth/timeline.rb', line 31

def mentions(options={})
  args = options.map{|k,v| "#{k}=#{v}"}.join('&')
  get("/statuses/mentions.json?#{args}")
end

#message(user, text) ⇒ Object

Sends a new direct message to the specified user from the authenticating user.



19
20
21
# File 'lib/twitter_oauth/direct_messages.rb', line 19

def message(user, text)
  post('/direct_messages/new.json', :user => user, :text => text)
end

#message_destroy(id) ⇒ Object

Destroys the direct message specified in the required ID parameter.



24
25
26
# File 'lib/twitter_oauth/direct_messages.rb', line 24

def message_destroy(id)
  post("/direct_messages/destroy/#{id}.json")
end

#messages(options = {}) ⇒ Object

Return the most recent direct messages sent to the authenticating user. By default, returns the last 20. See apiwiki.twitter.com/Twitter-REST-API-Method:-direct_messages for other options



7
8
9
10
# File 'lib/twitter_oauth/direct_messages.rb', line 7

def messages(options={})
  args = options.map{|k,v| "#{k}=#{v}"}.join('&')
  get("/direct_messages.json?#{args}")
end

#public_timeline(options = {}) ⇒ Object

Returns the 20 most recent statuses from non-protected users who have set a custom user icon.



5
6
7
8
# File 'lib/twitter_oauth/timeline.rb', line 5

def public_timeline(options={})
  args = options.map{|k,v| "#{k}=#{v}"}.join('&')
  get("/statuses/public_timeline.json?#{args}")
end

#rate_limit_statusObject

Returns the remaining number of API requests available to the requesting user before the API limit is reached for the current hour.



17
18
19
# File 'lib/twitter_oauth/account.rb', line 17

def rate_limit_status
  get('/account/rate_limit_status.json')
end

#remove_member_from_list(user, list, member_id) ⇒ Object

Removes the specified member from the list. The authenticated user must be the list’s owner to remove members from the list.



66
67
68
# File 'lib/twitter_oauth/lists.rb', line 66

def remove_member_from_list(user, list, member_id)
  delete("/#{user}/#{list}/members.json?id=#{member_id}")
end

#report_spam(user) ⇒ Object

The user specified in the id is blocked by the authenticated user and reported as a spammer.



5
6
7
# File 'lib/twitter_oauth/spam.rb', line 5

def report_spam(user)
  post("/report_spam.json", :id => user)
end

#request_token(options = {}) ⇒ Object



46
47
48
# File 'lib/twitter_oauth/client.rb', line 46

def request_token(options={})
  consumer.get_request_token(options)
end

#retweet(id) ⇒ Object

Retweets the tweet specified by the id parameter. Returns the original tweet with retweet details embedded.



20
21
22
# File 'lib/twitter_oauth/status.rb', line 20

def retweet(id)
  post("/statuses/retweet/#{id}.json")
end

#retweeted_by_me(options = {}) ⇒ Object

Returns the 20 most recent retweets posted by the authenticating user



38
39
40
41
# File 'lib/twitter_oauth/timeline.rb', line 38

def retweeted_by_me(options={})
  args = options.map{|k,v| "#{k}=#{v}"}.join('&')
  get("/statuses/retweeted_by_me.json?#{args}")
end

#retweeted_to_me(options = {}) ⇒ Object

Returns the 20 most recent retweets posted by the authenticating user’s friends.



44
45
46
47
# File 'lib/twitter_oauth/timeline.rb', line 44

def retweeted_to_me(options={})
  args = options.map{|k,v| "#{k}=#{v}"}.join('&')
  get("/statuses/retweeted_to_me.json?#{args}")
end

#retweets_of_me(options = {}) ⇒ Object

Returns the 20 most recent tweets of the authenticated user that have been retweeted by others.



50
51
52
53
# File 'lib/twitter_oauth/timeline.rb', line 50

def retweets_of_me(options={})
  args = options.map{|k,v| "#{k}=#{v}"}.join('&')
  get("/statuses/retweets_of_me.json?#{args}")
end

#saved_searchesObject

Returns the authenticated user’s saved search queries.



5
6
7
# File 'lib/twitter_oauth/saved_searches.rb', line 5

def saved_searches
  get("/saved_searches.json")
end

#search(q, options = {}) ⇒ Object



6
7
8
9
10
11
12
# File 'lib/twitter_oauth/search.rb', line 6

def search(q, options={})
  options[:page] ||= 1
  options[:rpp] ||= 20
  options[:q] = URI.escape(q)
  args = options.map{|k,v| "#{k}=#{v}"}.join('&')
  search_get("/search.json?#{args}")
end

#sent_messages(options = {}) ⇒ Object

By default, returns a list of the 20 most recent direct messages sent by the authenticating user.



13
14
15
16
# File 'lib/twitter_oauth/direct_messages.rb', line 13

def sent_messages(options={})
  args = options.map{|k,v| "#{k}=#{v}"}.join('&')
  get("/direct_messages/sent.json?#{args}")
end

#show(username) ⇒ Object



37
38
39
# File 'lib/twitter_oauth/client.rb', line 37

def show(username)
  get("/users/show/#{username}.json")
end

#status(id) ⇒ Object

Returns a single status, specified by the id parameter below.



5
6
7
# File 'lib/twitter_oauth/status.rb', line 5

def status(id)
  get("/statuses/show/#{id}.json")
end

#status_destroy(id) ⇒ Object

Destroys the status specified by the required ID parameter



15
16
17
# File 'lib/twitter_oauth/status.rb', line 15

def status_destroy(id)
  post("/statuses/destroy/#{id}.json")
end

#subscribe_to_list(user, list, options = {}) ⇒ Object

Make the authenticated user follow the specified list.



85
86
87
# File 'lib/twitter_oauth/lists.rb', line 85

def subscribe_to_list(user, list, options={})
  post("/#{user}/#{list}/subscribers.json")
end

#testObject

Returns the string “ok” in the requested format with a 200 OK HTTP status code.



42
43
44
# File 'lib/twitter_oauth/client.rb', line 42

def test
  get("/help/test.json")
end

Returns the top ten topics that are currently trending on Twitter.



5
6
7
# File 'lib/twitter_oauth/trends.rb', line 5

def trends
  get("/trends.json")
end

Returns the locations that Twitter has trending topic information for. The response is an array of “locations” that encode the location’s WOEID (a Yahoo! Where On Earth ID) and some other human-readable information such as a canonical name and country the location belongs in.



12
13
14
# File 'lib/twitter_oauth/trends.rb', line 12

def trends_available
  get("/trends/available.json")
end

Returns the top 10 trending topics for a specific location Twitter has trending topic information for. The response is an array of “trend” objects that encode the name of the trending topic, the query parameter that can be used to search for the topic on Search, and the direct URL that can be issued against Search. This information is cached for five minutes, and therefore users are discouraged from querying these endpoints faster than once every five minutes. Global trends information is also available from this API by using a WOEID of 1.



21
22
23
# File 'lib/twitter_oauth/trends.rb', line 21

def trends_for_location(woeid)
  get("/trends/woeid.json")
end

#unblock(id) ⇒ Object

Un-blocks the user specified in the ID parameter for the authenticating user.

Returns the un-blocked user in the requested format when successful.



13
14
15
# File 'lib/twitter_oauth/blocks.rb', line 13

def unblock(id)
  post("/blocks/destroy/#{id}.json")
end

#unfavorite(id) ⇒ Object

Un-favorites the status specified in the ID parameter as the authenticating user. Returns the un-favorited status when successful.



17
18
19
# File 'lib/twitter_oauth/favorites.rb', line 17

def unfavorite(id)
  post("/favorites/destroy/#{id}.json")
end

#unfriend(id) ⇒ Object

Allows the authenticating users to unfollow the specified user. Returns the unfollowed user when successful.



22
23
24
# File 'lib/twitter_oauth/friendships.rb', line 22

def unfriend(id)
  post("/friendships/destroy/#{id}.json")
end

#unsubscribe_from_list(user, list) ⇒ Object

Unsubscribes the authenticated user form the specified list.



90
91
92
# File 'lib/twitter_oauth/lists.rb', line 90

def unsubscribe_from_list(user, list)
  delete("/#{user}/#{list}/subscribers.json")
end

#update(message, options = {}) ⇒ Object

Updates the authenticating user’s status.



10
11
12
# File 'lib/twitter_oauth/status.rb', line 10

def update(message, options={})
  post('/statuses/update.json', options.merge(:status => message))
end

#update_list(user, list, options = {}) ⇒ Object

Updates the specified list.



14
15
16
# File 'lib/twitter_oauth/lists.rb', line 14

def update_list(user, list, options={})
  post("/#{user}/lists/#{list}.json", options)
end

#update_profile(params) ⇒ Object

Sets values that users are able to set under the “Account” tab of their settings page. Valid parameters are:

:name     Full name associated with the profile. Maximum of 20 characters.
:url      URL associated with the profile. Will be prepended with "http://" if not present. Maximum of 100 characters.
:location The city or country describing where the user of the account is located. The contents are not normalized
          or geocoded in any way. Maximum of 30 characters.
:description A description of the user owning the account. Maximum of 160 characters.


48
49
50
# File 'lib/twitter_oauth/account.rb', line 48

def update_profile(params)
  post('/account/update_profile', params)
end

#update_profile_background_image(image, tile = false) ⇒ Object

Updates profile background image. Takes a File object and optional tile argument. Returns extended user info object.



23
24
25
26
# File 'lib/twitter_oauth/account.rb', line 23

def update_profile_background_image(image, tile = false)
  body, headers = http_multipart_data({:image => image, :tile => tile})
  post('/account/update_profile_background_image.json', body, headers)
end

#update_profile_colors(colors) ⇒ Object

colors hash must contain at least one or more of the following keys :profile_background_color, :profile_text_color, :profile_link_color, :profile_sidebar_fill_color, :profile_sidebar_border_color returns extended user info object.



37
38
39
# File 'lib/twitter_oauth/account.rb', line 37

def update_profile_colors(colors)
  post('/account/update_profile_colors.json', colors)
end

#update_profile_image(image) ⇒ Object

Updates profile avatar image. Takes a File object which should be an image. Returns extended user info object.



30
31
32
33
# File 'lib/twitter_oauth/account.rb', line 30

def update_profile_image(image)
  body, headers = http_multipart_data({:image => image})
  post('/account/update_profile_image.json', body, headers)
end

#user_timeline(options = {}) ⇒ Object Also known as: user

Returns the 20 most recent statuses posted from the authenticating user.



24
25
26
27
# File 'lib/twitter_oauth/timeline.rb', line 24

def user_timeline(options={})
  args = options.map{|k,v| "#{k}=#{v}"}.join('&')
  get("/statuses/user_timeline.json?#{args}")
end

Returns the top 30 trending topics for each day in a given week.



25
26
27
# File 'lib/twitter_oauth/search.rb', line 25

def weekly_trends
  search_get("/trends/weekly.json")
end