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:



207
208
209
 
# File 'lib/twitter/api.rb', line 207

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:



223
224
225
 
# File 'lib/twitter/api.rb', line 223

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:



2116
2117
2118
 
# File 'lib/twitter/api.rb', line 2116

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:



2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
 
# File 'lib/twitter/api.rb', line 2087

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:



2071
2072
2073
 
# File 'lib/twitter/api.rb', line 2071

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:



2056
2057
2058
2059
 
# File 'lib/twitter/api.rb', line 2056

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:



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

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:



2287
2288
2289
 
# File 'lib/twitter/api.rb', line 2287

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:



2310
2311
2312
 
# File 'lib/twitter/api.rb', line 2310

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:



320
321
322
323
 
# File 'lib/twitter/api.rb', line 320

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:



300
301
302
303
304
 
# File 'lib/twitter/api.rb', line 300

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:



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

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:

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

    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

    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.

    See Also:

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

    Returns direct messages

    Examples:

    Return the direct message with the id 1825786345

    Twitter.direct_messages(1825786345)

    Parameters:

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

      An array of Tweet IDs.

    See Also:

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

    Returns direct messages

    Parameters:

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

      An array of Tweet IDs.

    • options (Hash) —

      A customizable set of options.

    See Also:

Returns:

Raises:



354
355
356
357
358
359
360
361
362
363
 
# File 'lib/twitter/api.rb', line 354

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:



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

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:



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

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:



1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
 
# File 'lib/twitter/api.rb', line 1445

def favorite(*args)
  options = args.extract_options!
  args.flatten.threaded_map do |id|
    begin
      object_from_response(Twitter::Tweet, :post, "/1.1/favorites/create.json", options.merge(:id => id))
    rescue Twitter::Error::Forbidden => error
      raise unless error.message == Twitter::Error::AlreadyFavorited::MESSAGE
    end
  end.compact
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 and raises an error if one has already been favorited

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:



1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
 
# File 'lib/twitter/api.rb', line 1474

def favorite!(*args)
  options = args.extract_options!
  args.flatten.threaded_map do |id|
    begin
      object_from_response(Twitter::Tweet, :post, "/1.1/favorites/create.json", options.merge(:id => id))
    rescue Twitter::Error::Forbidden => error
      if error.message == "You have already favorited this status"
        raise Twitter::Error::AlreadyFavorited.new("Tweet with the ID #{id} has already been favorited by the authenticated user.")
      else
        raise
      end
    end
  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:



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

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:



504
505
506
507
508
509
510
511
512
513
514
515
516
 
# File 'lib/twitter/api.rb', line 504

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:



534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
 
# File 'lib/twitter/api.rb', line 534

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:



386
387
388
 
# File 'lib/twitter/api.rb', line 386

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:



2338
2339
2340
2341
2342
2343
 
# File 'lib/twitter/api.rb', line 2338

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:



411
412
413
 
# File 'lib/twitter/api.rb', line 411

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:



479
480
481
482
483
484
485
 
# File 'lib/twitter/api.rb', line 479

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:



429
430
431
 
# File 'lib/twitter/api.rb', line 429

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:



605
606
607
608
 
# File 'lib/twitter/api.rb', line 605

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:

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

    Examples:

    Return extended information for @sferik and @pengwynn

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

    Parameters:

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

    Parameters:

Returns:

Raises:

See Also:



586
587
588
589
590
 
# File 'lib/twitter/api.rb', line 586

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:



444
445
446
447
 
# File 'lib/twitter/api.rb', line 444

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:



460
461
462
463
 
# File 'lib/twitter/api.rb', line 460

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) —

    The tweet entities node will be disincluded when set to false.

Returns:

Raises:

See Also:



1533
1534
1535
 
# File 'lib/twitter/api.rb', line 1533

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:



731
732
733
 
# File 'lib/twitter/api.rb', line 731

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:



1249
1250
1251
 
# File 'lib/twitter/api.rb', line 1249

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:



1125
1126
1127
 
# File 'lib/twitter/api.rb', line 1125

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:



1009
1010
1011
 
# File 'lib/twitter/api.rb', line 1009

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:



1200
1201
1202
 
# File 'lib/twitter/api.rb', line 1200

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:



1152
1153
1154
 
# File 'lib/twitter/api.rb', line 1152

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:



1068
1069
1070
 
# File 'lib/twitter/api.rb', line 1068

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:



1096
1097
1098
 
# File 'lib/twitter/api.rb', line 1096

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:



821
822
823
 
# File 'lib/twitter/api.rb', line 821

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:



1041
1042
1043
 
# File 'lib/twitter/api.rb', line 1041

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:



921
922
923
 
# File 'lib/twitter/api.rb', line 921

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:



951
952
953
 
# File 'lib/twitter/api.rb', line 951

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:



873
874
875
 
# File 'lib/twitter/api.rb', line 873

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:



789
790
791
792
793
794
 
# File 'lib/twitter/api.rb', line 789

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:



976
977
978
 
# File 'lib/twitter/api.rb', line 976

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:



1182
1183
1184
 
# File 'lib/twitter/api.rb', line 1182

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

#memberships(options = {}) ⇒ Array<Twitter::List> #memberships(user, options = {}) ⇒ Array<Twitter::List> Also known as: lists_subscribed_to

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

Overloads:

  • #memberships(options = {}) ⇒ Array<Twitter::List>

    Examples:

    Returns all lists the authenticating user subscribes to

    Twitter.lists

    Parameters:

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

      A customizable set of options.

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

    Examples:

    Returns all lists that @sferik subscribes to

    Twitter.lists('sferik')
Twitter.lists(7505382)

    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:



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

def lists(*args)
  objects_from_response(Twitter::List, :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:



1696
1697
1698
 
# File 'lib/twitter/api.rb', line 1696

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.

    • :filter_to_owned_lists (Boolean, String, Integer) —

      When set to true, t or 1, will return just lists the authenticating user owns, and the user represented by user_id or screen_name is a member of.

  • #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.

    • :filter_to_owned_lists (Boolean, String, Integer) —

      When set to true, t or 1, will return just lists the authenticating user owns, and the user represented by user_id or screen_name is a member of.

Returns:

Raises:

See Also:



846
847
848
 
# File 'lib/twitter/api.rb', line 846

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:



1552
1553
1554
 
# File 'lib/twitter/api.rb', line 1552

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:



1831
1832
1833
 
# File 'lib/twitter/api.rb', line 1831

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:



1856
1857
1858
1859
1860
1861
 
# File 'lib/twitter/api.rb', line 1856

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:



1397
1398
1399
 
# File 'lib/twitter/api.rb', line 1397

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:



685
686
687
 
# File 'lib/twitter/api.rb', line 685

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:



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

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:



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

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:



650
651
652
 
# File 'lib/twitter/api.rb', line 650

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:



744
745
746
 
# File 'lib/twitter/api.rb', line 744

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

#remove_profile_banner(options = {}) ⇒ nil

Removes the authenticating user’s profile banner image

Examples:

Remove the authenticating user’s profile banner image

Twitter.remove_profile_banner

Parameters:

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

    A customizable set of options.

Returns:

  • (nil)

Raises:

See Also:



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

def remove_profile_banner(options={})
  post("/1.1/account/remove_profile_banner.json", options)[:body]
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:



1268
1269
1270
 
# File 'lib/twitter/api.rb', line 1268

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 the specified Tweets as the authenticating user

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:



1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
 
# File 'lib/twitter/api.rb', line 1899

def retweet(*args)
  options = args.extract_options!
  args.flatten.threaded_map do |id|
    begin
      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)
    rescue Twitter::Error::Forbidden => error
      raise unless error.message == Twitter::Error::AlreadyRetweeted::MESSAGE
    end
  end.compact
end

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

Retweets the specified Tweets as the authenticating user and raises an error if one has already been retweeted

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:



1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
 
# File 'lib/twitter/api.rb', line 1930

def retweet!(*args)
  options = args.extract_options!
  args.flatten.threaded_map do |id|
    begin
      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)
    rescue Twitter::Error::Forbidden => error
      if error.message == "sharing is not permissible for this status (Share validations failed)"
        raise Twitter::Error::AlreadyRetweeted.new("Tweet with the ID #{id} has already been retweeted by the authenticated user.")
      else
        raise
      end
    end
  end.compact
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:



1602
1603
1604
1605
1606
1607
1608
 
# File 'lib/twitter/api.rb', line 1602

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:



1575
1576
1577
1578
1579
1580
1581
 
# File 'lib/twitter/api.rb', line 1575

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) —

    The tweet entities node will be disincluded when set to false.

Returns:

Raises:

See Also:



1628
1629
1630
1631
1632
1633
1634
 
# File 'lib/twitter/api.rb', line 1628

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:



1714
1715
1716
1717
1718
1719
1720
 
# File 'lib/twitter/api.rb', line 1714

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:



1735
1736
1737
 
# File 'lib/twitter/api.rb', line 1735

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>

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):

  • :count (Integer) —

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

  • :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.

  • :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.

  • :include_entities (Boolean, String, Integer) —

    The tweet entities node will be disincluded when set to false.

  • :include_user_entities (Boolean, String, Integer) —

    The user entities node will be disincluded when set to false.

Returns:

Raises:

See Also:



1652
1653
1654
 
# File 'lib/twitter/api.rb', line 1652

def retweets_of_me(options={})
  collection_from_response(Twitter::Tweet, :get, "/1.1/statuses/retweets_of_me.json", options)
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:



670
671
672
 
# File 'lib/twitter/api.rb', line 670

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:



1318
1319
1320
 
# File 'lib/twitter/api.rb', line 1318

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:



1333
1334
1335
 
# File 'lib/twitter/api.rb', line 1333

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:



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

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:



1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
 
# File 'lib/twitter/api.rb', line 1296

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:

Please note that Twitter’s search service and, by extension, the Search API is not meant to be an exhaustive source of Tweets. Not all Tweets will be indexed or made available via the search interface.

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.

  • :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.”

  • :count (Integer) —

    The number of tweets to return per page, up to a maximum 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.

  • :include_entities (Boolean, String, Integer) —

    The tweet entities node will be disincluded when set to false.

Returns:

Raises:

See Also:



1381
1382
1383
 
# File 'lib/twitter/api.rb', line 1381

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:



190
191
192
193
 
# File 'lib/twitter/api.rb', line 190

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:



1751
1752
1753
 
# File 'lib/twitter/api.rb', line 1751

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:



1785
1786
1787
1788
1789
 
# File 'lib/twitter/api.rb', line 1785

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:



1879
1880
1881
 
# File 'lib/twitter/api.rb', line 1879

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:



1770
1771
1772
 
# File 'lib/twitter/api.rb', line 1770

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:



1806
1807
1808
1809
1810
1811
 
# File 'lib/twitter/api.rb', line 1806

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:



896
897
898
 
# File 'lib/twitter/api.rb', line 896

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:



2177
2178
2179
 
# File 'lib/twitter/api.rb', line 2177

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:



2158
2159
2160
2161
2162
2163
2164
2165
 
# File 'lib/twitter/api.rb', line 2158

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:



757
758
759
 
# File 'lib/twitter/api.rb', line 757

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:



2006
2007
2008
2009
2010
 
# File 'lib/twitter/api.rb', line 2006

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:



2024
2025
2026
 
# File 'lib/twitter/api.rb', line 2024

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:



2041
2042
2043
 
# File 'lib/twitter/api.rb', line 2041

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:



2135
2136
2137
 
# File 'lib/twitter/api.rb', line 2135

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:



1506
1507
1508
1509
1510
1511
 
# File 'lib/twitter/api.rb', line 1506

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:



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

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:



1967
1968
1969
 
# File 'lib/twitter/api.rb', line 1967

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:



60
61
62
 
# File 'lib/twitter/api.rb', line 60

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:



79
80
81
 
# File 'lib/twitter/api.rb', line 79

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) —

    The background image for the profile, base64-encoded. 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 forcibly scaled down. The image must be provided as raw multipart data, not a URL.

  • 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:



95
96
97
 
# File 'lib/twitter/api.rb', line 95

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_banner(banner, options = {}) ⇒ nil

Note:

Uploads a profile banner on behalf of the authenticating user. For best results, upload an <5MB image that is exactly 1252px by 626px. Images will be resized for a number of display options. Users with an uploaded profile banner will have a profile_banner_url node in their Users objects. More information about sizing variations can be found in User Profile Images and Banners.

Note:

Profile banner images are processed asynchronously. The profile_banner_url and its variant sizes will not necessary be available directly after upload.

Updates the authenticating user’s profile banner image

Examples:

Update the authenticating user’s profile banner

Twitter.update_profile_banner(File.new("me.jpeg"))

Parameters:

  • image (File) —

    The Base64-encoded or raw image data being uploaded as the user’s new profile banner.

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

    A customizable set of options.

Options Hash (options):

  • :width (Integer) —

    The width of the preferred section of the image being uploaded in pixels. Use with height, offset_left, and offset_top to select the desired region of the image to use.

  • :height (Integer) —

    The height of the preferred section of the image being uploaded in pixels. Use with width, offset_left, and offset_top to select the desired region of the image to use.

  • :offset_left (Integer) —

    The number of pixels by which to offset the uploaded image from the left. Use with height, width, and offset_top to select the desired region of the image to use.

  • :offset_top (Integer) —

    The number of pixels by which to offset the uploaded image from the top. Use with height, width, and offset_left to select the desired region of the image to use.

Returns:

  • (nil)

Raises:

See Also:



154
155
156
 
# File 'lib/twitter/api.rb', line 154

def update_profile_banner(banner, options={})
  post("/1.1/account/update_profile_banner.json", options.merge(:banner => banner))[:body]
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:



114
115
116
 
# File 'lib/twitter/api.rb', line 114

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:

Updates the authenticating user’s profile image. Note that this method expects raw multipart data, not a URL to an image.

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 GET users/show.

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) —

    The avatar image for the profile, base64-encoded. 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:



131
132
133
 
# File 'lib/twitter/api.rb', line 131

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:



1990
1991
1992
 
# File 'lib/twitter/api.rb', line 1990

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:



2240
2241
2242
2243
2244
2245
2246
2247
2248
 
# File 'lib/twitter/api.rb', line 2240

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:



2260
2261
2262
2263
2264
2265
2266
 
# File 'lib/twitter/api.rb', line 2260

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:



2216
2217
2218
 
# File 'lib/twitter/api.rb', line 2216

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:



1676
1677
1678
 
# File 'lib/twitter/api.rb', line 1676

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:



2196
2197
2198
2199
2200
2201
 
# File 'lib/twitter/api.rb', line 2196

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:



44
45
46
 
# File 'lib/twitter/api.rb', line 44

def verify_credentials(options={})
  object_from_response(Twitter::User, :get, "/1.1/account/verify_credentials.json", options)
end