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

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.

namedescription
user_idThe ID of the user for whom to return results. Helpful for disambiguating when a valid user ID is also a valid screen name.
screen_nameThe screen name of the user for whom to return results. Helpful for disambiguating when a valid screen name is also a user ID.
countThe amount of results to return per page. Defaults to 20. No more than 1000 results will ever be returned in a single page.
cursorBreaks 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_listsWhen 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.

namedescription
nameThe 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.
modeWhether your list is public or private. Values can be public or private . If no mode is specified the list will be public.
descriptionThe description to give the list.

See the Twitter API documentation for details.

Link to this type

delete_member_params()

View Source

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()}
Link to this type

delete_members_params()

View Source

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.

namedescription
owner_screen_nameThe screen name of the user who owns the list being requested by a slug .
owner_idThe user ID of the user who owns the list being requested by a slug .
list_idThe numerical id of the list.
slugYou 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.

namedescription
list_idThe numerical id of the list.
slugYou 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_nameThe screen name of the user who owns the list being requested by a slug .
owner_idThe 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.

namedescription
user_idThe 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_nameThe screen name of the user for whom to return results. Helpful for disambiguating when a valid screen name is also a user ID.
reverseSet 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.

namedescription
user_idThe ID of the user for whom to return results. Helpful for disambiguating when a valid user ID is also a valid screen name.
screen_nameThe screen name of the user for whom to return results. Helpful for disambiguating when a valid screen name is also a user ID.
countThe amount of results to return per page. Defaults to 20. No more than 1000 results will ever be returned in a single page.
cursorBreaks 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.

namedescription
owner_screen_nameThe screen name of the user who owns the list being requested by a slug .
owner_idThe user ID of the user who owns the list being requested by a slug .
list_idThe numerical id of the list.
slugYou 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.

Link to this type

subscribed_by_params()

View Source

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.

namedescription
user_idThe ID of the user for whom to return results. Helpful for disambiguating when a valid user ID is also a valid screen name.
screen_nameThe screen name of the user for whom to return results. Helpful for disambiguating when a valid screen name is also a user ID.
countThe amount of results to return per page. Defaults to 20. No more than 1000 results will ever be returned in a single page.
cursorBreaks 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.

namedescription
list_idThe numerical id of the list.
slugYou 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_nameThe screen name of the user who owns the list being requested by a slug .
owner_idThe 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

Link to this function

containing(client, params \\ %{})

View Source

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!(map()) :: t()

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{}}
Link to this function

delete_member(client, params)

View Source

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.

Link to this function

delete_members(client, params)

View Source

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.

Link to this function

get_member(client, paramas)

View Source

See Tw.V1_1.User.list_member/2.

Link to this function

get_subscriber(client, paramas)

View Source

See Tw.V1_1.User.list_subscriber/2.

Link to this function

list(client, params \\ %{})

View Source

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.

Link to this function

owned_by(client, params \\ %{})

View Source

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.

Link to this function

put_member(client, params)

View Source

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.

Link to this function

put_members(client, params)

View Source

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.

Link to this function

subscribe(client, params)

View Source

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{}}
Link to this function

subscribed_by(client, params \\ %{})

View Source

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.

Link to this function

unsubscribe(client, params)

View Source

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"}}