Module: Twitter::API::Lists

Includes:: Utils

Included in:: Client

Defined in:: lib/twitter/api/lists.rb

Constant Summary collapse

MAX_USERS_PER_REQUEST =

Constants included from Utils

Utils::DEFAULT_CURSOR

Instance Method Summary collapse

#list(*args) ⇒ Twitter::List
Show the specified list.
#list_add_member(*args) ⇒ Twitter::List
Add a member to a list.
#list_add_members(*args) ⇒ Twitter::List
Adds specified members to a list.
#list_create(name, options = {}) ⇒ Twitter::List
Creates a new list for the authenticated user.
#list_destroy(*args) ⇒ Twitter::List
Deletes the specified list.
#list_member?(*args) ⇒ Boolean
Check if a user is a member of the specified list.
#list_members(*args) ⇒ Twitter::Cursor
Returns the members of the specified list.
#list_remove_member(*args) ⇒ Twitter::List
Removes the specified member from the list.
#list_remove_members(*args) ⇒ Twitter::List
Removes specified members from the list.
#list_subscribe(*args) ⇒ Twitter::List
Make the authenticated user follow the specified list.
#list_subscriber?(*args) ⇒ Boolean
Check if a user is a subscriber of the specified list.
#list_subscribers(*args) ⇒ Twitter::Cursor
Returns the subscribers of the specified list.
#list_timeline(*args) ⇒ Array<Twitter::Tweet>
Show tweet timeline for members of the specified list.
#list_unsubscribe(*args) ⇒ Twitter::List
Unsubscribes the authenticated user form the specified list.
#list_update(*args) ⇒ Twitter::List
Updates the specified list.
#lists(*args) ⇒ Array<Twitter::List> (also: #lists_subscribed_to)
Returns all lists the authenticating or specified user subscribes to, including their own.
#memberships(*args) ⇒ Twitter::Cursor
List the lists the specified user has been added to.
#subscriptions(*args) ⇒ Twitter::Cursor
List the lists the specified user follows.

Instance Method Details

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

(Twitter::List) —
The specified list.

Raises:

(Twitter::Error::Unauthorized) —
Error raised when supplied user credentials are not valid.

See Also:

https://dev.twitter.com/docs/api/1.1/get/lists/show

Authentication:

Requires user context

Rate Limited?:



450
451
452

# File 'lib/twitter/api/lists.rb', line 450

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:

(Twitter::List) —
The list.

Raises:

(Twitter::Error::Unauthorized) —
Error raised when supplied user credentials are not valid.

See Also:

https://dev.twitter.com/docs/api/1.1/post/lists/members/create

Authentication:

Requires user context

Rate Limited?:



348
349
350

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

def list_add_member(*args)
  list_from_response_with_user(: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 (Integer, String, Twitter::List) —
  A Twitter list ID, slug, or object.
- users (Array<Integer, String, Twitter::User>, Set<Integer, String, Twitter::User>) —
  An array of Twitter user IDs, screen names, or objects.
- options (Hash) (defaults to: {}) —
  A customizable set of options.
#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:
- 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.
- users (Array<Integer, String, Twitter::User>, Set<Integer, String, Twitter::User>) —
  An array of Twitter user IDs, screen names, or objects.
- options (Hash) (defaults to: {}) —
  A customizable set of options.

Returns:

(Twitter::List) —
The list.

Raises:

(Twitter::Error::Unauthorized) —
Error raised when supplied user credentials are not valid.

See Also:

https://dev.twitter.com/docs/api/1.1/post/lists/members/create_all

Authentication:

Requires user context

Rate Limited?:



264
265
266

# File 'lib/twitter/api/lists.rb', line 264

def list_add_members(*args)
  list_from_response_with_users(: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:

(Twitter::List) —
The created list.

Raises:

(Twitter::Error::Unauthorized) —
Error raised when supplied user credentials are not valid.

See Also:

https://dev.twitter.com/docs/api/1.1/post/lists/create

Authentication:

Requires user context

Rate Limited?:



423
424
425

# File 'lib/twitter/api/lists.rb', line 423

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:

(Twitter::List) —
The deleted list.

Raises:

(Twitter::Error::Unauthorized) —
Error raised when supplied user credentials are not valid.

See Also:

https://dev.twitter.com/docs/api/1.1/post/lists/destroy

Authentication:

Requires user context

Rate Limited?:



375
376
377

# File 'lib/twitter/api/lists.rb', line 375

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:

(Twitter::Error::Unauthorized) —
Error raised when supplied user credentials are not valid.

See Also:

https://dev.twitter.com/docs/api/1.1/get/lists/members/show

Authentication:

Requires user context

Rate Limited?:



291
292
293

# File 'lib/twitter/api/lists.rb', line 291

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:

(Twitter::Cursor)

Raises:

(Twitter::Error::Unauthorized) —
Error raised when supplied user credentials are not valid.

See Also:

https://dev.twitter.com/docs/api/1.1/get/lists/members

Authentication:

Requires user context

Rate Limited?:



319
320
321

# File 'lib/twitter/api/lists.rb', line 319

def list_members(*args)
  cursor_from_response_with_list(:get, "/1.1/lists/members.json", args, :list_members)
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:

(Twitter::List) —
The list.

Raises:

(Twitter::Error::Unauthorized) —
Error raised when supplied user credentials are not valid.

See Also:

https://dev.twitter.com/docs/api/1.1/post/lists/members/destroy

Authentication:

Requires user context

Rate Limited?:



99
100
101

# File 'lib/twitter/api/lists.rb', line 99

def list_remove_member(*args)
  list_from_response_with_user(: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 (Integer, String, Twitter::List) —
  A Twitter list ID, slug, or object.
- users (Array<Integer, String, Twitter::User>, Set<Integer, String, Twitter::User>) —
  An array of Twitter user IDs, screen names, or objects.
- options (Hash) (defaults to: {}) —
  A customizable set of options.
#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:
- 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.
- users (Array<Integer, String, Twitter::User>, Set<Integer, String, Twitter::User>) —
  An array of Twitter user IDs, screen names, or objects.
- options (Hash) (defaults to: {}) —
  A customizable set of options.

Returns:

(Twitter::List) —
The list.

Raises:

(Twitter::Error::Unauthorized) —
Error raised when supplied user credentials are not valid.

See Also:

https://dev.twitter.com/docs/api/1.1/post/lists/members/destroy_all

Authentication:

Requires user context

Rate Limited?:



505
506
507

# File 'lib/twitter/api/lists.rb', line 505

def list_remove_members(*args)
  list_from_response_with_users(: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:

(Twitter::List) —
The specified list.

Raises:

(Twitter::Error::Unauthorized) —
Error raised when supplied user credentials are not valid.

See Also:

https://dev.twitter.com/docs/api/1.1/post/lists/subscribers/create

Authentication:

Requires user context

Rate Limited?:



176
177
178

# File 'lib/twitter/api/lists.rb', line 176

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:

(Twitter::Error::Unauthorized) —
Error raised when supplied user credentials are not valid.

See Also:

https://dev.twitter.com/docs/api/1.1/get/lists/subscribers/show

Authentication:

Requires user context

Rate Limited?:



206
207
208

# File 'lib/twitter/api/lists.rb', line 206

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:

(Twitter::Cursor) —
The subscribers of the specified list.

Raises:

(Twitter::Error::Unauthorized) —
Error raised when supplied user credentials are not valid.

See Also:

https://dev.twitter.com/docs/api/1.1/get/lists/subscribers

Authentication:

Requires user context

Rate Limited?:



151
152
153

# File 'lib/twitter/api/lists.rb', line 151

def list_subscribers(*args)
  cursor_from_response_with_list(:get, "/1.1/lists/subscribers.json", args, :list_subscribers)
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:

(Array<Twitter::Tweet>)

Raises:

(Twitter::Error::Unauthorized) —
Error raised when supplied user credentials are not valid.

See Also:

https://dev.twitter.com/docs/api/1.1/get/lists/statuses

Authentication:

Requires user context

Rate Limited?:

# File 'lib/twitter/api/lists.rb', line 67

def list_timeline(*args)
  arguments = Twitter::API::Arguments.new(args)
  merge_list!(arguments.options, arguments.pop)
  merge_owner!(arguments.options, arguments.pop || screen_name) unless arguments.options[:owner_id] || arguments.options[:owner_screen_name]
  objects_from_response(Twitter::Tweet, :get, "/1.1/lists/statuses.json", arguments.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:

(Twitter::List) —
The specified list.

Raises:

(Twitter::Error::Unauthorized) —
Error raised when supplied user credentials are not valid.

See Also:

https://dev.twitter.com/docs/api/1.1/post/lists/subscribers/destroy

Authentication:

Requires user context

Rate Limited?:



231
232
233

# File 'lib/twitter/api/lists.rb', line 231

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:

(Twitter::List) —
The created list.

Raises:

(Twitter::Error::Unauthorized) —
Error raised when supplied user credentials are not valid.

See Also:

https://dev.twitter.com/docs/api/1.1/post/lists/update

Authentication:

Requires user context

Rate Limited?:



405
406
407

# File 'lib/twitter/api/lists.rb', line 405

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

#lists(options = {}) ⇒ `Array<Twitter::List>` #lists(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:

#lists(options = {}) ⇒ Array<Twitter::List>
Examples:

Return all lists the authenticating user subscribes to
```
Twitter.lists
```
Parameters:
- options (Hash) (defaults to: {}) —
  A customizable set of options.
#lists(user, options = {}) ⇒ Array<Twitter::List>
Examples:

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

(Array<Twitter::List>)

Raises:

(Twitter::Error::Unauthorized) —
Error raised when supplied user credentials are not valid.

See Also:

https://dev.twitter.com/docs/api/1.1/get/lists/list

Authentication:

Requires user context

Rate Limited?:



34
35
36

# File 'lib/twitter/api/lists.rb', line 34

def lists(*args)
  objects_from_response_with_user(Twitter::List, :get, "/1.1/lists/list.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:

(Twitter::Cursor)

Raises:

(Twitter::Error::Unauthorized) —
Error raised when supplied user credentials are not valid.

See Also:

https://dev.twitter.com/docs/api/1.1/get/lists/memberships

Authentication:

Requires user context

Rate Limited?:



124
125
126

# File 'lib/twitter/api/lists.rb', line 124

def memberships(*args)
  cursor_from_response_with_user(:lists, Twitter::List, :get, "/1.1/lists/memberships.json", args, :memberships)
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:

(Twitter::Cursor)

Raises:

(Twitter::Error::Unauthorized) —
Error raised when supplied user credentials are not valid.

See Also:

https://dev.twitter.com/docs/api/1.1/get/lists/subscriptions

Authentication:

Requires user context

Rate Limited?:



473
474
475

# File 'lib/twitter/api/lists.rb', line 473

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

Module: Twitter::API::Lists

Constant Summary collapse

Constants included from Utils

Instance Method Summary collapse

Instance Method Details

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

Examples:

Show the authenticated user's "presidents" list

Examples:

Show @sferik's "presidents" list

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

Examples:

Add @BarackObama to the authenticated user's "presidents" list

Examples:

Add @BarackObama to @sferik's "presidents" list

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

Examples:

Add @BarackObama and @pengwynn to the authenticated user's "presidents" list

Examples:

Add @BarackObama and @pengwynn to @sferik's "presidents" list

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

Examples:

Create a list named 'presidents'

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

Examples:

Delete the authenticated user's "presidents" list

Examples:

Delete @sferik's "presidents" list

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

Examples:

Check if @BarackObama is a member of the authenticated user's "presidents" list

Examples:

Check if @BarackObama is a member of @sferik's "presidents" list

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

Examples:

Return the members of the authenticated user's "presidents" list

Examples:

Return the members of @sferik's "presidents" list

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

Examples:

Remove @BarackObama from the authenticated user's "presidents" list

Examples:

Remove @BarackObama from @sferik's "presidents" list

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

Examples:

Remove @BarackObama and @pengwynn from the authenticated user's "presidents" list

Examples:

Remove @BarackObama and @pengwynn from @sferik's "presidents" list

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

Examples:

Subscribe to the authenticated user's "presidents" list

Examples:

Subscribe to @sferik's "presidents" list

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

Examples:

Check if @BarackObama is a subscriber of the authenticated user's "presidents" list

Examples:

Check if @BarackObama is a subscriber of @sferik's "presidents" list

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

Examples:

Return the subscribers of the authenticated user's "presidents" list

Examples:

Return the subscribers of @sferik's "presidents" list

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

Examples:

Show tweet timeline for members of the authenticated user's "presidents" list

Examples:

Show tweet timeline for members of @sferik's "presidents" list

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

Examples:

Unsubscribe from the authenticated user's "presidents" list

Examples:

Unsubscribe from @sferik's "presidents" list

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

Examples:

Update the authenticated user's "presidents" list to have the description "Presidents of the United States of America"

Examples:

Update the @sferik's "presidents" list to have the description "Presidents of the United States of America"

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

Examples:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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