View Source Tw.V1_1.List (Tw v0.1.0)
Twitter's list data structure (unrelated to List
) and related functions.
A list is a curated group of Twitter accounts. You can create your own lists or subscribe to lists created by others for the authenticated user. Viewing a list timeline will show you a stream of Tweets from only the accounts on that list.
See the Twitter API documentation for details.
Link to this section Summary
Types
Parameters for containing/2
.
Parameters for create/2
.
Parameters for delete/2
.
Parameters for get/2
.
Parameters for list/2
.
Parameters for owned_by/3
.
Parameters for subscribe/2
.
Parameters for subscribed_by/2
.
Parameters for unsubscribe/2
.
Functions
Request GET /lists/memberships.json
and return decoded result.
Request POST /lists/create.json
and return decoded result.
Decode JSON-decoded map into t/0
Request POST /lists/destroy.json
and return decoded result.
Request POST /lists/members/destroy.json
and return decoded result.
Request POST /lists/members/destroy_all.json
and return decoded result.
Request GET /lists/show.json
and return decoded result.
Request GET /lists/list.json
and return decoded result.
Request GET /lists/ownerships.json
and return decoded result.
Request POST /lists/members/create.json
and return decoded result.
Request POST /lists/members/create_all.json
and return decoded result.
Request POST /lists/subscribers/create.json
and return decoded result.
Request GET /lists/subscriptions.json
and return decoded result.
Request POST /lists/subscribers/destroy.json
and return decoded result.
Request POST /lists/update.json
and return decoded result.
Link to this section Types
Specs
containing_params() :: %{ :screen_name => Tw.V1_1.User.screen_name(), optional(:count) => pos_integer(), optional(:cursor) => Tw.V1_1.CursoredResult.cursor(), optional(:filter_to_owned_lists) => boolean() } | %{ :user_id => Tw.V1_1.User.id(), optional(:count) => pos_integer(), optional(:cursor) => Tw.V1_1.CursoredResult.cursor(), optional(:filter_to_owned_lists) => boolean() } | %{ :user => Tw.V1_1.User.t(), optional(:count) => pos_integer(), optional(:cursor) => Tw.V1_1.CursoredResult.cursor(), optional(:filter_to_owned_lists) => boolean() } | %{ optional(:count) => pos_integer(), optional(:cursor) => Tw.V1_1.CursoredResult.cursor(), optional(:filter_to_owned_lists) => boolean() }
Parameters for containing/2
.
name description user_id The ID of the user for whom to return results. Helpful for disambiguating when a valid user ID is also a valid screen name. screen_name The screen name of the user for whom to return results. Helpful for disambiguating when a valid screen name is also a user ID. count The amount of results to return per page. Defaults to 20. No more than 1000 results will ever be returned in a single page. cursor Breaks the results into pages. 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. It is recommended to always use cursors when the method supports them. See Cursoring for more information. filter_to_owned_lists 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.
See the Twitter API documentation for details.
Specs
create_params() :: %{ :name => binary(), optional(:mode) => mode(), optional(:description) => binary() }
Parameters for create/2
.
name description name The name for the list. A list's name must start with a letter and can consist only of 25 or fewer letters, numbers, "-", or "_" characters. mode Whether your list is public or private. Values can be public or private . If no mode is specified the list will be public. description The description to give the list.
See the Twitter API documentation for details.
Specs
delete_member_params() :: %{ slug: binary(), owner_screen_name: Tw.V1_1.User.screen_name(), screen_name: Tw.V1_1.User.screen_name() } | %{ slug: binary(), owner_screen_name: Tw.V1_1.User.screen_name(), user_id: Tw.V1_1.User.id() } | %{ slug: binary(), owner_screen_name: Tw.V1_1.User.screen_name(), user: Tw.V1_1.User.t() } | %{ slug: binary(), owner_id: Tw.V1_1.User.id(), screen_name: Tw.V1_1.User.screen_name() } | %{slug: binary(), owner_id: Tw.V1_1.User.id(), user_id: Tw.V1_1.User.id()} | %{slug: binary(), owner_id: Tw.V1_1.User.id(), user: Tw.V1_1.User.t()} | %{list_id: non_neg_integer(), screen_name: Tw.V1_1.User.screen_name()} | %{list_id: non_neg_integer(), user_id: Tw.V1_1.User.id()} | %{list_id: non_neg_integer(), user: Tw.V1_1.User.t()} | %{list: t(), screen_name: Tw.V1_1.User.screen_name()} | %{list: t(), user_id: Tw.V1_1.User.id()} | %{list: t(), user: Tw.V1_1.User.t()}
Specs
delete_members_params() :: %{ slug: binary(), owner_screen_name: Tw.V1_1.User.screen_name(), screen_names: [Tw.V1_1.User.screen_name()] } | %{ slug: binary(), owner_screen_name: Tw.V1_1.User.screen_name(), user_ids: [Tw.V1_1.User.id()] } | %{ slug: binary(), owner_screen_name: Tw.V1_1.User.screen_name(), users: [Tw.V1_1.User.t()] } | %{ slug: binary(), owner_id: Tw.V1_1.User.id(), screen_names: [Tw.V1_1.User.screen_name()] } | %{ slug: binary(), owner_id: Tw.V1_1.User.id(), user_ids: [Tw.V1_1.User.id()] } | %{slug: binary(), owner_id: Tw.V1_1.User.id(), users: [Tw.V1_1.User.t()]} | %{list_id: non_neg_integer(), screen_names: [Tw.V1_1.User.screen_name()]} | %{list_id: non_neg_integer(), user_ids: [Tw.V1_1.User.id()]} | %{list_id: non_neg_integer(), users: [Tw.V1_1.User.t()]} | %{list: t(), screen_names: [Tw.V1_1.User.screen_name()]} | %{list: t(), user_ids: [Tw.V1_1.User.id()]} | %{list: t(), users: [Tw.V1_1.User.t()]}
Specs
delete_params() :: Tw.V1_1.Endpoint.list_params()
Parameters for delete/2
.
name description owner_screen_name The screen name of the user who owns the list being requested by a slug . owner_id The user ID of the user who owns the list being requested by a slug . list_id The numerical id of the list. slug You can identify a list by its slug instead of its numerical id. If you decide to do so, note that you'll also have to specify the list owner using the owner_id or owner_screen_name parameters.
See the Twitter API documentation for details.
Specs
get_params() :: Tw.V1_1.Endpoint.list_params()
Parameters for get/2
.
name description list_id The numerical id of the list. slug You can identify a list by its slug instead of its numerical id. If you decide to do so, note that you'll also have to specify the list owner using the owner_id or owner_screen_name parameters. owner_screen_name The screen name of the user who owns the list being requested by a slug . owner_id The user ID of the user who owns the list being requested by a slug .
See the Twitter API documentation for details.
Specs
list_params() :: %{optional(:reverse) => boolean()} | %{:user_id => Tw.V1_1.User.id(), optional(:reverse) => boolean()} | %{ :screen_name => Tw.V1_1.User.screen_name(), optional(:reverse) => boolean() }
Parameters for list/2
.
name description user_id The ID of the user for whom to return results. Helpful for disambiguating when a valid user ID is also a valid screen name. Note: : Specifies the ID of the user to get lists from. Helpful for disambiguating when a valid user ID is also a valid screen name. screen_name The screen name of the user for whom to return results. Helpful for disambiguating when a valid screen name is also a user ID. reverse Set this to true if you would like owned lists to be returned first. See description above for information on how this parameter works.
See the Twitter API documentation for details.
Specs
mode() :: :private | :public
Specs
owned_by_params() :: %{ :screen_name => Tw.V1_1.User.screen_name(), optional(:count) => pos_integer(), optional(:cursor) => Tw.V1_1.CursoredResult.cursor() } | %{ :user_id => Tw.V1_1.User.id(), optional(:count) => pos_integer(), optional(:cursor) => Tw.V1_1.CursoredResult.cursor() } | %{ :user => Tw.V1_1.User.t(), optional(:count) => pos_integer(), optional(:cursor) => Tw.V1_1.CursoredResult.cursor() } | %{ optional(:count) => pos_integer(), optional(:cursor) => Tw.V1_1.CursoredResult.cursor() }
Parameters for owned_by/3
.
name description user_id The ID of the user for whom to return results. Helpful for disambiguating when a valid user ID is also a valid screen name. screen_name The screen name of the user for whom to return results. Helpful for disambiguating when a valid screen name is also a user ID. count The amount of results to return per page. Defaults to 20. No more than 1000 results will ever be returned in a single page. cursor Breaks the results into pages. 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. It is recommended to always use cursors when the method supports them. See Cursoring for more information.
See the Twitter API documentation for details.
Specs
put_member_params() :: %{ slug: binary(), owner_screen_name: Tw.V1_1.User.screen_name(), screen_name: Tw.V1_1.User.screen_name() } | %{ slug: binary(), owner_screen_name: Tw.V1_1.User.screen_name(), user_id: Tw.V1_1.User.id() } | %{ slug: binary(), owner_screen_name: Tw.V1_1.User.screen_name(), user: Tw.V1_1.User.t() } | %{ slug: binary(), owner_id: Tw.V1_1.User.id(), screen_name: Tw.V1_1.User.screen_name() } | %{slug: binary(), owner_id: Tw.V1_1.User.id(), user_id: Tw.V1_1.User.id()} | %{slug: binary(), owner_id: Tw.V1_1.User.id(), user: Tw.V1_1.User.t()} | %{list_id: non_neg_integer(), screen_name: Tw.V1_1.User.screen_name()} | %{list_id: non_neg_integer(), user_id: Tw.V1_1.User.id()} | %{list_id: non_neg_integer(), user: Tw.V1_1.User.t()} | %{list: t(), screen_name: Tw.V1_1.User.screen_name()} | %{list: t(), user_id: Tw.V1_1.User.id()} | %{list: t(), user: Tw.V1_1.User.t()}
Specs
put_members_params() :: %{ slug: binary(), owner_screen_name: Tw.V1_1.User.screen_name(), screen_names: [Tw.V1_1.User.screen_name()] } | %{ slug: binary(), owner_screen_name: Tw.V1_1.User.screen_name(), user_ids: [Tw.V1_1.User.id()] } | %{ slug: binary(), owner_screen_name: Tw.V1_1.User.screen_name(), users: [Tw.V1_1.User.t()] } | %{ slug: binary(), owner_id: Tw.V1_1.User.id(), screen_names: [Tw.V1_1.User.screen_name()] } | %{ slug: binary(), owner_id: Tw.V1_1.User.id(), user_ids: [Tw.V1_1.User.id()] } | %{slug: binary(), owner_id: Tw.V1_1.User.id(), users: [Tw.V1_1.User.t()]} | %{list_id: non_neg_integer(), screen_names: [Tw.V1_1.User.screen_name()]} | %{list_id: non_neg_integer(), user_ids: [Tw.V1_1.User.id()]} | %{list_id: non_neg_integer(), users: [Tw.V1_1.User.t()]} | %{list: t(), screen_names: [Tw.V1_1.User.screen_name()]} | %{list: t(), user_ids: [Tw.V1_1.User.id()]} | %{list: t(), users: [Tw.V1_1.User.t()]}
Specs
subscribe_params() :: Tw.V1_1.Endpoint.list_params()
Parameters for subscribe/2
.
name description owner_screen_name The screen name of the user who owns the list being requested by a slug . owner_id The user ID of the user who owns the list being requested by a slug . list_id The numerical id of the list. slug You can identify a list by its slug instead of its numerical id. If you decide to do so, note that you'll also have to specify the list owner using the owner_id or owner_screen_name parameters.
See the Twitter API documentation for details.
Specs
subscribed_by_params() :: %{ :screen_name => Tw.V1_1.User.screen_name(), optional(:count) => pos_integer(), optional(:cursor) => Tw.V1_1.CursoredResult.cursor() } | %{ :user_id => Tw.V1_1.User.id(), optional(:count) => pos_integer(), optional(:cursor) => Tw.V1_1.CursoredResult.cursor() } | %{ :user => Tw.V1_1.User.t(), optional(:count) => pos_integer(), optional(:cursor) => Tw.V1_1.CursoredResult.cursor() } | %{ optional(:count) => pos_integer(), optional(:cursor) => Tw.V1_1.CursoredResult.cursor() }
Parameters for subscribed_by/2
.
name description user_id The ID of the user for whom to return results. Helpful for disambiguating when a valid user ID is also a valid screen name. screen_name The screen name of the user for whom to return results. Helpful for disambiguating when a valid screen name is also a user ID. count The amount of results to return per page. Defaults to 20. No more than 1000 results will ever be returned in a single page. cursor Breaks the results into pages. 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. It is recommended to always use cursors when the method supports them. See Cursoring for more information.
See the Twitter API documentation for details.
Specs
t() :: %Tw.V1_1.List{ created_at: DateTime.t(), description: binary(), following: boolean(), full_name: binary(), id: pos_integer(), id_str: binary(), member_count: non_neg_integer(), mode: mode(), name: binary(), slug: binary(), subscriber_count: non_neg_integer(), uri: binary(), user: Tw.V1_1.User.t() }
Specs
unsubscribe_params() :: Tw.V1_1.Endpoint.list_params()
Parameters for unsubscribe/2
.
name description list_id The numerical id of the list. slug You can identify a list by its slug instead of its numerical id. If you decide to do so, note that you'll also have to specify the list owner using the owner_id or owner_screen_name parameters. owner_screen_name The screen name of the user who owns the list being requested by a slug . owner_id The user ID of the user who owns the list being requested by a slug .
See the Twitter API documentation for details.
Specs
update_params() :: %{ :slug => binary(), :owner_screen_name => Tw.V1_1.User.screen_name(), optional(:name) => binary(), optional(:mode) => mode(), optional(:description) => binary() } | %{ :slug => binary(), :owner_id => Tw.V1_1.User.id(), optional(:name) => binary(), optional(:mode) => mode(), optional(:description) => binary() } | %{ :list_id => non_neg_integer(), optional(:name) => binary(), optional(:mode) => mode(), optional(:description) => binary() } | %{ :list => t(), optional(:name) => binary(), optional(:mode) => mode(), optional(:description) => binary() }
Link to this section Functions
Specs
containing(Tw.V1_1.Client.t(), containing_params()) :: {:ok, Tw.V1_1.CursoredResult.t(:lists, [t()])} | {:error, Tw.V1_1.Client.error()}
Request GET /lists/memberships.json
and return decoded result.
Returns the lists the specified user has been added to. If user_id or screen_name are not provided, the memberships for the authenticating user are returned.
See the Twitter API documentation for details.
Specs
create(Tw.V1_1.Client.t(), create_params()) :: {:ok, t()} | {:error, Tw.V1_1.Client.error()}
Request POST /lists/create.json
and return decoded result.
Creates a new list for the authenticated user. Note that you can create up to 1000 lists per account.
See the Twitter API documentation for details.
Specs
Decode JSON-decoded map into t/0
Specs
delete(Tw.V1_1.Client.t(), delete_params()) :: {:ok, t()} | {:error, Tw.V1_1.Client.error()}
Request POST /lists/destroy.json
and return decoded result.
Deletes the specified list. The authenticated user must own the list to be able to destroy it.
See the Twitter API documentation for details.
Examples
iex> {:ok, list} = Tw.V1_1.List.get(client, %{list_id: 574})
iex> {:ok, list} = Tw.V1_1.List.delete(client, %{list: list})
{:ok, %Tw.V1_1.List{}}
iex> {:ok, list} = Tw.V1_1.List.delete(client, %{list_id: 574})
{:ok, %Tw.V1_1.List{}}
Specs
delete_member(Tw.V1_1.Client.t(), delete_member_params()) :: {:ok, t()} | {:error, Tw.V1_1.Client.error()}
Request POST /lists/members/destroy.json
and return decoded result.
Removes the specified member from the list. The authenticated user must be the list's owner to remove members from the list.
See the Twitter API documentation for details.
Specs
delete_members(Tw.V1_1.Client.t(), delete_members_params()) :: {:ok, t()} | {:error, Tw.V1_1.Client.error()}
Request POST /lists/members/destroy_all.json
and return decoded result.
Removes multiple members from a list, by specifying a comma-separated list of member ids or screen names. The authenticated user must own the list to be able to remove members from it. Note that lists can't have more than 500 members, and you are limited to removing up to 100 members to a list at a time with this method.
Please note that there can be issues with lists that rapidly remove and add memberships. Take care when using these methods such that you are not too rapidly switching between removals and adds on the same list.
See the Twitter API documentation for details.
Specs
get(Tw.V1_1.Client.t(), get_params()) :: {:ok, t()} | {:error, Tw.V1_1.Client.error()}
Request GET /lists/show.json
and return decoded result.
Returns the specified list. Private lists will only be shown if the authenticated user owns the specified list.
See the Twitter API documentation for details.
Specs
list(Tw.V1_1.Client.t(), list_params()) :: {:ok, [t()]} | {:error, Tw.V1_1.Client.error()}
Request GET /lists/list.json
and return decoded result.
Returns all lists the authenticating or specified user subscribes to, including their own. The user is specified using the user_id or screen_name parameters. If no user is given, the authenticating user is used.
A maximum of 100 results will be returned by this call. Subscribed lists are returned first, followed by owned lists. This means that if a user subscribes to 90 lists and owns 20 lists, this method returns 90 subscriptions and 10 owned lists. The reverse method returns owned lists first, so with reverse=true, 20 owned lists and 80 subscriptions would be returned. If your goal is to obtain every list a user owns or subscribes to, use GET lists / ownerships and/or GET lists / subscriptions instead.
See the Twitter API documentation for details.
Specs
owned_by(Tw.V1_1.Client.t(), owned_by_params()) :: {:ok, Tw.V1_1.CursoredResult.t(:lists, [t()])} | {:error, Tw.V1_1.Client.error()}
Request GET /lists/ownerships.json
and return decoded result.
Returns the lists owned by the specified Twitter user. Private lists will only be shown if the authenticated user is also the owner of the lists.
See the Twitter API documentation for details.
Specs
put_member(Tw.V1_1.Client.t(), put_member_params()) :: {:ok, t()} | {:error, Tw.V1_1.Client.error()}
Request POST /lists/members/create.json
and return decoded result.
Add a member to a list. The authenticated user must own the list to be able to add members to it. Note that lists cannot have more than 5,000 members.
See the Twitter API documentation for details.
Specs
put_members(Tw.V1_1.Client.t(), put_members_params()) :: {:ok, t()} | {:error, Tw.V1_1.Client.error()}
Request POST /lists/members/create_all.json
and return decoded result.
Adds multiple members to a list, by specifying a comma-separated list of member ids or screen names. The authenticated user must own the list to be able to add members to it. Note that lists can't have more than 5,000 members, and you are limited to adding up to 100 members to a list at a time with this method.
Please note that there can be issues with lists that rapidly remove and add memberships. Take care when using these methods such that you are not too rapidly switching between removals and adds on the same list.
See the Twitter API documentation for details.
Specs
subscribe(Tw.V1_1.Client.t(), subscribe_params()) :: {:ok, t()} | {:error, Tw.V1_1.Client.error()}
Request POST /lists/subscribers/create.json
and return decoded result.
Subscribes the authenticated user to the specified list.
See the Twitter API documentation for details.
Examples
iex> {:ok, list} = Tw.V1_1.List.get(client, %{list_id: 574})
iex> {:ok, list} = Tw.V1_1.List.subscribe(client, %{list: list})
{:ok, %Tw.V1_1.List{}}
iex> {:ok, list} = Tw.V1_1.List.subscribe(client, %{list_id: 574})
{:ok, %Tw.V1_1.List{}}
Specs
subscribed_by(Tw.V1_1.Client.t(), subscribed_by_params()) :: {:ok, Tw.V1_1.CursoredResult.t(:lists, [t()])} | {:error, Tw.V1_1.Client.error()}
Request GET /lists/subscriptions.json
and return decoded result.
Obtain a collection of the lists the specified user is subscribed to, 20 lists per page by default. Does not include the user's own lists.
See the Twitter API documentation for details.
Specs
unsubscribe(Tw.V1_1.Client.t(), unsubscribe_params()) :: {:ok, t()} | {:error, Tw.V1_1.Client.error()}
Request POST /lists/subscribers/destroy.json
and return decoded result.
Unsubscribes the authenticated user from the specified list.
See the Twitter API documentation for details.
Examples
iex> {:ok, list} = Tw.V1_1.List.get(client, %{list_id: 574})
iex> {:ok, list} = Tw.V1_1.List.unsubscribe(client, %{list: list})
{:ok, %Tw.V1_1.List{}}
iex> {:ok, list} = Tw.V1_1.List.unsubscribe(client, %{list_id: 574})
{:ok, %Tw.V1_1.List{}}
Specs
update(Tw.V1_1.Client.t(), update_params()) :: {:ok, t()} | {:error, Tw.V1_1.Client.error()}
Request POST /lists/update.json
and return decoded result.
Updates the specified list. The authenticated user must own the list to be able to update it.
See the Twitter API documentation for details.
Examples
iex> {:ok, list} = Tw.V1_1.List.get(client, %{list_id: 574})
iex> {:ok, list} = Tw.V1_1.List.update(client, %{list: list, name: "updated"})
{:ok, %Tw.V1_1.List{name: "updated"}}
iex> {:ok, list} = Tw.V1_1.List.update(client, %{list_id: 574}, %{name: "updated"})
{:ok, %Tw.V1_1.List{name: "updated"}}