Module: Twitter::REST::Lists

Includes:
Utils, Utils
Included in:
API
Defined in:
lib/twitter/rest/lists.rb

Constant Summary

MAX_USERS_PER_REQUEST =
100
URI_SUBSTRING =
'://'

Constants included from Utils

Utils::DEFAULT_CURSOR

Instance Method Summary (collapse)

Methods included from Utils

flat_pmap, pmap

Instance Method Details

- (Twitter::List) add_list_member(list, user_to_add, options = {}) - (Twitter::List) add_list_member(user, list, user_to_add, options = {})

Note:

Lists are limited to having 500 members.

Add a member to a list

Overloads:

  • - (Twitter::List) add_list_member(list, user_to_add, options = {})

    Parameters:

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

      A Twitter list ID, slug, URI, 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.

  • - (Twitter::List) add_list_member(user, list, user_to_add, options = {})

    Parameters:

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

      A Twitter user ID, screen name, URI, or object.

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

      A Twitter list ID, slug, URI, 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:

Rate Limited?:

  • No

Authentication:

  • Requires user context



258
259
260
# File 'lib/twitter/rest/lists.rb', line 258

def add_list_member(*args)
  list_from_response_with_user(:post, '/1.1/lists/members/create.json', args)
end

- (Twitter::List) add_list_members(list, users, options = {}) - (Twitter::List) add_list_members(user, list, users, options = {})

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:

  • - (Twitter::List) add_list_members(list, users, options = {})

    Parameters:

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

      A Twitter list ID, slug, URI, or object.

    • users (Enumerable<Integer, String, Twitter::User>)

      A collection of Twitter user IDs, screen names, or objects.

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

      A customizable set of options.

  • - (Twitter::List) add_list_members(user, list, users, options = {})

    Parameters:

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

      A Twitter user ID, screen name, URI, or object.

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

      A Twitter list ID, slug, URI, or object.

    • users (Enumerable<Integer, String, Twitter::User>)

      A collection of Twitter user IDs, screen names, or objects.

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

      A customizable set of options.

Returns:

Raises:

See Also:

Rate Limited?:

  • No

Authentication:

  • Requires user context



198
199
200
# File 'lib/twitter/rest/lists.rb', line 198

def add_list_members(*args)
  list_from_response_with_users(:post, '/1.1/lists/members/create_all.json', args)
end

- (Twitter::List) create_list(name, options = {})

Note:

Accounts are limited to 20 lists.

Creates a new list for the authenticated user

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:

Rate Limited?:

  • No

Authentication:

  • Requires user context



317
318
319
# File 'lib/twitter/rest/lists.rb', line 317

def create_list(name, options = {})
  perform_with_object(:post, '/1.1/lists/create.json', options.merge(:name => name), Twitter::List)
end

- (Twitter::List) destroy_list(list, options = {}) - (Twitter::List) destroy_list(user, list, options = {})

Note:

Must be owned by the authenticated user.

Deletes the specified list

Overloads:

  • - (Twitter::List) destroy_list(list, options = {})

    Parameters:

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

      A Twitter list ID, slug, URI, or object.

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

      A customizable set of options.

  • - (Twitter::List) destroy_list(user, list, options = {})

    Parameters:

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

      A Twitter user ID, screen name, URI, or object.

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

      A Twitter list ID, slug, URI, or object.

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

      A customizable set of options.

Returns:

Raises:

See Also:

Rate Limited?:

  • No

Authentication:

  • Requires user context



278
279
280
# File 'lib/twitter/rest/lists.rb', line 278

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

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

Note:

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

Show the specified list

Overloads:

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

    Parameters:

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

      A Twitter list ID, slug, URI, or object.

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

      A customizable set of options.

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

    Parameters:

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

      A Twitter user ID, screen name, URI, or object.

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

      A Twitter list ID, slug, URI, or object.

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

      A customizable set of options.

Returns:

Raises:

See Also:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



337
338
339
# File 'lib/twitter/rest/lists.rb', line 337

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

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

Check if a user is a member of the specified list

Overloads:

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

    Parameters:

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

      A Twitter list ID, slug, URI, 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.

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

    Parameters:

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

      A Twitter user ID, screen name, URI, or object.

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

      A Twitter list ID, slug, URI, 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:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



219
220
221
# File 'lib/twitter/rest/lists.rb', line 219

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

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

Returns the members of the specified list

Overloads:

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

    Parameters:

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

      A Twitter list ID, slug, URI, or object.

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

      A customizable set of options.

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

    Parameters:

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

      A Twitter user ID, screen name, URI, or object.

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

      A Twitter list ID, slug, URI, or object.

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

      A customizable set of options.

Returns:

Raises:

See Also:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



237
238
239
# File 'lib/twitter/rest/lists.rb', line 237

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

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

Make the authenticated user follow the specified list

Overloads:

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

    Parameters:

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

      A Twitter list ID, slug, URI, or object.

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

      A customizable set of options.

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

    Parameters:

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

      A Twitter user ID, screen name, URI, or object.

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

      A Twitter list ID, slug, URI, or object.

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

      A customizable set of options.

Returns:

Raises:

See Also:

Rate Limited?:

  • No

Authentication:

  • Requires user context



138
139
140
# File 'lib/twitter/rest/lists.rb', line 138

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

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

Check if a user is a subscriber of the specified list

Overloads:

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

    Parameters:

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

      A Twitter list ID, slug, URI, or object.

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

      A Twitter user ID, screen name, URI, or object.

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

      A customizable set of options.

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

    Parameters:

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

      A Twitter user ID, screen name, URI, or object.

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

      A Twitter list ID, slug, URI, or object.

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

      A Twitter user ID, screen name, URI, 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:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



159
160
161
# File 'lib/twitter/rest/lists.rb', line 159

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

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

Returns the subscribers of the specified list

Overloads:

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

    Parameters:

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

      A Twitter list ID, slug, URI, or object.

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

      A customizable set of options.

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

    Parameters:

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

      A Twitter user ID, screen name, URI, or object.

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

      A Twitter list ID, slug, URI, or object.

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

      A customizable set of options.

Returns:

Raises:

See Also:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



120
121
122
# File 'lib/twitter/rest/lists.rb', line 120

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

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

Show tweet timeline for members of the specified list

Overloads:

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

    Parameters:

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

      A Twitter list ID, slug, URI, 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.

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

    Parameters:

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

      A Twitter user ID, screen name, URI, or object.

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

      A Twitter list ID, slug, URI, 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:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



58
59
60
61
62
63
# File 'lib/twitter/rest/lists.rb', line 58

def list_timeline(*args)
  arguments = Twitter::Arguments.new(args)
  merge_list!(arguments.options, arguments.pop)
  merge_owner!(arguments.options, arguments.pop)
  perform_with_objects(:get, '/1.1/lists/statuses.json', arguments.options, Twitter::Tweet)
end

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

Unsubscribes the authenticated user form the specified list

Overloads:

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

    Parameters:

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

      A Twitter list ID, slug, URI, or object.

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

      A customizable set of options.

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

    Parameters:

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

      A Twitter user ID, screen name, URI, or object.

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

      A Twitter list ID, slug, URI, or object.

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

      A customizable set of options.

Returns:

Raises:

See Also:

Rate Limited?:

  • No

Authentication:

  • Requires user context



177
178
179
# File 'lib/twitter/rest/lists.rb', line 177

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

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

Updates the specified list

Overloads:

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

    Parameters:

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

      A Twitter list ID, slug, URI, 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.

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

    Parameters:

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

      A Twitter user ID, screen name, URI, or object.

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

      A Twitter list ID, slug, URI, 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:

Rate Limited?:

  • No

Authentication:

  • Requires user context



301
302
303
# File 'lib/twitter/rest/lists.rb', line 301

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

- (Array<Twitter::List>) lists(options = {}) - (Array<Twitter::List>) lists(user, options = {}) Also known as: lists_subscribed_to

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

Overloads:

  • - (Array<Twitter::List>) lists(options = {})

    Parameters:

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

      A customizable set of options.

    Options Hash (options):

    • :reverse (Boolean)

      Set this to true if you would like owned lists to be returned first.

  • - (Array<Twitter::List>) lists(user, options = {})

    Parameters:

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

      A Twitter user ID, screen name, URI, or object.

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

      A customizable set of options.

    Options Hash (options):

    • :reverse (Boolean)

      Set this to true if you would like owned lists to be returned first.

Returns:

Raises:

See Also:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



33
34
35
# File 'lib/twitter/rest/lists.rb', line 33

def lists(*args)
  objects_from_response_with_user(Twitter::List, :get, '/1.1/lists/list.json', args)
end

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

List the lists the specified user has been added to

Overloads:

  • - (Twitter::Cursor) memberships(options = {})

    Parameters:

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

      A customizable set of options.

    Options Hash (options):

    • :count (Integer)

      The amount of results to return per page. Defaults to 20. No more than 1000 results will ever be returned in a single page.

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

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

    Parameters:

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

      A Twitter user ID, screen name, URI, or object.

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

      A customizable set of options.

    Options Hash (options):

    • :count (Integer)

      The amount of results to return per page. Defaults to 20. No more than 1000 results will ever be returned in a single page.

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

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



102
103
104
# File 'lib/twitter/rest/lists.rb', line 102

def memberships(*args)
  cursor_from_response_with_user(:lists, Twitter::List, :get, '/1.1/lists/memberships.json', args)
end

- (Array<Twitter::List>) owned_lists(options = {}) - (Array<Twitter::List>) owned_lists(user, options = {})

Returns the lists owned by the specified Twitter user

Overloads:

  • - (Array<Twitter::List>) owned_lists(options = {})

    Parameters:

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

      A customizable set of options.

    Options Hash (options):

    • :count (Integer)

      The amount of results to return per page. Defaults to 20. No more than 1000 results will ever be returned in a single page.

  • - (Array<Twitter::List>) owned_lists(user, options = {})

    Parameters:

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

      A Twitter user ID, screen name, URI, or object.

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

      A customizable set of options.

    Options Hash (options):

    • :count (Integer)

      The amount of results to return per page. Defaults to 20. No more than 1000 results will ever be returned in a single page.

Returns:

Raises:

See Also:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



392
393
394
# File 'lib/twitter/rest/lists.rb', line 392

def owned_lists(*args)
  cursor_from_response_with_user(:lists, Twitter::List, :get, '/1.1/lists/ownerships.json', args)
end

- (Twitter::List) remove_list_member(list, user_to_remove, options = {}) - (Twitter::List) remove_list_member(user, list, user_to_remove, options = {})

Removes the specified member from the list

Overloads:

  • - (Twitter::List) remove_list_member(list, user_to_remove, options = {})

    Parameters:

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

      A Twitter list ID, slug, URI, 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.

  • - (Twitter::List) remove_list_member(user, list, user_to_remove, options = {})

    Parameters:

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

      A Twitter user ID, screen name, URI, or object.

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

      A Twitter list ID, slug, URI, 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:

Rate Limited?:

  • No

Authentication:

  • Requires user context



81
82
83
# File 'lib/twitter/rest/lists.rb', line 81

def remove_list_member(*args)
  list_from_response_with_user(:post, '/1.1/lists/members/destroy.json', args)
end

- (Twitter::List) remove_list_members(list, users, options = {}) - (Twitter::List) remove_list_members(user, list, users, options = {})

Removes specified members from the list

Overloads:

  • - (Twitter::List) remove_list_members(list, users, options = {})

    Parameters:

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

      A Twitter list ID, slug, URI, or object.

    • users (Enumerable<Integer, String, Twitter::User>)

      A collection of Twitter user IDs, screen names, or objects.

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

      A customizable set of options.

  • - (Twitter::List) remove_list_members(user, list, users, options = {})

    Parameters:

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

      A Twitter user ID, screen name, URI, or object.

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

      A Twitter list ID, slug, URI, or object.

    • users (Enumerable<Integer, String, Twitter::User>)

      A collection of Twitter user IDs, screen names, or objects.

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

      A customizable set of options.

Returns:

Raises:

See Also:

Rate Limited?:

  • No

Authentication:

  • Requires user context



373
374
375
# File 'lib/twitter/rest/lists.rb', line 373

def remove_list_members(*args)
  list_from_response_with_users(:post, '/1.1/lists/members/destroy_all.json', args)
end

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

List the lists the specified user follows

Overloads:

  • - (Twitter::Cursor) subscriptions(options = {})

    Parameters:

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

      A customizable set of options.

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

    Parameters:

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

      A Twitter user ID, screen name, URI, or object.

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

      A customizable set of options.

Returns:

Raises:

See Also:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



353
354
355
# File 'lib/twitter/rest/lists.rb', line 353

def subscriptions(*args)
  cursor_from_response_with_user(:lists, Twitter::List, :get, '/1.1/lists/subscriptions.json', args)
end