Module: Twitter::API

Included in:
Client
Defined in:
lib/twitter/api.rb

Constant Summary collapse

DEFAULT_CURSOR = 
-1
DEFAULT_TWEETS_PER_REQUEST = 
20
MAX_USERS_PER_REQUEST = 
100
MAX_TWEETS_PER_REQUEST = 
200

Instance Method Summary collapse

Instance Method Details

#activity_about_me(options = {}) ⇒ Array

Note:

Undocumented

Returns activity about me

Examples:

Return activity about me

Twitter.activity_about_me

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :count (Integer) —

    Specifies the number of records to retrieve. Must be less than or equal to 100.

  • :since_id (Integer) —

    Returns results with an ID greater than (that is, more recent than) the specified ID.

Returns:

  • (Array) —

    An array of actions

Raises:



167
168
169
 
# File 'lib/twitter/api.rb', line 167

def activity_about_me(options={})
  collection_from_response(Twitter::ActionFactory, :get, "/i/activity/about_me.json", options)
end

#activity_by_friends(options = {}) ⇒ Array

Note:

Undocumented

Returns activity by friends

Examples:

Return activity by friends

Twitter.activity_by_friends

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :count (Integer) —

    Specifies the number of records to retrieve. Must be less than or equal to 100.

  • :since_id (Integer) —

    Returns results with an ID greater than (that is, more recent than) the specified ID.

Returns:

  • (Array) —

    An array of actions

Raises:



183
184
185
 
# File 'lib/twitter/api.rb', line 183

def activity_by_friends(options={})
  collection_from_response(Twitter::ActionFactory, :get, "/i/activity/by_friends.json", options)
end

#block(*users) ⇒ Array<Twitter::User> #block(*users, options) ⇒ Array<Twitter::User>

Note:

Destroys a friendship to the blocked user if it exists.

Blocks the users specified by the authenticating user

Overloads:

Returns:

Raises:

See Also:



2000
2001
2002
 
# File 'lib/twitter/api.rb', line 2000

def block(*args)
  threaded_users_from_response(:post, "/1.1/blocks/create.json", args)
end

#block?(user, options = {}) ⇒ Boolean

Returns true if the authenticating user is blocking a target user

Examples:

Check whether the authenticating user is blocking @sferik

Twitter.block?('sferik')
Twitter.block?(7505382)  # Same as above

Parameters:

  • user (Integer, String, Twitter::User) —

    A Twitter user ID, screen name, or object.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Returns:

  • (Boolean) —

    true if the authenticating user is blocking the target user, otherwise false.

Raises:

See Also:



1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
 
# File 'lib/twitter/api.rb', line 1971

def block?(user, options={})
  merge_default_cursor!(options)
  user_id = case user
  when Integer
    user
  when String
    user(user).id
  when Twitter::User
    user.id
  end
  blocked_ids(options).all.map(&:to_i).include?(user_id)
end

#blocked_ids(*args) ⇒ Array

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

Examples:

Return an array of numeric user ids the authenticating user is blocking

Twitter.blocking_ids

Parameters:

  • options (Hash) —

    A customizable set of options.

Returns:

  • (Array) —

    Numeric user ids the authenticating user is blocking.

Raises:

See Also:



1955
1956
1957
 
# File 'lib/twitter/api.rb', line 1955

def blocked_ids(*args)
  ids_from_response(:get, "/1.1/blocks/ids.json", args)
end

#blocking(options = {}) ⇒ Array<Twitter::User>

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

Examples:

Return an array of user objects that the authenticating user is blocking

Twitter.blocking

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :page (Integer) —

    Specifies the page of results to retrieve.

Returns:

Raises:

See Also:



1940
1941
1942
1943
 
# File 'lib/twitter/api.rb', line 1940

def blocking(options={})
  merge_default_cursor!(options)
  cursor_from_response(:users, Twitter::User, :get, "/1.1/blocks/list.json", options)
end

#configuration(options = {}) ⇒ Twitter::Configuration

Returns the current configuration used by Twitter

Examples:

Return the current configuration used by Twitter

Twitter.configuration

Returns:

Raises:

See Also:



678
679
680
 
# File 'lib/twitter/api.rb', line 678

def configuration(options={})
  object_from_response(Twitter::Configuration, :get, "/1.1/help/configuration.json", options)
end

#contributees(options = {}) ⇒ Array<Twitter::User> #contributees(user, options = {}) ⇒ Array<Twitter::User>

Returns an array of users that the specified user can contribute to

Overloads:

  • #contributees(options = {}) ⇒ Array<Twitter::User>

    Examples:

    Return the authenticated user’s contributees

    Twitter.contributees

    Parameters:

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :skip_status (Boolean, String, Integer) —

      Do not include contributee’s Tweets when set to true, ‘t’ or 1.

  • #contributees(user, options = {}) ⇒ Array<Twitter::User>

    Examples:

    Return users @sferik can contribute to

    Twitter.contributees('sferik')
Twitter.contributees(7505382)  # Same as above

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :skip_status (Boolean, String, Integer) —

      Do not include contributee’s Tweets when set to true, ‘t’ or 1.

Returns:

Raises:

See Also:



2171
2172
2173
 
# File 'lib/twitter/api.rb', line 2171

def contributees(*args)
  users_from_response(:get, "/1.1/users/contributees.json", args)
end

#contributors(options = {}) ⇒ Array<Twitter::User> #contributors(user, options = {}) ⇒ Array<Twitter::User>

Returns an array of users who can contribute to the specified account

Overloads:

  • #contributors(options = {}) ⇒ Array<Twitter::User>

    Examples:

    Return the authenticated user’s contributors

    Twitter.contributors

    Parameters:

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :skip_status (Boolean, String, Integer) —

      Do not include contributee’s Tweets when set to true, ‘t’ or 1.

  • #contributors(user, options = {}) ⇒ Array<Twitter::User>

    Examples:

    Return users who can contribute to @sferik’s account

    Twitter.contributors('sferik')
Twitter.contributors(7505382)  # Same as above

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :skip_status (Boolean, String, Integer) —

      Do not include contributee’s Tweets when set to true, ‘t’ or 1.

Returns:

Raises:

See Also:



2194
2195
2196
 
# File 'lib/twitter/api.rb', line 2194

def contributors(*args)
  users_from_response(:get, "/1.1/users/contributors.json", args)
end

#direct_message(id, options = {}) ⇒ Twitter::DirectMessage

Note:

This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information.

Returns a direct message

Examples:

Return the direct message with the id 1825786345

Twitter.direct_message(1825786345)

Parameters:

  • id (Integer) —

    A Tweet IDs.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Returns:

Raises:

See Also:



280
281
282
283
 
# File 'lib/twitter/api.rb', line 280

def direct_message(id, options={})
  options[:id] = id
  object_from_response(Twitter::DirectMessage, :get, "/1.1/direct_messages/show.json", options)
end

#direct_message_create(user, text, options = {}) ⇒ Twitter::DirectMessage Also known as: d, m

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

Examples:

Send a direct message to @sferik from the authenticating user

Twitter.direct_message_create('sferik', "I'm sending you this message via @gem!")
Twitter.direct_message_create(7505382, "I'm sending you this message via @gem!")  # Same as above

Parameters:

  • user (Integer, String, Twitter::User) —

    A Twitter user ID, screen name, or object.

  • text (String) —

    The text of your direct message, up to 140 characters.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Returns:

Raises:

See Also:



260
261
262
263
264
 
# File 'lib/twitter/api.rb', line 260

def direct_message_create(user, text, options={})
  options.merge_user!(user)
  options[:text] = text
  object_from_response(Twitter::DirectMessage, :post, "/1.1/direct_messages/new.json", options)
end

#direct_message_destroy(*ids) ⇒ Array<Twitter::DirectMessage> #direct_message_destroy(*ids, options) ⇒ Array<Twitter::DirectMessage>

Note:

This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information.

Destroys direct messages

Overloads:

  • #direct_message_destroy(*ids) ⇒ Array<Twitter::DirectMessage>

    Examples:

    Destroys the direct message with the ID 1825785544

    Twitter.direct_message_destroy(1825785544)

    Parameters:

    • ids (Array<Integer>, Set<Integer>) —

      An array of Tweet IDs.

  • #direct_message_destroy(*ids, options) ⇒ Array<Twitter::DirectMessage>

    Parameters:

    • ids (Array<Integer>, Set<Integer>) —

      An array of Tweet IDs.

    • options (Hash) —

      A customizable set of options.

Returns:

Raises:

See Also:



240
241
242
243
244
245
 
# File 'lib/twitter/api.rb', line 240

def direct_message_destroy(*args)
  options = args.extract_options!
  args.flatten.threaded_map do |id|
    object_from_response(Twitter::DirectMessage, :post, "/1.1/direct_messages/destroy.json", options.merge(:id => id))
  end
end

#direct_messages(options = {}) ⇒ Array<Twitter::DirectMessage> #direct_messages(*ids) ⇒ Array<Twitter::DirectMessage> #direct_messages(*ids, options) ⇒ Array<Twitter::DirectMessage>

Note:

This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information.

Returns The requested messages.

Overloads:

Returns:

Raises:



314
315
316
317
318
319
320
321
322
323
 
# File 'lib/twitter/api.rb', line 314

def direct_messages(*args)
  options = args.extract_options!
  if args.empty?
    direct_messages_received(options)
  else
    args.flatten.threaded_map do |id|
      direct_message(id, options)
    end
  end
end

#direct_messages_received(options = {}) ⇒ Array<Twitter::DirectMessage>

Note:

This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information.

Returns the 20 most recent direct messages sent to the authenticating user

Examples:

Return the 20 most recent direct messages sent to the authenticating user

Twitter.direct_messages_received

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :since_id (Integer) —

    Returns results with an ID greater than (that is, more recent than) the specified ID.

  • :max_id (Integer) —

    Returns results with an ID less than (that is, older than) or equal to the specified ID.

  • :count (Integer) —

    Specifies the number of records to retrieve. Must be less than or equal to 200.

  • :page (Integer) —

    Specifies the page of results to retrieve.

Returns:

Raises:

See Also:



202
203
204
 
# File 'lib/twitter/api.rb', line 202

def direct_messages_received(options={})
  collection_from_response(Twitter::DirectMessage, :get, "/1.1/direct_messages.json", options)
end

#direct_messages_sent(options = {}) ⇒ Array<Twitter::DirectMessage>

Note:

This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information.

Returns the 20 most recent direct messages sent by the authenticating user

Examples:

Return the 20 most recent direct messages sent by the authenticating user

Twitter.direct_messages_sent

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :since_id (Integer) —

    Returns results with an ID greater than (that is, more recent than) the specified ID.

  • :max_id (Integer) —

    Returns results with an ID less than (that is, older than) or equal to the specified ID.

  • :count (Integer) —

    Specifies the number of records to retrieve. Must be less than or equal to 200.

  • :page (Integer) —

    Specifies the page of results to retrieve.

Returns:

Raises:

See Also:



221
222
223
 
# File 'lib/twitter/api.rb', line 221

def direct_messages_sent(options={})
  collection_from_response(Twitter::DirectMessage, :get, "/1.1/direct_messages/sent.json", options)
end

#favorite(*ids) ⇒ Array<Twitter::Tweet> #favorite(*ids, options) ⇒ Array<Twitter::Tweet> Also known as: fav, fave, favorite_create

Favorites the specified Tweets as the authenticating user

Overloads:

  • #favorite(*ids) ⇒ Array<Twitter::Tweet>

    Examples:

    Favorite the Tweet with the ID 25938088801

    Twitter.favorite(25938088801)

    Parameters:

    • ids (Array<Integer>, Set<Integer>) —

      An array of Tweet IDs.

  • #favorite(*ids, options) ⇒ Array<Twitter::Tweet>

    Parameters:

    • ids (Array<Integer>, Set<Integer>) —

      An array of Tweet IDs.

    • options (Hash) —

      A customizable set of options.

Returns:

Raises:

See Also:



1400
1401
1402
1403
1404
1405
 
# File 'lib/twitter/api.rb', line 1400

def favorite(*args)
  options = args.extract_options!
  args.flatten.threaded_map do |id|
    object_from_response(Twitter::Tweet, :post, "/1.1/favorites/create.json", options.merge(:id => id))
  end
end

#favorites(options = {}) ⇒ Array<Twitter::Tweet> #favorites(user, options = {}) ⇒ Array<Twitter::Tweet>

Returns favorite Tweets.

Overloads:

  • #favorites(options = {}) ⇒ Array<Twitter::Tweet>

    Returns the 20 most recent favorite Tweets for the authenticating user

    Examples:

    Return the 20 most recent favorite Tweets for the authenticating user

    Twitter.favorites

    Parameters:

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :count (Integer) —

      Specifies the number of records to retrieve. Must be less than or equal to 100.

    • :since_id (Integer) —

      Returns results with an ID greater than (that is, more recent than) the specified ID.

  • #favorites(user, options = {}) ⇒ Array<Twitter::Tweet>

    Returns the 20 most recent favorite Tweets for the specified user

    Examples:

    Return the 20 most recent favorite Tweets for @sferik

    Twitter.favorites('sferik')

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :count (Integer) —

      Specifies the number of records to retrieve. Must be less than or equal to 100.

    • :since_id (Integer) —

      Returns results with an ID greater than (that is, more recent than) the specified ID.

Returns:

Raises:

See Also:



1378
1379
1380
1381
1382
1383
1384
 
# File 'lib/twitter/api.rb', line 1378

def favorites(*args)
  options = args.extract_options!
  if user = args.pop
    options.merge_user!(user)
  end
  collection_from_response(Twitter::Tweet, :get, "/1.1/favorites/list.json", options)
end

#follow(*args) ⇒ Array<Twitter::User> Also known as: friendship_create

Allows the authenticating user to follow the specified users, unless they are already followed

@overload(*users)

@param users [Array<Integer, String, Twitter::User>, Set<Integer, String, Twitter::User>] An array of Twitter user IDs, screen names, or objects.
@example Follow @sferik
  Twitter.follow('sferik')

@overload(*users, options)

@param users [Array<Integer, String, Twitter::User>, Set<Integer, String, Twitter::User>] An array of Twitter user IDs, screen names, or objects.
@param options [Hash] A customizable set of options.
@option options [Boolean] :follow (false) Enable notifications for the target user.

Returns:

Raises:

See Also:



464
465
466
467
468
469
470
471
472
473
474
475
476
 
# File 'lib/twitter/api.rb', line 464

def follow(*args)
  options = args.extract_options!
  # Twitter always turns on notifications if the "follow" option is present, even if it's set to false
  # so only send follow if it's true
  options[:follow] = true if !!options.delete(:follow)
  existing_friends = Thread.new do
    friend_ids.ids
  end
  new_friends = Thread.new do
    users(args).map(&:id)
  end
  follow!(new_friends.value - existing_friends.value, options)
end

#follow!(*users) ⇒ Array<Twitter::User> #follow!(*users, options) ⇒ Array<Twitter::User> Also known as: friendship_create!

Allows the authenticating user to follow the specified users

Overloads:

Returns:

Raises:

See Also:



494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
 
# File 'lib/twitter/api.rb', line 494

def follow!(*args)
  options = args.extract_options!
  # Twitter always turns on notifications if the "follow" option is present, even if it's set to false
  # so only send follow if it's true
  options[:follow] = true if !!options.delete(:follow)
  args.flatten.threaded_map do |user|
    begin
      options.merge_user!(user)
      object_from_response(Twitter::User, :post, "/1.1/friendships/create.json", options)
    rescue Twitter::Error::Forbidden
      # This error will be raised if the user doesn't have permission to
      # follow list_member, for whatever reason.
    end
  end.compact
end

#follower_ids(options = {}) ⇒ Twitter::Cursor #follower_ids(user, options = {}) ⇒ Twitter::Cursor

Overloads:

  • #follower_ids(options = {}) ⇒ Twitter::Cursor

    Returns an array of numeric IDs for every user following the authenticated user

    Examples:

    Return the authenticated user’s followers’ IDs

    Twitter.follower_ids

    Parameters:

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :cursor (Integer) — default: -1 —

      Breaks the results into pages. Provide values as returned in the response objects’s next_cursor and previous_cursor attributes to page back and forth in the list.

  • #follower_ids(user, options = {}) ⇒ Twitter::Cursor

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

    Examples:

    Return @sferik’s followers’ IDs

    Twitter.follower_ids('sferik')
Twitter.follower_ids(7505382)  # Same as above

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :cursor (Integer) — default: -1 —

      Breaks the results into pages. This is recommended for users who are following many users. Provide a value of -1 to begin paging. Provide values as returned in the response body’s next_cursor and previous_cursor attributes to page back and forth in the list.

Returns:

Raises:

See Also:



346
347
348
 
# File 'lib/twitter/api.rb', line 346

def follower_ids(*args)
  ids_from_response(:get, "/1.1/followers/ids.json", args)
end

#following_followers_of(options = {}) ⇒ Object #following_followers_of(user, options = {}) ⇒ Object

Note:

Undocumented

Overloads:

  • #following_followers_of(options = {}) ⇒ Object

    Returns users following followers of the specified user

    Examples:

    Return users follow followers of @sferik

    Twitter.following_followers_of

    Parameters:

    • options (Hash) (defaults to: {}) —

      A customizable set of options. @option options [Integer] :cursor (-1) Breaks the results into pages. Provide values as returned in the response objects’s next_cursor and previous_cursor attributes to page back and forth in the list. @return [Twitter::Cursor]

  • #following_followers_of(user, options = {}) ⇒ Object

    Returns users following followers of the authenticated user

    Examples:

    Return users follow followers of @sferik

    Twitter.following_followers_of('sferik')
Twitter.following_followers_of(7505382)  # Same as above

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options. @option options [Integer] :cursor (-1) Breaks the results into pages. Provide values as returned in the response objects’s next_cursor and previous_cursor attributes to page back and forth in the list. @return [Twitter::Cursor]

Raises:



2222
2223
2224
2225
2226
2227
 
# File 'lib/twitter/api.rb', line 2222

def following_followers_of(*args)
  options = args.extract_options!
  merge_default_cursor!(options)
  options.merge_user!(args.pop || screen_name)
  cursor_from_response(:users, Twitter::User, :get, "/users/following_followers_of.json", options)
end

#friend_ids(options = {}) ⇒ Twitter::Cursor #friend_ids(user, options = {}) ⇒ Twitter::Cursor

Overloads:

  • #friend_ids(options = {}) ⇒ Twitter::Cursor

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

    Examples:

    Return the authenticated user’s friends’ IDs

    Twitter.friend_ids

    Parameters:

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :cursor (Integer) — default: -1 —

      Breaks the results into pages. This is recommended for users who are following many users. Provide a value of -1 to begin paging. Provide values as returned in the response body’s next_cursor and previous_cursor attributes to page back and forth in the list.

  • #friend_ids(user, options = {}) ⇒ Twitter::Cursor

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

    Examples:

    Return @sferik’s friends’ IDs

    Twitter.friend_ids('sferik')
Twitter.friend_ids(7505382)  # Same as above

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :cursor (Integer) — default: -1 —

      Breaks the results into pages. Provide values as returned in the response objects’s next_cursor and previous_cursor attributes to page back and forth in the list.

Returns:

Raises:

See Also:



371
372
373
 
# File 'lib/twitter/api.rb', line 371

def friend_ids(*args)
  ids_from_response(:get, "/1.1/friends/ids.json", args)
end

#friendship(source, target, options = {}) ⇒ Twitter::Relationship Also known as: friendship_show, relationship

Returns detailed information about the relationship between two users

Examples:

Return the relationship between @sferik and @pengwynn

Twitter.friendship('sferik', 'pengwynn')
Twitter.friendship('sferik', 14100886)   # Same as above
Twitter.friendship(7505382, 14100886)    # Same as above

Parameters:

  • source (Integer, String, Twitter::User) —

    The Twitter user ID, screen name, or object of the source user.

  • target (Integer, String, Twitter::User) —

    The Twitter user ID, screen name, or object of the target user.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Returns:

Raises:

See Also:



439
440
441
442
443
444
445
 
# File 'lib/twitter/api.rb', line 439

def friendship(source, target, options={})
  options.merge_user!(source, "source")
  options[:source_id] = options.delete(:source_user_id) unless options[:source_user_id].nil?
  options.merge_user!(target, "target")
  options[:target_id] = options.delete(:target_user_id) unless options[:target_user_id].nil?
  object_from_response(Twitter::Relationship, :get, "/1.1/friendships/show.json", options)
end

#friendship?(source, target, options = {}) ⇒ Boolean

Test for the existence of friendship between two users

Examples:

Return true if @sferik follows @pengwynn

Twitter.friendship?('sferik', 'pengwynn')
Twitter.friendship?('sferik', 14100886)   # Same as above
Twitter.friendship?(7505382, 14100886)    # Same as above

Parameters:

  • source (Integer, String, Twitter::User) —

    The Twitter user ID, screen name, or object of the source user.

  • target (Integer, String, Twitter::User) —

    The Twitter user ID, screen name, or object of the target user.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Returns:

  • (Boolean) —

    true if user_a follows user_b, otherwise false.

Raises:

See Also:



389
390
391
 
# File 'lib/twitter/api.rb', line 389

def friendship?(source, target, options={})
  friendship(source, target, options).source.following?
end

#friendship_update(user, options = {}) ⇒ Twitter::Relationship

Allows one to enable or disable retweets and device notifications from the specified user.

Examples:

Enable rewteets and devise notifications for @sferik

Twitter.friendship_update('sferik', :device => true, :retweets => true)

Parameters:

  • user (Integer, String, Twitter::User) —

    A Twitter user ID, screen name, or object.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :device (Boolean) —

    Enable/disable device notifications from the target user.

  • :retweets (Boolean) —

    Enable/disable retweets from the target user.

Returns:

Raises:

See Also:



565
566
567
568
 
# File 'lib/twitter/api.rb', line 565

def friendship_update(user, options={})
  options.merge_user!(user)
  object_from_response(Twitter::Relationship, :post, "/1.1/friendships/update.json", options)
end

#friendships(*users) ⇒ Array<Twitter::User> #friendships(*users, options) ⇒ Array<Twitter::User>

Returns the relationship of the authenticating user to the comma separated list of up to 100 screen_names or user_ids provided. Values for connections can be: following, following_requested, followed_by, none.

Overloads:

Returns:

Raises:

See Also:



546
547
548
549
550
 
# File 'lib/twitter/api.rb', line 546

def friendships(*args)
  options = args.extract_options!
  options.merge_users!(Array(args))
  collection_from_response(Twitter::User, :get, "/1.1/friendships/lookup.json", options)
end

#friendships_incoming(options = {}) ⇒ Twitter::Cursor

Returns an array of numeric IDs for every user who has a pending request to follow the authenticating user

Examples:

Return an array of numeric IDs for every user who has a pending request to follow the authenticating user

Twitter.friendships_incoming

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :cursor (Integer) — default: -1 —

    Breaks the results into pages. Provide values as returned in the response objects’s next_cursor and previous_cursor attributes to page back and forth in the list.

Returns:

Raises:

See Also:



404
405
406
407
 
# File 'lib/twitter/api.rb', line 404

def friendships_incoming(options={})
  merge_default_cursor!(options)
  cursor_from_response(:ids, nil, :get, "/1.1/friendships/incoming.json", options)
end

#friendships_outgoing(options = {}) ⇒ Twitter::Cursor

Returns an array of numeric IDs for every protected user for whom the authenticating user has a pending follow request

Examples:

Return an array of numeric IDs for every protected user for whom the authenticating user has a pending follow request

Twitter.friendships_outgoing

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :cursor (Integer) — default: -1 —

    Breaks the results into pages. Provide values as returned in the response objects’s next_cursor and previous_cursor attributes to page back and forth in the list.

Returns:

Raises:

See Also:



420
421
422
423
 
# File 'lib/twitter/api.rb', line 420

def friendships_outgoing(options={})
  merge_default_cursor!(options)
  cursor_from_response(:ids, nil, :get, "/1.1/friendships/outgoing.json", options)
end

#home_timeline(options = {}) ⇒ Array<Twitter::Tweet>

Note:

This method can only return up to 800 Tweets, including retweets.

Returns the 20 most recent Tweets, including retweets if they exist, posted by the authenticating user and the users they follow

Examples:

Return the 20 most recent Tweets, including retweets if they exist, posted by the authenticating user and the users they follow

Twitter.home_timeline

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :since_id (Integer) —

    Returns results with an ID greater than (that is, more recent than) the specified ID.

  • :max_id (Integer) —

    Returns results with an ID less than (that is, older than) or equal to the specified ID.

  • :count (Integer) —

    Specifies the number of records to retrieve. Must be less than or equal to 200.

  • :trim_user (Boolean, String, Integer) —

    Each tweet returned in a timeline will include a user object with only the author’s numerical ID when set to true, ‘t’ or 1.

  • :exclude_replies (Boolean, String, Integer) —

    This parameter will prevent replies from appearing in the returned timeline. Using exclude_replies with the count parameter will mean you will receive up-to count tweets - this is because the count parameter retrieves that many tweets before filtering out retweets and replies.

  • :include_rts (Boolean, String, Integer) —

    Specifies that the timeline should include native retweets in addition to regular tweets. Note: If you’re using the trim_user parameter in conjunction with include_rts, the retweets will no longer contain a full user object.

  • :contributor_details (Boolean, String, Integer) —

    Specifies that the contributors element should be enhanced to include the screen_name of the contributor.

  • :include_entities (Boolean, String, Integer) —

    Specifies that each tweet should include an ‘entities’ node including metadata about the tweet such as: user_mentions, urls, and hashtags.

Returns:

Raises:

See Also:



1451
1452
1453
 
# File 'lib/twitter/api.rb', line 1451

def home_timeline(options={})
  collection_from_response(Twitter::Tweet, :get, "/1.1/statuses/home_timeline.json", options)
end

#languages(options = {}) ⇒ Array<Twitter::Language>

Returns the list of languages supported by Twitter

Examples:

Return the list of languages Twitter supports

Twitter.languages

Returns:

Raises:

See Also:



691
692
693
 
# File 'lib/twitter/api.rb', line 691

def languages(options={})
  collection_from_response(Twitter::Language, :get, "/1.1/help/languages.json", options)
end

#list(list, options = {}) ⇒ Twitter::List #list(user, list, options = {}) ⇒ Twitter::List

Note:

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

Show the specified list

Overloads:

  • #list(list, options = {}) ⇒ Twitter::List

    Examples:

    Show the authenticated user’s “presidents” list

    Twitter.list('presidents')
Twitter.list(8863586)

    Parameters:

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

  • #list(user, list, options = {}) ⇒ Twitter::List

    Examples:

    Show @sferik’s “presidents” list

    Twitter.list('sferik', 'presidents')
Twitter.list('sferik', 8863586)
Twitter.list(7505382, 'presidents')
Twitter.list(7505382, 8863586)

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, or object.

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

Returns:

Raises:

See Also:



1202
1203
1204
 
# File 'lib/twitter/api.rb', line 1202

def list(*args)
  list_from_response(:get, "/1.1/lists/show.json", args)
end

#list_add_member(list, user_to_add, options = {}) ⇒ Twitter::List #list_add_member(user, list, user_to_add, options = {}) ⇒ Twitter::List

Note:

Lists are limited to having 500 members.

Add a member to a list

Overloads:

  • #list_add_member(list, user_to_add, options = {}) ⇒ Twitter::List

    Examples:

    Add @BarackObama to the authenticated user’s “presidents” list

    Twitter.list_add_member('presidents', 813286)
Twitter.list_add_member(8863586, 813286)

    Parameters:

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, or object.

    • user_to_add (Integer, String) —

      The user id or screen name to add to the list.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

  • #list_add_member(user, list, user_to_add, options = {}) ⇒ Twitter::List

    Examples:

    Add @BarackObama to @sferik’s “presidents” list

    Twitter.list_add_member('sferik', 'presidents', 813286)
Twitter.list_add_member('sferik', 8863586, 813286)
Twitter.list_add_member(7505382, 'presidents', 813286)
Twitter.list_add_member(7505382, 8863586, 813286)

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, or object.

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, or object.

    • user_to_add (Integer, String) —

      The user id or screen name to add to the list.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

Returns:

Raises:

See Also:



1083
1084
1085
 
# File 'lib/twitter/api.rb', line 1083

def list_add_member(*args)
  list_modify_member(:post, "/1.1/lists/members/create.json", args)
end

#list_add_members(list, users, options = {}) ⇒ Twitter::List #list_add_members(user, list, users, options = {}) ⇒ Twitter::List

Note:

Lists are limited to having 500 members, and you are limited to adding up to 100 members to a list at a time with this method.

Adds specified members to a list

Overloads:

  • #list_add_members(list, users, options = {}) ⇒ Twitter::List

    Examples:

    Add @BarackObama and @pengwynn to the authenticated user’s “presidents” list

    Twitter.list_add_members('presidents', ['BarackObama', 'pengwynn'])
Twitter.list_add_members('presidents', [813286, 18755393])
Twitter.list_add_members(8863586, ['BarackObama', 'pengwynn'])
Twitter.list_add_members(8863586, [813286, 18755393])

    Parameters:

  • #list_add_members(user, list, users, options = {}) ⇒ Twitter::List

    Examples:

    Add @BarackObama and @pengwynn to @sferik’s “presidents” list

    Twitter.list_add_members('sferik', 'presidents', ['BarackObama', 'pengwynn'])
Twitter.list_add_members('sferik', 'presidents', [813286, 18755393])
Twitter.list_add_members(7505382, 'presidents', ['BarackObama', 'pengwynn'])
Twitter.list_add_members(7505382, 'presidents', [813286, 18755393])
Twitter.list_add_members(7505382, 8863586, ['BarackObama', 'pengwynn'])
Twitter.list_add_members(7505382, 8863586, [813286, 18755393])

    Parameters:

Returns:

Raises:

See Also:



967
968
969
 
# File 'lib/twitter/api.rb', line 967

def list_add_members(*args)
  list_modify_members(:post, "/1.1/lists/members/create_all.json", args)
end

#list_create(name, options = {}) ⇒ Twitter::List

Note:

Accounts are limited to 20 lists.

Creates a new list for the authenticated user

Examples:

Create a list named ‘presidents’

Twitter.list_create('presidents')

Parameters:

  • name (String) —

    The name for the list.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :mode (String) — default: 'public' —

    Whether your list is public or private. Values can be ‘public’ or ‘private’.

  • :description (String) —

    The description to give the list.

Returns:

Raises:

See Also:



1158
1159
1160
 
# File 'lib/twitter/api.rb', line 1158

def list_create(name, options={})
  object_from_response(Twitter::List, :post, "/1.1/lists/create.json", options.merge(:name => name))
end

#list_destroy(list, options = {}) ⇒ Twitter::List #list_destroy(user, list, options = {}) ⇒ Twitter::List

Note:

Must be owned by the authenticated user.

Deletes the specified list

Overloads:

  • #list_destroy(list, options = {}) ⇒ Twitter::List

    Examples:

    Delete the authenticated user’s “presidents” list

    Twitter.list_destroy('presidents')
Twitter.list_destroy(8863586)

    Parameters:

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

  • #list_destroy(user, list, options = {}) ⇒ Twitter::List

    Examples:

    Delete @sferik’s “presidents” list

    Twitter.list_destroy('sferik', 'presidents')
Twitter.list_destroy('sferik', 8863586)
Twitter.list_destroy(7505382, 'presidents')
Twitter.list_destroy(7505382, 8863586)

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, or object.

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

Returns:

Raises:

See Also:



1110
1111
1112
 
# File 'lib/twitter/api.rb', line 1110

def list_destroy(*args)
  list_from_response(:post, "/1.1/lists/destroy.json", args)
end

#list_member?(list, user_to_check, options = {}) ⇒ Boolean #list_member?(user, list, user_to_check, options = {}) ⇒ Boolean

Check if a user is a member of the specified list

Overloads:

  • #list_member?(list, user_to_check, options = {}) ⇒ Boolean

    Examples:

    Check if @BarackObama is a member of the authenticated user’s “presidents” list

    Twitter.list_member?('presidents', 813286)
Twitter.list_member?(8863586, 'BarackObama')

    Parameters:

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, or object.

    • user_to_check (Integer, String) —

      The user ID or screen name of the list member.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

  • #list_member?(user, list, user_to_check, options = {}) ⇒ Boolean

    Examples:

    Check if @BarackObama is a member of @sferik’s “presidents” list

    Twitter.list_member?('sferik', 'presidents', 813286)
Twitter.list_member?('sferik', 8863586, 'BarackObama')
Twitter.list_member?(7505382, 'presidents', 813286)

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, or object.

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, or object.

    • user_to_check (Integer, String) —

      The user ID or screen name of the list member.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

Returns:

  • (Boolean) —

    true if user is a member of the specified list, otherwise false.

Raises:

See Also:



1026
1027
1028
 
# File 'lib/twitter/api.rb', line 1026

def list_member?(*args)
  list_user?(:get, "/1.1/lists/members/show.json", args)
end

#list_members(list, options = {}) ⇒ Twitter::Cursor #list_members(user, list, options = {}) ⇒ Twitter::Cursor

Returns the members of the specified list

Overloads:

  • #list_members(list, options = {}) ⇒ Twitter::Cursor

    Examples:

    Return the members of the authenticated user’s “presidents” list

    Twitter.list_members('presidents')
Twitter.list_members(8863586)

    Parameters:

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :cursor (Integer) — default: -1 —

      Breaks the results into pages. Provide values as returned in the response objects’s next_cursor and previous_cursor attributes to page back and forth in the list.

  • #list_members(user, list, options = {}) ⇒ Twitter::Cursor

    Examples:

    Return the members of @sferik’s “presidents” list

    Twitter.list_members('sferik', 'presidents')
Twitter.list_members('sferik', 8863586)
Twitter.list_members(7505382, 'presidents')
Twitter.list_members(7505382, 8863586)

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, or object.

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :cursor (Integer) — default: -1 —

      Breaks the results into pages. Provide values as returned in the response objects’s next_cursor and previous_cursor attributes to page back and forth in the list.

Returns:

Raises:

See Also:



1054
1055
1056
 
# File 'lib/twitter/api.rb', line 1054

def list_members(*args)
  list_users(:get, "/1.1/lists/members.json", args)
end

#list_remove_member(list, user_to_remove, options = {}) ⇒ Twitter::List #list_remove_member(user, list, user_to_remove, options = {}) ⇒ Twitter::List

Removes the specified member from the list

Overloads:

  • #list_remove_member(list, user_to_remove, options = {}) ⇒ Twitter::List

    Examples:

    Remove @BarackObama from the authenticated user’s “presidents” list

    Twitter.list_remove_member('presidents', 813286)
Twitter.list_remove_member('presidents', 'BarackObama')
Twitter.list_remove_member(8863586, 'BarackObama')

    Parameters:

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, or object.

    • user_to_remove (Integer, String) —

      The user id or screen name of the list member to remove.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

  • #list_remove_member(user, list, user_to_remove, options = {}) ⇒ Twitter::List

    Examples:

    Remove @BarackObama from @sferik’s “presidents” list

    Twitter.list_remove_member('sferik', 'presidents', 813286)
Twitter.list_remove_member('sferik', 'presidents', 'BarackObama')
Twitter.list_remove_member('sferik', 8863586, 'BarackObama')
Twitter.list_remove_member(7505382, 'presidents', 813286)

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, or object.

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, or object.

    • user_to_remove (Integer, String) —

      The user id or screen name of the list member to remove.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

Returns:

Raises:

See Also:



781
782
783
 
# File 'lib/twitter/api.rb', line 781

def list_remove_member(*args)
  list_modify_member(:post, "/1.1/lists/members/destroy.json", args)
end

#list_remove_members(list, users, options = {}) ⇒ Twitter::List #list_remove_members(user, list, users, options = {}) ⇒ Twitter::List

Removes specified members from the list

Overloads:

  • #list_remove_members(list, users, options = {}) ⇒ Twitter::List

    Examples:

    Remove @BarackObama and @pengwynn from the authenticated user’s “presidents” list

    Twitter.list_remove_members('presidents', ['BarackObama', 'pengwynn'])
Twitter.list_remove_members('presidents', [813286, 18755393])
Twitter.list_remove_members(8863586, ['BarackObama', 'pengwynn'])
Twitter.list_remove_members(8863586, [813286, 18755393])

    Parameters:

  • #list_remove_members(user, list, users, options = {}) ⇒ Twitter::List

    Examples:

    Remove @BarackObama and @pengwynn from @sferik’s “presidents” list

    Twitter.list_remove_members('sferik', 'presidents', ['BarackObama', 'pengwynn'])
Twitter.list_remove_members('sferik', 'presidents', [813286, 18755393])
Twitter.list_remove_members(7505382, 'presidents', ['BarackObama', 'pengwynn'])
Twitter.list_remove_members(7505382, 'presidents', [813286, 18755393])
Twitter.list_remove_members(7505382, 8863586, ['BarackObama', 'pengwynn'])
Twitter.list_remove_members(7505382, 8863586, [813286, 18755393])

    Parameters:

Returns:

Raises:

See Also:



999
1000
1001
 
# File 'lib/twitter/api.rb', line 999

def list_remove_members(*args)
  list_modify_members(:post, "/1.1/lists/members/destroy_all.json", args)
end

#list_subscribe(list, options = {}) ⇒ Twitter::List #list_subscribe(user, list, options = {}) ⇒ Twitter::List

Make the authenticated user follow the specified list

Overloads:

  • #list_subscribe(list, options = {}) ⇒ Twitter::List

    Examples:

    Subscribe to the authenticated user’s “presidents” list

    Twitter.list_subscribe('presidents')
Twitter.list_subscribe(8863586)

    Parameters:

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

  • #list_subscribe(user, list, options = {}) ⇒ Twitter::List

    Examples:

    Subscribe to @sferik’s “presidents” list

    Twitter.list_subscribe('sferik', 'presidents')
Twitter.list_subscribe('sferik', 8863586)
Twitter.list_subscribe(7505382, 'presidents')

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, or object.

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

Returns:

Raises:

See Also:



879
880
881
 
# File 'lib/twitter/api.rb', line 879

def list_subscribe(*args)
  list_from_response(:post, "/1.1/lists/subscribers/create.json", args)
end

#list_subscriber?(list, user_to_check, options = {}) ⇒ Boolean #list_subscriber?(user, list, user_to_check, options = {}) ⇒ Boolean

Check if a user is a subscriber of the specified list

Overloads:

  • #list_subscriber?(list, user_to_check, options = {}) ⇒ Boolean

    Examples:

    Check if @BarackObama is a subscriber of the authenticated user’s “presidents” list

    Twitter.list_subscriber?('presidents', 813286)
Twitter.list_subscriber?(8863586, 813286)
Twitter.list_subscriber?('presidents', 'BarackObama')

    Parameters:

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, or object.

    • user_to_check (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

  • #list_subscriber?(user, list, user_to_check, options = {}) ⇒ Boolean

    Examples:

    Check if @BarackObama is a subscriber of @sferik’s “presidents” list

    Twitter.list_subscriber?('sferik', 'presidents', 813286)
Twitter.list_subscriber?('sferik', 8863586, 813286)
Twitter.list_subscriber?(7505382, 'presidents', 813286)
Twitter.list_subscriber?('sferik', 'presidents', 'BarackObama')

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, or object.

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, or object.

    • user_to_check (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

Returns:

  • (Boolean) —

    true if user is a subscriber of the specified list, otherwise false.

  • (Boolean) —

    true if user is a subscriber of the specified list, otherwise false.

Raises:

See Also:



909
910
911
 
# File 'lib/twitter/api.rb', line 909

def list_subscriber?(*args)
  list_user?(:get, "/1.1/lists/subscribers/show.json", args)
end

#list_subscribers(list, options = {}) ⇒ Twitter::Cursor #list_subscribers(user, list, options = {}) ⇒ Twitter::Cursor

Returns the subscribers of the specified list

Overloads:

  • #list_subscribers(list, options = {}) ⇒ Twitter::Cursor

    Examples:

    Return the subscribers of the authenticated user’s “presidents” list

    Twitter.list_subscribers('presidents')
Twitter.list_subscribers(8863586)

    Parameters:

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :cursor (Integer) — default: -1 —

      Breaks the results into pages. Provide values as returned in the response objects’s next_cursor and previous_cursor attributes to page back and forth in the list.

  • #list_subscribers(user, list, options = {}) ⇒ Twitter::Cursor

    Examples:

    Return the subscribers of @sferik’s “presidents” list

    Twitter.list_subscribers('sferik', 'presidents')
Twitter.list_subscribers('sferik', 8863586)
Twitter.list_subscribers(7505382, 'presidents')

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, or object.

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :cursor (Integer) — default: -1 —

      Breaks the results into pages. Provide values as returned in the response objects’s next_cursor and previous_cursor attributes to page back and forth in the list.

Returns:

Raises:

See Also:



831
832
833
 
# File 'lib/twitter/api.rb', line 831

def list_subscribers(*args)
  list_users(:get, "/1.1/lists/subscribers.json", args)
end

#list_timeline(list, options = {}) ⇒ Array<Twitter::Tweet> #list_timeline(user, list, options = {}) ⇒ Array<Twitter::Tweet>

Show tweet timeline for members of the specified list

Overloads:

  • #list_timeline(list, options = {}) ⇒ Array<Twitter::Tweet>

    Examples:

    Show tweet timeline for members of the authenticated user’s “presidents” list

    Twitter.list_timeline('presidents')
Twitter.list_timeline(8863586)

    Parameters:

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :since_id (Integer) —

      Returns results with an ID greater than (that is, more recent than) the specified ID.

    • :max_id (Integer) —

      Returns results with an ID less than (that is, older than) or equal to the specified ID.

    • :count (Integer) —

      The number of results to retrieve.

  • #list_timeline(user, list, options = {}) ⇒ Array<Twitter::Tweet>

    Examples:

    Show tweet timeline for members of @sferik’s “presidents” list

    Twitter.list_timeline('sferik', 'presidents')
Twitter.list_timeline('sferik', 8863586)
Twitter.list_timeline(7505382, 'presidents')
Twitter.list_timeline(7505382, 8863586)

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, or object.

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :since_id (Integer) —

      Returns results with an ID greater than (that is, more recent than) the specified ID.

    • :max_id (Integer) —

      Returns results with an ID less than (that is, older than) or equal to the specified ID.

    • :count (Integer) —

      The number of results to retrieve.

Returns:

Raises:

See Also:



749
750
751
752
753
754
 
# File 'lib/twitter/api.rb', line 749

def list_timeline(*args)
  options = args.extract_options!
  options.merge_list!(args.pop)
  options.merge_owner!(args.pop || screen_name) unless options[:owner_id] || options[:owner_screen_name]
  collection_from_response(Twitter::Tweet, :get, "/1.1/lists/statuses.json", options)
end

#list_unsubscribe(list, options = {}) ⇒ Twitter::List #list_unsubscribe(user, list, options = {}) ⇒ Twitter::List

Unsubscribes the authenticated user form the specified list

Overloads:

  • #list_unsubscribe(list, options = {}) ⇒ Twitter::List

    Examples:

    Unsubscribe from the authenticated user’s “presidents” list

    Twitter.list_unsubscribe('presidents')
Twitter.list_unsubscribe(8863586)

    Parameters:

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

  • #list_unsubscribe(user, list, options = {}) ⇒ Twitter::List

    Examples:

    Unsubscribe from @sferik’s “presidents” list

    Twitter.list_unsubscribe('sferik', 'presidents')
Twitter.list_unsubscribe('sferik', 8863586)
Twitter.list_unsubscribe(7505382, 'presidents')

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, or object.

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

Returns:

Raises:

See Also:



934
935
936
 
# File 'lib/twitter/api.rb', line 934

def list_unsubscribe(*args)
  list_from_response(:post, "/1.1/lists/subscribers/destroy.json", args)
end

#list_update(list, options = {}) ⇒ Twitter::List #list_update(user, list, options = {}) ⇒ Twitter::List

Updates the specified list

Overloads:

  • #list_update(list, options = {}) ⇒ Twitter::List

    Examples:

    Update the authenticated user’s “presidents” list to have the description “Presidents of the United States of America”

    Twitter.list_update('presidents', :description => "Presidents of the United States of America")
Twitter.list_update(8863586, :description => "Presidents of the United States of America")

    Parameters:

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :mode (String) — default: 'public' —

      Whether your list is public or private. Values can be ‘public’ or ‘private’.

    • :description (String) —

      The description to give the list.

  • #list_update(user, list, options = {}) ⇒ Twitter::List

    Examples:

    Update the @sferik’s “presidents” list to have the description “Presidents of the United States of America”

    Twitter.list_update('sferik', 'presidents', :description => "Presidents of the United States of America")
Twitter.list_update(7505382, 'presidents', :description => "Presidents of the United States of America")
Twitter.list_update('sferik', 8863586, :description => "Presidents of the United States of America")
Twitter.list_update(7505382, 8863586, :description => "Presidents of the United States of America")

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, or object.

    • list (Integer, String, Twitter::List) —

      A Twitter list ID, slug, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :mode (String) — default: 'public' —

      Whether your list is public or private. Values can be ‘public’ or ‘private’.

    • :description (String) —

      The description to give the list.

Returns:

Raises:

See Also:



1140
1141
1142
 
# File 'lib/twitter/api.rb', line 1140

def list_update(*args)
  list_from_response(:post, "/1.1/lists/update.json", args)
end

#lists(*args) ⇒ Twitter::Cursor Also known as: lists_subscribed_to

List the lists of the specified user Returns all lists the authenticating or specified user subscribes to, including their own.

Examples:

List the authenticated user’s lists

Twitter.lists

Parameters:

  • options (Hash) —

    A customizable set of options.

Returns:

Raises:

See Also:



1174
1175
1176
 
# File 'lib/twitter/api.rb', line 1174

def lists(*args)
  lists_from_response(:get, "/1.1/lists/list.json", args)
end

#media_timeline(user, options = {}) ⇒ Array<Twitter::Tweet>

Note:

This method can only return up to the 100 most recent images.

Note:

Images will not be returned from tweets posted before January 1, 2010.

Returns the 20 most recent images posted by the specified user

Examples:

Return the 20 most recent Tweets posted by @sferik

Twitter.media_timeline('sferik')

Parameters:

  • user (Integer, String, Twitter::User) —

    A Twitter user ID, screen name, or object.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :count (Integer) —

    Specifies the number of records to retrieve. Must be less than or equal to 200.

  • :filter (Boolean) —

    Include possibly sensitive media when set to false, ‘f’ or 0.

Returns:

Raises:

See Also:



1619
1620
1621
 
# File 'lib/twitter/api.rb', line 1619

def media_timeline(*args)
  objects_from_response(Twitter::Tweet, :get, "/1.1/statuses/media_timeline.json", args)
end

#memberships(options = {}) ⇒ Twitter::Cursor #memberships(user, options = {}) ⇒ Twitter::Cursor

List the lists the specified user has been added to

Overloads:

  • #memberships(options = {}) ⇒ Twitter::Cursor

    Examples:

    List the lists the authenticated user has been added to

    Twitter.memberships

    Parameters:

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :cursor (Integer) — default: -1 —

      Breaks the results into pages. Provide values as returned in the response objects’s next_cursor and previous_cursor attributes to page back and forth in the list.

  • #memberships(user, options = {}) ⇒ Twitter::Cursor

    Examples:

    List the lists that @sferik has been added to

    Twitter.memberships('sferik')
Twitter.memberships(7505382)

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :cursor (Integer) — default: -1 —

      Breaks the results into pages. Provide values as returned in the response objects’s next_cursor and previous_cursor attributes to page back and forth in the list.

Returns:

Raises:

See Also:



804
805
806
 
# File 'lib/twitter/api.rb', line 804

def memberships(*args)
  lists_from_response(:get, "/1.1/lists/memberships.json", args)
end

#mentions_timeline(options = {}) ⇒ Array<Twitter::Tweet> Also known as: mentions

Note:

This method can only return up to 800 Tweets.

Returns the 20 most recent mentions (statuses containing @username) for the authenticating user

Examples:

Return the 20 most recent mentions (statuses containing @username) for the authenticating user

Twitter.mentions

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :since_id (Integer) —

    Returns results with an ID greater than (that is, more recent than) the specified ID.

  • :max_id (Integer) —

    Returns results with an ID less than (that is, older than) or equal to the specified ID.

  • :count (Integer) —

    Specifies the number of records to retrieve. Must be less than or equal to 200.

  • :trim_user (Boolean, String, Integer) —

    Each tweet returned in a timeline will include a user object with only the author’s numerical ID when set to true, ‘t’ or 1.

Returns:

Raises:

See Also:



1470
1471
1472
 
# File 'lib/twitter/api.rb', line 1470

def mentions_timeline(options={})
  collection_from_response(Twitter::Tweet, :get, "/1.1/statuses/mentions_timeline.json", options)
end

#oembed(id, options = {}) ⇒ Twitter::OEmbed

Returns oEmbed for a Tweet

Examples:

Return oEmbeds for Tweet with the ID 25938088801

Twitter.status_with_activity(25938088801)

Parameters:

  • id (Integer, String) —

    A Tweet ID.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :maxwidth (Integer) —

    The maximum width in pixels that the embed should be rendered at. This value is constrained to be between 250 and 550 pixels.

  • :hide_media (Boolean, String, Integer) —

    Specifies whether the embedded Tweet should automatically expand images which were uploaded via POST statuses/update_with_media. When set to either true, t or 1 images will not be expanded. Defaults to false.

  • :hide_thread (Boolean, String, Integer) —

    Specifies whether the embedded Tweet should automatically show the original message in the case that the embedded Tweet is a reply. When set to either true, t or 1 the original Tweet will not be shown. Defaults to false.

  • :omit_script (Boolean, String, Integer) —

    Specifies whether the embedded Tweet HTML should include a ‘<script>` element pointing to widgets.js. In cases where a page already includes widgets.js, setting this value to true will prevent a redundant script element from being included. When set to either true, t or 1 the `<script>` element will not be included in the embed HTML, meaning that pages must include a reference to widgets.js manually. Defaults to false.

  • :align (String) —

    Specifies whether the embedded Tweet should be left aligned, right aligned, or centered in the page. Valid values are left, right, center, and none. Defaults to none, meaning no alignment styles are specified for the Tweet.

  • :related (String) —

    A value for the TWT related parameter, as described in Web Intents. This value will be forwarded to all Web Intents calls.

  • :lang (String) —

    Language code for the rendered embed. This will affect the text and localization of the rendered HTML.

Returns:

Raises:

See Also:



1754
1755
1756
 
# File 'lib/twitter/api.rb', line 1754

def oembed(id, options={})
  object_from_response(Twitter::OEmbed, :get, "/1.1/statuses/oembed.json?id=#{id}", options)
end

#oembed(*ids_or_urls) ⇒ Array<Twitter::OEmbed> #oembed(*ids_or_urls, options) ⇒ Array<Twitter::OEmbed>

Returns oEmbeds for Tweets

Overloads:

  • #oembed(*ids_or_urls) ⇒ Array<Twitter::OEmbed>

    Examples:

    Return oEmbeds for Tweets with the ID 25938088801

    Twitter.status_with_activity(25938088801)

    Parameters:

    • ids_or_urls (Array<Integer, String>, Set<Integer, String>) —

      An array of Tweet IDs or URLs.

  • #oembed(*ids_or_urls, options) ⇒ Array<Twitter::OEmbed>

    Parameters:

    • ids_or_urls (Array<Integer, String>, Set<Integer, String>) —

      An array of Tweet IDs or URLs.

    • options (Hash) —

      A customizable set of options.

    Options Hash (options):

    • :maxwidth (Integer) —

      The maximum width in pixels that the embed should be rendered at. This value is constrained to be between 250 and 550 pixels.

    • :hide_media (Boolean, String, Integer) —

      Specifies whether the embedded Tweet should automatically expand images which were uploaded via POST statuses/update_with_media. When set to either true, t or 1 images will not be expanded. Defaults to false.

    • :hide_thread (Boolean, String, Integer) —

      Specifies whether the embedded Tweet should automatically show the original message in the case that the embedded Tweet is a reply. When set to either true, t or 1 the original Tweet will not be shown. Defaults to false.

    • :omit_script (Boolean, String, Integer) —

      Specifies whether the embedded Tweet HTML should include a ‘<script>` element pointing to widgets.js. In cases where a page already includes widgets.js, setting this value to true will prevent a redundant script element from being included. When set to either true, t or 1 the `<script>` element will not be included in the embed HTML, meaning that pages must include a reference to widgets.js manually. Defaults to false.

    • :align (String) —

      Specifies whether the embedded Tweet should be left aligned, right aligned, or centered in the page. Valid values are left, right, center, and none. Defaults to none, meaning no alignment styles are specified for the Tweet.

    • :related (String) —

      A value for the TWT related parameter, as described in Web Intents. This value will be forwarded to all Web Intents calls.

    • :lang (String) —

      Language code for the rendered embed. This will affect the text and localization of the rendered HTML.

Returns:

Raises:

See Also:



1779
1780
1781
1782
1783
1784
 
# File 'lib/twitter/api.rb', line 1779

def oembeds(*args)
  options = args.extract_options!
  args.flatten.threaded_map do |id|
    object_from_response(Twitter::OEmbed, :get, "/1.1/statuses/oembed.json?id=#{id}", options)
  end
end

#phoenix_search(q, options = {}) ⇒ Array<Twitter::Tweet>

Note:

Undocumented

Returns recent Tweets related to a query with images and videos embedded

Examples:

Return recent Tweets related to twitter with images and videos embedded

Twitter.phoenix_search('twitter')

Parameters:

  • q (String) —

    A search term.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :count (Integer) —

    Specifies the number of records to retrieve. Must be less than or equal to 100.

  • :since_id (Integer) —

    Returns results with an ID greater than (that is, more recent than) the specified ID.

Returns:



1352
1353
1354
 
# File 'lib/twitter/api.rb', line 1352

def phoenix_search(q, options={})
  search_collection_from_response(:get, "/phoenix_search.phoenix", options.merge(:q => q))
end

#place(place_id, options = {}) ⇒ Twitter::Place

Returns all the information about a known place

Examples:

Return all the information about Twitter HQ

Twitter.place("247f43d441defc03")

Parameters:

  • place_id (String) —

    A place in the world. These IDs can be retrieved from Twitter::API::Geo#reverse_geocode.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Returns:

Raises:

See Also:



645
646
647
 
# File 'lib/twitter/api.rb', line 645

def place(place_id, options={})
  object_from_response(Twitter::Place, :get, "/1.1/geo/id/#{place_id}.json", options)
end

#place_create(options = {}) ⇒ Twitter::Place

Creates a new place at the given latitude and longitude

Examples:

Create a new place

Twitter.place_create(:name => "@sferik's Apartment", :token => "22ff5b1f7159032cf69218c4d8bb78bc", :contained_within => "41bcb736f84a799e", :lat => "37.783699", :long => "-122.393581")

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :name (String) —

    The name a place is known as.

  • :contained_within (String) —

    This is the place_id which you would like to restrict the search results to. Setting this value means only places within the given place_id will be found.

  • :token (String) —

    The token found in the response from Twitter::API::Geo#places_similar.

  • :lat (Float) —

    The latitude to search around. This option will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn’t a corresponding :long option.

  • :long (Float) —

    The longitude to search around. The valid range for longitude is -180.0 to +180.0 (East is positive) inclusive. This option will be ignored if outside that range, if it is not a number, if geo_enabled is disabled, or if there not a corresponding :lat option.

  • :"attribute:street_address" (String) —

    This option searches for places which have this given street address. There are other well-known and application-specific attributes available. Custom attributes are also permitted.

Returns:

Raises:

See Also:



665
666
667
 
# File 'lib/twitter/api.rb', line 665

def place_create(options={})
  object_from_response(Twitter::Place, :post, "/1.1/geo/place.json", options)
end

#places_nearby(options = {}) ⇒ Array<Twitter::Place> Also known as: geo_search

Search for places that can be attached to a Twitter::API::Statuses#update

Examples:

Return an array of places near the IP address 74.125.19.104

Twitter.places_nearby(:ip => "74.125.19.104")

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :lat (Float) —

    The latitude to search around. This option will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn’t a corresponding :long option.

  • :long (Float) —

    The longitude to search around. The valid range for longitude is -180.0 to +180.0 (East is positive) inclusive. This option will be ignored if outside that range, if it is not a number, if geo_enabled is disabled, or if there not a corresponding :lat option.

  • :query (String) —

    Free-form text to match against while executing a geo-based query, best suited for finding nearby locations by name.

  • :ip (String) —

    An IP address. Used when attempting to fix geolocation based off of the user’s IP address.

  • :granularity (String) — default: 'neighborhood' —

    This is the minimal granularity of place types to return and must be one of: ‘poi’, ‘neighborhood’, ‘city’, ‘admin’ or ‘country’.

  • :accuracy (String) — default: '0m' —

    A hint on the “region” in which to search. If a number, then this is a radius in meters, but it can also take a string that is suffixed with ft to specify feet. If coming from a device, in practice, this value is whatever accuracy the device has measuring its location (whether it be coming from a GPS, WiFi triangulation, etc.).

  • :max_results (Integer) —

    A hint as to the number of results to return. This does not guarantee that the number of results returned will equal max_results, but instead informs how many “nearby” results to return. Ideally, only pass in the number of places you intend to display to the user here.

  • :contained_within (String) —

    This is the place_id which you would like to restrict the search results to. Setting this value means only places within the given place_id will be found.

  • :"attribute:street_address" (String) —

    This option searches for places which have this given street address. There are other well-known and application-specific attributes available. Custom attributes are also permitted.

Returns:

Raises:

See Also:



589
590
591
 
# File 'lib/twitter/api.rb', line 589

def places_nearby(options={})
  geo_collection_from_response(:get, "/1.1/geo/search.json", options)
end

#places_similar(options = {}) ⇒ Array<Twitter::Place>

Note:

Conceptually, you would use this method to get a list of known places to choose from first. Then, if the desired place doesn’t exist, make a request to Twitter::API::Geo#place to create a new one. The token contained in the response is the token necessary to create a new place.

Locates places near the given coordinates which are similar in name

Examples:

Return an array of places similar to Twitter HQ

Twitter.places_similar(:lat => "37.7821120598956", :long => "-122.400612831116", :name => "Twitter HQ")

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :lat (Float) —

    The latitude to search around. This option will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn’t a corresponding :long option.

  • :long (Float) —

    The longitude to search around. The valid range for longitude is -180.0 to +180.0 (East is positive) inclusive. This option will be ignored if outside that range, if it is not a number, if geo_enabled is disabled, or if there not a corresponding :lat option.

  • :name (String) —

    The name a place is known as.

  • :contained_within (String) —

    This is the place_id which you would like to restrict the search results to. Setting this value means only places within the given place_id will be found.

  • :"attribute:street_address" (String) —

    This option searches for places which have this given street address. There are other well-known and application-specific attributes available. Custom attributes are also permitted.

Returns:

Raises:

See Also:



610
611
612
 
# File 'lib/twitter/api.rb', line 610

def places_similar(options={})
  geo_collection_from_response(:get, "/1.1/geo/similar_places.json", options)
end

#privacy(options = {}) ⇒ String

Returns Twitter’s Privacy Policy

Examples:

Return Twitter’s Privacy Policy

Twitter.privacy

Returns:

Raises:

See Also:



704
705
706
 
# File 'lib/twitter/api.rb', line 704

def privacy(options={})
  get("/1.1/help/privacy.json", options)[:body][:privacy]
end

#report_spam(*users) ⇒ Array<Twitter::User> #report_spam(*users, options) ⇒ Array<Twitter::User>

The users specified are blocked by the authenticated user and reported as spammers

Overloads:

Returns:

Raises:

See Also:



1221
1222
1223
 
# File 'lib/twitter/api.rb', line 1221

def report_spam(*args)
  threaded_users_from_response(:post, "/1.1/report_spam.json", args)
end

#retweet(*ids) ⇒ Array<Twitter::Tweet> #retweet(*ids, options) ⇒ Array<Twitter::Tweet>

Retweets tweets

Overloads:

  • #retweet(*ids) ⇒ Array<Twitter::Tweet>

    Examples:

    Retweet the Tweet with the ID 28561922516

    Twitter.retweet(28561922516)

    Parameters:

    • ids (Array<Integer>, Set<Integer>) —

      An array of Tweet IDs.

  • #retweet(*ids, options) ⇒ Array<Twitter::Tweet>

    Parameters:

    • ids (Array<Integer>, Set<Integer>) —

      An array of Tweet IDs.

    • options (Hash) —

      A customizable set of options.

    Options Hash (options):

    • :trim_user (Boolean, String, Integer) —

      Each tweet returned in a timeline will include a user object with only the author’s numerical ID when set to true, ‘t’ or 1.

Returns:

Raises:

See Also:



1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
 
# File 'lib/twitter/api.rb', line 1822

def retweet(*args)
  options = args.extract_options!
  args.flatten.threaded_map do |id|
    response = post("/1.1/statuses/retweet/#{id}.json", options)
    retweeted_status = response.dup
    retweeted_status[:body] = response[:body].delete(:retweeted_status)
    retweeted_status[:body][:retweeted_status] = response[:body]
    Twitter::Tweet.from_response(retweeted_status)
  end
end

#retweeted_by_me(options = {}) ⇒ Array<Twitter::Tweet>

Note:

This method can only return up to 3,200 Tweets.

Returns the 20 most recent retweets posted by the authenticating user

Examples:

Return the 20 most recent retweets posted by the authenticating user

Twitter.retweeted_by_me

Parameters:

  • user (Integer, String, Twitter::User) —

    A Twitter user ID, screen name, or object.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :since_id (Integer) —

    Returns results with an ID greater than (that is, more recent than) the specified ID.

  • :max_id (Integer) —

    Returns results with an ID less than (that is, older than) or equal to the specified ID.

  • :count (Integer) —

    Specifies the number of records to retrieve. Must be less than or equal to 200.

  • :trim_user (Boolean, String, Integer) —

    Each tweet returned in a timeline will include a user object with only the author’s numerical ID when set to true, ‘t’ or 1.

  • :exclude_replies (Boolean, String, Integer) —

    This parameter will prevent replies from appearing in the returned timeline. Using exclude_replies with the count parameter will mean you will receive up-to count tweets - this is because the count parameter retrieves that many tweets before filtering out retweets and replies.

  • :contributor_details (Boolean, String, Integer) —

    Specifies that the contributors element should be enhanced to include the screen_name of the contributor.

Returns:

Raises:

See Also:



1520
1521
1522
1523
1524
1525
1526
 
# File 'lib/twitter/api.rb', line 1520

def retweeted_by_me(options={})
  options[:include_rts] = true
  count = options[:count] || DEFAULT_TWEETS_PER_REQUEST
  collect_with_count(count) do |count_options|
    select_retweets(user_timeline(options.merge(count_options)))
  end
end

#retweeted_by_user(user, options = {}) ⇒ Array<Twitter::Tweet> Also known as: retweeted_by

Note:

This method can only return up to 3,200 Tweets.

Returns the 20 most recent retweets posted by the specified user

Examples:

Return the 20 most recent retweets posted by @sferik

Twitter.retweeted_by_user('sferik')

Parameters:

  • user (Integer, String, Twitter::User) —

    A Twitter user ID, screen name, or object.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :since_id (Integer) —

    Returns results with an ID greater than (that is, more recent than) the specified ID.

  • :max_id (Integer) —

    Returns results with an ID less than (that is, older than) or equal to the specified ID.

  • :count (Integer) —

    Specifies the number of records to retrieve. Must be less than or equal to 200.

  • :trim_user (Boolean, String, Integer) —

    Each tweet returned in a timeline will include a user object with only the author’s numerical ID when set to true, ‘t’ or 1.

  • :exclude_replies (Boolean, String, Integer) —

    This parameter will prevent replies from appearing in the returned timeline. Using exclude_replies with the count parameter will mean you will receive up-to count tweets - this is because the count parameter retrieves that many tweets before filtering out retweets and replies.

  • :contributor_details (Boolean, String, Integer) —

    Specifies that the contributors element should be enhanced to include the screen_name of the contributor.

Returns:

Raises:

See Also:



1493
1494
1495
1496
1497
1498
1499
 
# File 'lib/twitter/api.rb', line 1493

def retweeted_by_user(user, options={})
  options[:include_rts] = true
  count = options[:count] || DEFAULT_TWEETS_PER_REQUEST
  collect_with_count(count) do |count_options|
    select_retweets(user_timeline(user, options.merge(count_options)))
  end
end

#retweeted_to_me(options = {}) ⇒ Array<Twitter::Tweet>

Note:

This method can only return up to 800 Tweets, including retweets.

Returns the 20 most recent retweets posted by users the authenticating user follow.

Examples:

Return the 20 most recent retweets posted by users followed by the authenticating user

Twitter.retweeted_to_me

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :since_id (Integer) —

    Returns results with an ID greater than (that is, more recent than) the specified ID.

  • :max_id (Integer) —

    Returns results with an ID less than (that is, older than) or equal to the specified ID.

  • :count (Integer) —

    Specifies the number of records to retrieve. Must be less than or equal to 200.

  • :trim_user (Boolean, String, Integer) —

    Each tweet returned in a timeline will include a user object with only the author’s numerical ID when set to true, ‘t’ or 1.

  • :exclude_replies (Boolean, String, Integer) —

    This parameter will prevent replies from appearing in the returned timeline. Using exclude_replies with the count parameter will mean you will receive up-to count tweets - this is because the count parameter retrieves that many tweets before filtering out retweets and replies.

  • :contributor_details (Boolean, String, Integer) —

    Specifies that the contributors element should be enhanced to include the screen_name of the contributor.

  • :include_entities (Boolean, String, Integer) —

    Specifies that each tweet should include an ‘entities’ node including metadata about the tweet such as: user_mentions, urls, and hashtags.

Returns:

Raises:

See Also:



1546
1547
1548
1549
1550
1551
1552
 
# File 'lib/twitter/api.rb', line 1546

def retweeted_to_me(options={})
  options[:include_rts] = true
  count = options[:count] || DEFAULT_TWEETS_PER_REQUEST
  collect_with_count(count) do |count_options|
    select_retweets(home_timeline(options.merge(count_options)))
  end
end

#retweeters_of(id, options = {}) ⇒ Array

Show up to 100 users who retweeted the Tweet

Examples:

Show up to 100 users who retweeted the Tweet with the ID 28561922516

Twitter.retweeters_of(28561922516)

Parameters:

  • id (Integer) —

    The numerical ID of the desired Tweet.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :count (Integer) —

    Specifies the number of records to retrieve. Must be less than or equal to 100.

  • :trim_user (Boolean, String, Integer) —

    Each tweet returned in a timeline will include a user object with only the author’s numerical ID when set to true, ‘t’ or 1.

  • :ids_only (Boolean) — default: 'false' —

    Only return user ids instead of full user objects.

Returns:

Raises:

See Also:



1637
1638
1639
1640
1641
1642
1643
 
# File 'lib/twitter/api.rb', line 1637

def retweeters_of(id, options={})
  if ids_only = !!options.delete(:ids_only)
    retweets(id, options).map(&:user).map(&:id)
  else
    retweets(id, options).map(&:user)
  end
end

#retweets(id, options = {}) ⇒ Array<Twitter::Tweet>

Returns up to 100 of the first retweets of a given tweet

Examples:

Return up to 100 of the first retweets of the Tweet with the ID 28561922516

Twitter.retweets(28561922516)

Parameters:

  • id (Integer) —

    The numerical ID of the desired Tweet.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :count (Integer) —

    Specifies the number of records to retrieve. Must be less than or equal to 100.

  • :trim_user (Boolean, String, Integer) —

    Each tweet returned in a timeline will include a user object with only the author’s numerical ID when set to true, ‘t’ or 1.

Returns:

Raises:

See Also:



1658
1659
1660
 
# File 'lib/twitter/api.rb', line 1658

def retweets(id, options={})
  collection_from_response(Twitter::Tweet, :get, "/1.1/statuses/retweets/#{id}.json", options)
end

#retweets_of_me(options = {}) ⇒ Array<Twitter::Tweet>

Note:

This method can only return up to 3,200 Tweets.

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

Examples:

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

Twitter.retweets_of_me

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :since_id (Integer) —

    Returns results with an ID greater than (that is, more recent than) the specified ID.

  • :max_id (Integer) —

    Returns results with an ID less than (that is, older than) or equal to the specified ID.

  • :count (Integer) —

    Specifies the number of records to retrieve. Must be less than or equal to 200.

  • :trim_user (Boolean, String, Integer) —

    Each tweet returned in a timeline will include a user object with only the author’s numerical ID when set to true, ‘t’ or 1.

  • :exclude_replies (Boolean, String, Integer) —

    This parameter will prevent replies from appearing in the returned timeline. Using exclude_replies with the count parameter will mean you will receive up-to count tweets - this is because the count parameter retrieves that many tweets before filtering out retweets and replies.

  • :contributor_details (Boolean, String, Integer) —

    Specifies that the contributors element should be enhanced to include the screen_name of the contributor.

Returns:

Raises:

See Also:



1571
1572
1573
1574
1575
1576
1577
 
# File 'lib/twitter/api.rb', line 1571

def retweets_of_me(options={})
  options[:include_rts] = false
  count = options[:count] || DEFAULT_TWEETS_PER_REQUEST
  collect_with_count(count) do |count_options|
    user_timeline(options.merge(count_options)).select{|tweet| tweet.retweet_count.to_i > 0}
  end
end

#reverse_geocode(options = {}) ⇒ Array<Twitter::Place>

Note:

This request is an informative call and will deliver generalized results about geography.

Searches for up to 20 places that can be used as a place_id

Examples:

Return an array of places within the specified region

Twitter.reverse_geocode(:lat => "37.7821120598956", :long => "-122.400612831116")

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :lat (Float) —

    The latitude to search around. This option will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn’t a corresponding :long option.

  • :long (Float) —

    The longitude to search around. The valid range for longitude is -180.0 to +180.0 (East is positive) inclusive. This option will be ignored if outside that range, if it is not a number, if geo_enabled is disabled, or if there not a corresponding :lat option.

  • :accuracy (String) — default: '0m' —

    A hint on the “region” in which to search. If a number, then this is a radius in meters, but it can also take a string that is suffixed with ft to specify feet. If coming from a device, in practice, this value is whatever accuracy the device has measuring its location (whether it be coming from a GPS, WiFi triangulation, etc.).

  • :granularity (String) — default: 'neighborhood' —

    This is the minimal granularity of place types to return and must be one of: ‘poi’, ‘neighborhood’, ‘city’, ‘admin’ or ‘country’.

  • :max_results (Integer) —

    A hint as to the number of results to return. This does not guarantee that the number of results returned will equal max_results, but instead informs how many “nearby” results to return. Ideally, only pass in the number of places you intend to display to the user here.

Returns:

Raises:

See Also:



630
631
632
 
# File 'lib/twitter/api.rb', line 630

def reverse_geocode(options={})
  geo_collection_from_response(:get, "/1.1/geo/reverse_geocode.json", options)
end

#saved_search(id, options = {}) ⇒ Twitter::SavedSearch

Retrieve the data for saved searches owned by the authenticating user

Examples:

Retrieve the data for a saved search owned by the authenticating user with the ID 16129012

Twitter.saved_search(16129012)

Parameters:

  • id (Integer) —

    A Tweet IDs.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Returns:

Raises:

See Also:



1271
1272
1273
 
# File 'lib/twitter/api.rb', line 1271

def saved_search(id, options={})
  object_from_response(Twitter::SavedSearch, :get, "/1.1/saved_searches/show/#{id}.json", options)
end

#saved_search_create(query, options = {}) ⇒ Twitter::SavedSearch

Creates a saved search for the authenticated user

Examples:

Create a saved search for the authenticated user with the query “twitter”

Twitter.saved_search_create("twitter")

Parameters:

  • query (String) —

    The query of the search the user would like to save.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Returns:

Raises:

See Also:



1286
1287
1288
 
# File 'lib/twitter/api.rb', line 1286

def saved_search_create(query, options={})
  object_from_response(Twitter::SavedSearch, :post, "/1.1/saved_searches/create.json", options.merge(:query => query))
end

#saved_search_destroy(*ids) ⇒ Array<Twitter::SavedSearch> #saved_search_destroy(*ids, options) ⇒ Array<Twitter::SavedSearch>

Note:

The search specified by ID must be owned by the authenticating user.

Destroys saved searches for the authenticated user

Overloads:

  • #saved_search_destroy(*ids) ⇒ Array<Twitter::SavedSearch>

    Examples:

    Destroys a saved search for the authenticated user with the ID 16129012

    Twitter.saved_search_destroy(16129012)

    Parameters:

    • ids (Array<Integer>, Set<Integer>) —

      An array of Tweet IDs.

  • #saved_search_destroy(*ids, options) ⇒ Array<Twitter::SavedSearch>

    Parameters:

    • ids (Array<Integer>, Set<Integer>) —

      An array of Tweet IDs.

    • options (Hash) —

      A customizable set of options.

Returns:

Raises:

See Also:



1305
1306
1307
1308
1309
1310
 
# File 'lib/twitter/api.rb', line 1305

def saved_search_destroy(*args)
  options = args.extract_options!
  args.flatten.threaded_map do |id|
    object_from_response(Twitter::SavedSearch, :post, "/1.1/saved_searches/destroy/#{id}.json", options)
  end
end

#saved_search(options = {}) ⇒ Array<Twitter::SavedSearch> #saved_search(*ids) ⇒ Array<Twitter::SavedSearch> #saved_search(*ids, options) ⇒ Array<Twitter::SavedSearch>

Returns The saved searches.

Overloads:

Returns:

Raises:



1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
 
# File 'lib/twitter/api.rb', line 1249

def saved_searches(*args)
  options = args.extract_options!
  if args.empty?
    collection_from_response(Twitter::SavedSearch, :get, "/1.1/saved_searches/list.json", options)
  else
    args.flatten.threaded_map do |id|
      object_from_response(Twitter::SavedSearch, :get, "/1.1/saved_searches/show/#{id}.json", options)
    end
  end
end

#search(q, options = {}) ⇒ Twitter::SearchResults

Note:

As of April 1st 2010, the Search API provides an option to retrieve “popular tweets” in addition to real-time search results. In an upcoming release, this will become the default and clients that don’t want to receive popular tweets in their search results will have to explicitly opt-out. See the result_type parameter below for more information.

Returns tweets that match a specified query.

Examples:

Returns tweets related to twitter

Twitter.search('twitter')

Parameters:

  • q (String) —

    A search term.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :geocode (String) —

    Returns tweets by users located within a given radius of the given latitude/longitude. The location is preferentially taking from the Geotagging API, but will fall back to their Twitter profile. The parameter value is specified by “latitude,longitude,radius”, where radius units must be specified as either “mi” (miles) or “km” (kilometers). Note that you cannot use the near operator via the API to geocode arbitrary locations; however you can use this geocode parameter to search near geocodes directly.

  • :lang (String) —

    Restricts tweets to the given language, given by an ISO 639-1 code.

  • :locale (String) —

    Specify the language of the query you are sending (only ja is currently effective). This is intended for language-specific clients and the default should work in the majority of cases.

  • :page (Integer) —

    The page number (starting at 1) to return, up to a max of roughly 1500 results (based on rpp * page).

  • :result_type (String) —

    Specifies what type of search results you would prefer to receive. Options are “mixed”, “recent”, and “popular”. The current default is “mixed.”

  • :rpp (Integer) —

    The number of tweets to return per page, up to a max of 100.

  • :until (String) —

    Optional. Returns tweets generated before the given date. Date should be formatted as YYYY-MM-DD.

  • :since_id (Integer) —

    Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occured since the since_id, the since_id will be forced to the oldest ID available.

  • :max_id (Integer) —

    Returns results with an ID less than (that is, older than) or equal to the specified ID.

  • :with_twitter_user_id (Boolean, String, Integer) —

    When set to either true, t or 1, the from_user_id and to_user_id values in the response will map to “official” user IDs which will match those returned by the REST API.

Returns:

Raises:

See Also:



1336
1337
1338
 
# File 'lib/twitter/api.rb', line 1336

def search(q, options={})
  object_from_response(Twitter::SearchResults, :get, "/1.1/search/tweets.json", options.merge(:q => q))
end

#settings(options = {}) ⇒ Twitter::Settings

Updates the authenticating user’s settings. Or, if no options supplied, returns settings (including current trend, geo and sleep time information) for the authenticating user.

Examples:

Return the settings for the authenticating user.

Twitter.settings

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :trend_location_woeid (Integer) —

    The Yahoo! Where On Earth ID to use as the user’s default trend location. Global information is available by using 1 as the WOEID. The woeid must be one of the locations returned by GET trends/available.

  • :sleep_time_enabled (Boolean, String, Integer) —

    When set to true, ‘t’ or 1, will enable sleep time for the user. Sleep time is the time when push or SMS notifications should not be sent to the user.

  • :start_sleep_time (Integer) —

    The hour that sleep time should begin if it is enabled. The value for this parameter should be provided in ISO8601 format (i.e. 00-23). The time is considered to be in the same timezone as the user’s time_zone setting.

  • :end_sleep_time (Integer) —

    The hour that sleep time should end if it is enabled. The value for this parameter should be provided in ISO8601 format (i.e. 00-23). The time is considered to be in the same timezone as the user’s time_zone setting.

  • :time_zone (String) —

    The timezone dates and times should be displayed in for the user. The timezone must be one of the Rails TimeZone names.

  • :lang (String) —

    The language which Twitter should render in for this user. The language must be specified by the appropriate two letter ISO 639-1 representation. Currently supported languages are provided by GET help/languages.

Returns:

Raises:

See Also:



150
151
152
153
 
# File 'lib/twitter/api.rb', line 150

def settings(options={})
  request_method = options.size.zero? ? :get : :post
  object_from_response(Twitter::Settings, request_method, "/1.1/account/settings.json", options)
end

#status(id, options = {}) ⇒ Twitter::Tweet

Returns a Tweet

Examples:

Return the Tweet with the ID 25938088801

Twitter.status(25938088801)

Parameters:

  • id (Integer) —

    A Tweet ID.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :trim_user (Boolean, String, Integer) —

    Each tweet returned in a timeline will include a user object with only the author’s numerical ID when set to true, ‘t’ or 1.

Returns:

Raises:

See Also:



1674
1675
1676
 
# File 'lib/twitter/api.rb', line 1674

def status(id, options={})
  object_from_response(Twitter::Tweet, :get, "/1.1/statuses/show/#{id}.json", options)
end

#status_activity(id, options = {}) ⇒ Twitter::Tweet Also known as: tweet_activity

Note:

Undocumented

Returns activity summary for a Tweet

Examples:

Return activity summary for the Tweet with the ID 25938088801

Twitter.status_activity(25938088801)

Parameters:

  • id (Integer) —

    A Tweet ID.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Returns:

Raises:



1708
1709
1710
1711
1712
 
# File 'lib/twitter/api.rb', line 1708

def status_activity(id, options={})
  response = get("/i/statuses/#{id}/activity/summary.json", options)
  response[:body].merge!(:id => id) if response[:body]
  Twitter::Tweet.from_response(response)
end

#status_destroy(*ids) ⇒ Array<Twitter::Tweet> #status_destroy(*ids, options) ⇒ Array<Twitter::Tweet> Also known as: tweet_destroy

Note:

The authenticating user must be the author of the specified Tweets.

Destroys the specified Tweets

Overloads:

  • #status_destroy(*ids) ⇒ Array<Twitter::Tweet>

    Examples:

    Destroy the Tweet with the ID 25938088801

    Twitter.status_destroy(25938088801)

    Parameters:

    • ids (Array<Integer>, Set<Integer>) —

      An array of Tweet IDs.

  • #status_destroy(*ids, options) ⇒ Array<Twitter::Tweet>

    Parameters:

    • ids (Array<Integer>, Set<Integer>) —

      An array of Tweet IDs.

    • options (Hash) —

      A customizable set of options.

    Options Hash (options):

    • :trim_user (Boolean, String, Integer) —

      Each tweet returned in a timeline will include a user object with only the author’s numerical ID when set to true, ‘t’ or 1.

Returns:

Raises:

See Also:



1802
1803
1804
 
# File 'lib/twitter/api.rb', line 1802

def status_destroy(*args)
  threaded_tweets_from_response(:post, "/1.1/statuses/destroy", args)
end

#statuses(*ids) ⇒ Array<Twitter::Tweet> #statuses(*ids, options) ⇒ Array<Twitter::Tweet>

Returns Tweets

Overloads:

  • #statuses(*ids) ⇒ Array<Twitter::Tweet>

    Examples:

    Return the Tweet with the ID 25938088801

    Twitter.statuses(25938088801)

    Parameters:

    • ids (Array<Integer>, Set<Integer>) —

      An array of Tweet IDs.

  • #statuses(*ids, options) ⇒ Array<Twitter::Tweet>

    Parameters:

    • ids (Array<Integer>, Set<Integer>) —

      An array of Tweet IDs.

    • options (Hash) —

      A customizable set of options.

    Options Hash (options):

    • :trim_user (Boolean, String, Integer) —

      Each tweet returned in a timeline will include a user object with only the author’s numerical ID when set to true, ‘t’ or 1.

Returns:

Raises:

See Also:



1693
1694
1695
 
# File 'lib/twitter/api.rb', line 1693

def statuses(*args)
  threaded_tweets_from_response(:get, "/1.1/statuses/show", args)
end

#statuses_activity(*ids) ⇒ Array<Twitter::Tweet> #statuses_activity(*ids, options) ⇒ Array<Twitter::Tweet>

Note:

Undocumented

Returns activity summary for Tweets

Overloads:

  • #statuses_activity(*ids) ⇒ Array<Twitter::Tweet>

    Examples:

    Return activity summary for the Tweet with the ID 25938088801

    Twitter.statuses_activity(25938088801)

    Parameters:

    • ids (Array<Integer>, Set<Integer>) —

      An array of Tweet IDs.

  • #statuses_activity(*ids, options) ⇒ Array<Twitter::Tweet>

    Parameters:

    • ids (Array<Integer>, Set<Integer>) —

      An array of Tweet IDs.

    • options (Hash) —

      A customizable set of options.

Returns:

Raises:



1729
1730
1731
1732
1733
1734
 
# File 'lib/twitter/api.rb', line 1729

def statuses_activity(*args)
  options = args.extract_options!
  args.flatten.threaded_map do |id|
    status_activity(id, options)
  end
end

#subscriptions(options = {}) ⇒ Twitter::Cursor #subscriptions(user, options = {}) ⇒ Twitter::Cursor

List the lists the specified user follows

Overloads:

  • #subscriptions(options = {}) ⇒ Twitter::Cursor

    Examples:

    List the lists the authenticated user follows

    Twitter.subscriptions

    Parameters:

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :cursor (Integer) — default: -1 —

      Breaks the results into pages. Provide values as returned in the response objects’s next_cursor and previous_cursor attributes to page back and forth in the list.

  • #subscriptions(user, options = {}) ⇒ Twitter::Cursor

    Examples:

    List the lists that @sferik follows

    Twitter.subscriptions('sferik')
Twitter.subscriptions(7505382)

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :cursor (Integer) — default: -1 —

      Breaks the results into pages. Provide values as returned in the response objects’s next_cursor and previous_cursor attributes to page back and forth in the list.

Returns:

Raises:

See Also:



854
855
856
 
# File 'lib/twitter/api.rb', line 854

def subscriptions(*args)
  lists_from_response(:get, "/1.1/lists/subscriptions.json", args)
end

#suggest_users(slug, options = {}) ⇒ Array<Twitter::User>

Access the users in a given category of the Twitter suggested user list and return their most recent Tweet if they are not a protected user

Examples:

Return the users in the Art & Design category and their most recent Tweet if they are not a protected user

Twitter.suggest_users("art-design")

Parameters:

  • slug (String) —

    The short name of list or a category.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Returns:

See Also:



2061
2062
2063
 
# File 'lib/twitter/api.rb', line 2061

def suggest_users(slug, options={})
  collection_from_response(Twitter::User, :get, "/1.1/users/suggestions/#{slug}/members.json", options)
end

#suggestions(options = {}) ⇒ Array<Twitter::Suggestion> #suggestions(slug, options = {}) ⇒ Array<Twitter::Suggestion>

Overloads:

Returns:

Raises:



2042
2043
2044
2045
2046
2047
2048
2049
 
# File 'lib/twitter/api.rb', line 2042

def suggestions(*args)
  options = args.extract_options!
  if slug = args.pop
    object_from_response(Twitter::Suggestion, :get, "/1.1/users/suggestions/#{slug}.json", options)
  else
    collection_from_response(Twitter::Suggestion, :get, "/1.1/users/suggestions.json", options)
  end
end

#tos(options = {}) ⇒ String

Returns Twitter’s Terms of Service

Examples:

Return Twitter’s Terms of Service

Twitter.tos

Returns:

Raises:

See Also:



717
718
719
 
# File 'lib/twitter/api.rb', line 717

def tos(options={})
  get("/1.1/help/tos.json", options)[:body][:tos]
end

#trends(id = 1, options = {}) ⇒ Array<Twitter::Trend> Also known as: local_trends, trends_place

Returns the top 10 trending topics for a specific WOEID

Examples:

Return the top 10 trending topics for San Francisco

Twitter.trends(2487956)

Parameters:

  • id (Integer) (defaults to: 1) —

    The Yahoo! Where On Earth ID of the location to return trending information for. WOEIDs can be retrieved by calling Twitter::API::Trends#trend_locations. Global information is available by using 1 as the WOEID.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :exclude (String) —

    Setting this equal to ‘hashtags’ will remove all hashtags from the trends list.

Returns:

Raises:

See Also:



1890
1891
1892
1893
1894
 
# File 'lib/twitter/api.rb', line 1890

def trends(id=1, options={})
  options[:id] = id
  response = get("/1.1/trends/place.json", options)
  collection_from_array(Twitter::Trend, response[:body].first[:trends])
end

#trends_available(options = {}) ⇒ Array<Twitter::Place> Also known as: trend_locations

Returns the locations that Twitter has trending topic information for

Examples:

Return the locations that Twitter has trending topic information for

Twitter.trends_available

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Returns:

Raises:

See Also:



1908
1909
1910
 
# File 'lib/twitter/api.rb', line 1908

def trends_available(options={})
  collection_from_response(Twitter::Place, :get, "/1.1/trends/available.json", options)
end

#trends_closest(options = {}) ⇒ Array<Twitter::Place>

Returns the locations that Twitter has trending topic information for, closest to a specified location.

Examples:

Return the locations that Twitter has trending topic information for

Twitter.trends_closest

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :lat (Float) —

    If provided with a :long option the available trend locations will be sorted by distance, nearest to furthest, to the co-ordinate pair. The valid ranges for latitude are -90.0 to +90.0 (North is positive) inclusive.

  • :long (Float) —

    If provided with a :lat option the available trend locations will be sorted by distance, nearest to furthest, to the co-ordinate pair. The valid ranges for longitude are -180.0 to +180.0 (East is positive) inclusive.

Returns:

Raises:

See Also:



1925
1926
1927
 
# File 'lib/twitter/api.rb', line 1925

def trends_closest(options={})
  collection_from_response(Twitter::Place, :get, "/1.1/trends/closest.json", options)
end

#unblock(*users) ⇒ Array<Twitter::User> #unblock(*users, options) ⇒ Array<Twitter::User>

Un-blocks the users specified by the authenticating user

Overloads:

Returns:

Raises:

See Also:



2019
2020
2021
 
# File 'lib/twitter/api.rb', line 2019

def unblock(*args)
  threaded_users_from_response(:post, "/1.1/blocks/destroy.json", args)
end

#unfavorite(*ids) ⇒ Array<Twitter::Tweet> #unfavorite(*ids, options) ⇒ Array<Twitter::Tweet> Also known as: favorite_destroy

Un-favorites the specified Tweets as the authenticating user

Overloads:

  • #unfavorite(*ids) ⇒ Array<Twitter::Tweet>

    Examples:

    Un-favorite the tweet with the ID 25938088801

    Twitter.unfavorite(25938088801)

    Parameters:

    • ids (Array<Integer>, Set<Integer>) —

      An array of Tweet IDs.

  • #unfavorite(*ids, options) ⇒ Array<Twitter::Tweet>

    Parameters:

    • ids (Array<Integer>, Set<Integer>) —

      An array of Tweet IDs.

    • options (Hash) —

      A customizable set of options.

Returns:

Raises:

See Also:



1424
1425
1426
1427
1428
1429
 
# File 'lib/twitter/api.rb', line 1424

def unfavorite(*args)
  options = args.extract_options!
  args.flatten.threaded_map do |id|
    object_from_response(Twitter::Tweet, :post, "/1.1/favorites/destroy.json", options.merge(:id => id))
  end
end

#unfollow(*users) ⇒ Array<Twitter::User> #unfollow(*users) ⇒ Array<Twitter::User> Also known as: friendship_destroy

Allows the authenticating user to unfollow the specified users

Overloads:

Returns:

Raises:

See Also:



525
526
527
 
# File 'lib/twitter/api.rb', line 525

def unfollow(*args)
  threaded_users_from_response(:post, "/1.1/friendships/destroy.json", args)
end

#update(status, options = {}) ⇒ Twitter::Tweet

Note:

A status update with text identical to the authenticating user’s current status will be ignored to prevent duplicates.

Updates the authenticating user’s status

Examples:

Update the authenticating user’s status

Twitter.update("I'm tweeting with @gem!")

Parameters:

  • status (String) —

    The text of your status update, up to 140 characters.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :in_reply_to_status_id (Integer) —

    The ID of an existing status that the update is in reply to.

  • :lat (Float) —

    The latitude of the location this tweet refers to. This option will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn’t a corresponding :long option.

  • :long (Float) —

    The longitude of the location this tweet refers to. The valid ranges for longitude is -180.0 to +180.0 (East is positive) inclusive. This option will be ignored if outside that range, if it is not a number, if geo_enabled is disabled, or if there not a corresponding :lat option.

  • :place_id (String) —

    A place in the world. These IDs can be retrieved from Twitter::API::Geo#reverse_geocode.

  • :display_coordinates (String) —

    Whether or not to put a pin on the exact coordinates a tweet has been sent from.

  • :trim_user (Boolean, String, Integer) —

    Each tweet returned in a timeline will include a user object with only the author’s numerical ID when set to true, ‘t’ or 1.

Returns:

Raises:

See Also:



1851
1852
1853
 
# File 'lib/twitter/api.rb', line 1851

def update(status, options={})
  object_from_response(Twitter::Tweet, :post, "/1.1/statuses/update.json", options.merge(:status => status))
end

#update_delivery_device(device, options = {}) ⇒ Twitter::User

Sets which device Twitter delivers updates to for the authenticating user

Examples:

Turn SMS updates on for the authenticating user

Twitter.update_delivery_device('sms')

Parameters:

  • device (String) —

    Must be one of: ‘sms’, ‘none’.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Returns:

Raises:

See Also:



58
59
60
 
# File 'lib/twitter/api.rb', line 58

def update_delivery_device(device, options={})
  object_from_response(Twitter::User, :post, "/1.1/account/update_delivery_device.json", options.merge(:device => device))
end

#update_profile(options = {}) ⇒ Twitter::User

Note:

Only the options specified will be updated.

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

Examples:

Set authenticating user’s name to Erik Michaels-Ober

Twitter.update_profile(:name => "Erik Michaels-Ober")

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :name (String) —

    Full name associated with the profile. Maximum of 20 characters.

  • :url (String) —

    URL associated with the profile. Will be prepended with “http://” if not present. Maximum of 100 characters.

  • :location (String) —

    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 (String) —

    A description of the user owning the account. Maximum of 160 characters.

Returns:

Raises:

See Also:



77
78
79
 
# File 'lib/twitter/api.rb', line 77

def update_profile(options={})
  object_from_response(Twitter::User, :post, "/1.1/account/update_profile.json", options)
end

#update_profile_background_image(image, options = {}) ⇒ Twitter::User

Updates the authenticating user’s profile background image

Examples:

Update the authenticating user’s profile background image

Twitter.update_profile_background_image(File.new("we_concept_bg2.png"))

Parameters:

  • image (File, Hash) —

    The background image for the profile. Must be a valid GIF, JPG, or PNG image of less than 800 kilobytes in size. Images with width larger than 2048 pixels will be scaled down.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :tile (Boolean) —

    Whether or not to tile the background image. If set to true the background image will be displayed tiled. The image will not be tiled otherwise.

Returns:

Raises:

See Also:



93
94
95
 
# File 'lib/twitter/api.rb', line 93

def update_profile_background_image(image, options={})
  object_from_response(Twitter::User, :post, "/1.1/account/update_profile_background_image.json", options.merge(:image => image))
end

#update_profile_colors(options = {}) ⇒ Twitter::User

Sets one or more hex values that control the color scheme of the authenticating user’s profile

Examples:

Set authenticating user’s profile background to black

Twitter.update_profile_colors(:profile_background_color => '000000')

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :profile_background_color (String) —

    Profile background color.

  • :profile_text_color (String) —

    Profile text color.

  • :profile_link_color (String) —

    Profile link color.

  • :profile_sidebar_fill_color (String) —

    Profile sidebar’s background color.

  • :profile_sidebar_border_color (String) —

    Profile sidebar’s border color.

Returns:

Raises:

See Also:



112
113
114
 
# File 'lib/twitter/api.rb', line 112

def update_profile_colors(options={})
  object_from_response(Twitter::User, :post, "/1.1/account/update_profile_colors.json", options)
end

#update_profile_image(image, options = {}) ⇒ Twitter::User

Note:

This method asynchronously processes the uploaded file before updating the user’s profile image URL. You can either update your local cache the next time you request the user’s information, or, at least 5 seconds after uploading the image, ask for the updated URL using User#profile_image_url.

Updates the authenticating user’s profile image

Examples:

Update the authenticating user’s profile image

Twitter.update_profile_image(File.new("me.jpeg"))

Parameters:

  • image (File, Hash) —

    The avatar image for the profile. Must be a valid GIF, JPG, or PNG image of less than 700 kilobytes in size. Images with width larger than 500 pixels will be scaled down. Animated GIFs will be converted to a static GIF of the first frame, removing the animation.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Returns:

Raises:

See Also:



128
129
130
 
# File 'lib/twitter/api.rb', line 128

def update_profile_image(image, options={})
  object_from_response(Twitter::User, :post, "/1.1/account/update_profile_image.json", options.merge(:image => image))
end

#update_with_media(status, media, options = {}) ⇒ Twitter::Tweet

Note:

A status update with text/media identical to the authenticating user’s current status will NOT be ignored

Updates the authenticating user’s status with media

Examples:

Update the authenticating user’s status

Twitter.update_with_media("I'm tweeting with @gem!", File.new('my_awesome_pic.jpeg'))

Parameters:

  • status (String) —

    The text of your status update, up to 140 characters.

  • media (File, Hash) —

    A File object with your picture (PNG, JPEG or GIF)

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :in_reply_to_status_id (Integer) —

    The ID of an existing Tweet that the update is in reply to.

  • :lat (Float) —

    The latitude of the location this tweet refers to. This option will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn’t a corresponding :long option.

  • :long (Float) —

    The longitude of the location this tweet refers to. The valid ranges for longitude is -180.0 to +180.0 (East is positive) inclusive. This option will be ignored if outside that range, if it is not a number, if geo_enabled is disabled, or if there not a corresponding :lat option.

  • :place_id (String) —

    A place in the world. These IDs can be retrieved from Twitter::API::Geo#reverse_geocode.

  • :display_coordinates (String) —

    Whether or not to put a pin on the exact coordinates a tweet has been sent from.

  • :trim_user (Boolean, String, Integer) —

    Each tweet returned in a timeline will include a user object with only the author’s numerical ID when set to true, ‘t’ or 1.

Returns:

Raises:

See Also:



1874
1875
1876
 
# File 'lib/twitter/api.rb', line 1874

def update_with_media(status, media, options={})
  object_from_response(Twitter::Tweet, :post, "/1.1/statuses/update_with_media.json", options.merge('media[]' => media, 'status' => status))
end

#user(options = {}) ⇒ Twitter::User #user(user, options = {}) ⇒ Twitter::User

Returns The requested user.

Overloads:

  • #user(options = {}) ⇒ Twitter::User

    Returns extended information for the authenticated user

    Examples:

    Return extended information for the authenticated user

    Twitter.user

    Parameters:

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :skip_status (Boolean, String, Integer) —

      Do not include user’s Tweets when set to true, ‘t’ or 1.

  • #user(user, options = {}) ⇒ Twitter::User

    Returns extended information for a given user

    Examples:

    Return extended information for @sferik

    Twitter.user('sferik')
Twitter.user(7505382)  # Same as above

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, or object.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

Returns:

Raises:

See Also:



2124
2125
2126
2127
2128
2129
2130
2131
2132
 
# File 'lib/twitter/api.rb', line 2124

def user(*args)
  options = args.extract_options!
  if user = args.pop
    options.merge_user!(user)
    object_from_response(Twitter::User, :get, "/1.1/users/show.json", options)
  else
    verify_credentials(options)
  end
end

#user?(user, options = {}) ⇒ Boolean

Returns true if the specified user exists

Examples:

Return true if @sferik exists

Twitter.user?('sferik')
Twitter.user?(7505382)  # Same as above

Parameters:

Returns:

  • (Boolean) —

    true if the user exists, otherwise false.

Raises:



2144
2145
2146
2147
2148
2149
2150
 
# File 'lib/twitter/api.rb', line 2144

def user?(user, options={})
  options.merge_user!(user)
  get("/1.1/users/show.json", options)
  true
rescue Twitter::Error::NotFound
  false
end

#user_search(query, options = {}) ⇒ Array<Twitter::User>

Returns users that match the given query

Examples:

Return users that match “Erik Michaels-Ober”

Twitter.user_search("Erik Michaels-Ober")

Parameters:

  • query (String) —

    The search query to run against people search.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :count (Integer) —

    The number of people to retrieve. Maxiumum of 20 allowed per page.

  • :page (Integer) —

    Specifies the page of results to retrieve.

Returns:

Raises:

See Also:



2100
2101
2102
 
# File 'lib/twitter/api.rb', line 2100

def user_search(query, options={})
  collection_from_response(Twitter::User, :get, "/1.1/users/search.json", options.merge(:q => query))
end

#user_timeline(user, options = {}) ⇒ Array<Twitter::Tweet>

Note:

This method can only return up to 3,200 Tweets.

Returns the 20 most recent Tweets posted by the specified user

Examples:

Return the 20 most recent Tweets posted by @sferik

Twitter.user_timeline('sferik')

Parameters:

  • user (Integer, String, Twitter::User) —

    A Twitter user ID, screen name, or object.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :since_id (Integer) —

    Returns results with an ID greater than (that is, more recent than) the specified ID.

  • :max_id (Integer) —

    Returns results with an ID less than (that is, older than) or equal to the specified ID.

  • :count (Integer) —

    Specifies the number of records to retrieve. Must be less than or equal to 200.

  • :trim_user (Boolean, String, Integer) —

    Each tweet returned in a timeline will include a user object with only the author’s numerical ID when set to true, ‘t’ or 1.

  • :exclude_replies (Boolean, String, Integer) —

    This parameter will prevent replies from appearing in the returned timeline. Using exclude_replies with the count parameter will mean you will receive up-to count tweets - this is because the count parameter retrieves that many tweets before filtering out retweets and replies.

  • :contributor_details (Boolean, String, Integer) —

    Specifies that the contributors element should be enhanced to include the screen_name of the contributor.

  • :include_rts (Boolean, String, Integer) —

    Specifies that the timeline should include native retweets in addition to regular tweets. Note: If you’re using the trim_user parameter in conjunction with include_rts, the retweets will no longer contain a full user object.

Returns:

Raises:

See Also:



1599
1600
1601
 
# File 'lib/twitter/api.rb', line 1599

def user_timeline(*args)
  objects_from_response(Twitter::Tweet, :get, "/1.1/statuses/user_timeline.json", args)
end

#users(*users) ⇒ Array<Twitter::User> #users(*users, options) ⇒ Array<Twitter::User>

Returns extended information for up to 100 users

Overloads:

Returns:

Raises:

See Also:



2080
2081
2082
2083
2084
2085
 
# File 'lib/twitter/api.rb', line 2080

def users(*args)
  options = args.extract_options!
  args.flatten.each_slice(MAX_USERS_PER_REQUEST).threaded_map do |users|
    collection_from_response(Twitter::User, :post, "/1.1/users/lookup.json", options.merge_users(users))
  end.flatten
end

#verify_credentials(options = {}) ⇒ Twitter::User Also known as: current_user

Returns the requesting user if authentication was successful, otherwise raises Error::Unauthorized

Examples:

Return the requesting user if authentication was successful

Twitter.verify_credentials

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :skip_status (Boolean, String, Integer) —

    Do not include user’s Tweets when set to true, ‘t’ or 1.

Returns:

Raises:

See Also:



42
43
44
 
# File 'lib/twitter/api.rb', line 42

def verify_credentials(options={})
  object_from_response(Twitter::User, :get, "/1.1/account/verify_credentials.json", options)
end