Modules Documentation

API

A library that provides a Python interface to the Twitter API

class twitter.api.Api(consumer_key=None, consumer_secret=None, access_token_key=None, access_token_secret=None, application_only_auth=False, input_encoding=None, request_headers=None, cache=<object object>, base_url=None, stream_url=None, upload_url=None, chunk_size=1048576, use_gzip_compression=False, debugHTTP=False, timeout=None, sleep_on_rate_limit=False, tweet_mode='compat', proxies=None)[source]

Bases: object

A python interface into the Twitter API

By default, the Api caches results for 1 minute.

Example usage:

To create an instance of the twitter.Api class, with no authentication:

>>> import twitter
>>> api = twitter.Api()

To fetch a single user’s public status messages, where “user” is either a Twitter “short name” or their user id.

>>> statuses = api.GetUserTimeline(user)
>>> print([s.text for s in statuses])

To use authentication, instantiate the twitter.Api class with a consumer key and secret; and the oAuth key and secret:

>>> api = twitter.Api(consumer_key='twitter consumer key',
                      consumer_secret='twitter consumer secret',
                      access_token_key='the_key_given',
                      access_token_secret='the_key_secret')

To fetch your friends (after being authenticated):

>>> users = api.GetFriends()
>>> print([u.name for u in users])

To post a twitter status message (after being authenticated):

>>> status = api.PostUpdate('I love python-twitter!')
>>> print(status.text)
I love python-twitter!

There are many other methods, including:

>>> api.PostUpdates(status)
>>> api.PostDirectMessage(user, text)
>>> api.GetUser(user)
>>> api.GetReplies()
>>> api.GetUserTimeline(user)
>>> api.GetHomeTimeline()
>>> api.GetStatus(status_id)
>>> api.GetStatuses(status_ids)
>>> api.DestroyStatus(status_id)
>>> api.GetFriends(user)
>>> api.GetFollowers()
>>> api.GetFeatured()
>>> api.GetDirectMessages()
>>> api.GetSentDirectMessages()
>>> api.PostDirectMessage(user, text)
>>> api.DestroyDirectMessage(message_id)
>>> api.DestroyFriendship(user)
>>> api.CreateFriendship(user)
>>> api.LookupFriendship(user)
>>> api.VerifyCredentials()
CheckRateLimit(url)[source]

Checks a URL to see the rate limit status for that endpoint.

Parameters:url (str) – URL to check against the current rate limits.
Returns:EndpointRateLimit namedtuple.
Return type:namedtuple
ClearCredentials()[source]

Clear any credentials for this instance

CreateBlock(user_id=None, screen_name=None, include_entities=True, skip_status=False)[source]

Blocks the user specified by either user_id or screen_name.

Parameters:
  • user_id (int, optional) – The numerical ID of the user to block.
  • screen_name (str, optional) – The screen name of the user to block.
  • include_entities (bool, optional) – The entities node will not be included if set to False.
  • skip_status (bool, optional) – When set to False, the blocked User’s statuses will not be included with the returned User object.
Returns:

A twitter.User instance representing the blocked user.

CreateFavorite(status=None, status_id=None, include_entities=True)[source]

Favorites the specified status object or id as the authenticating user.

Returns the favorite status when successful.

Parameters:
  • status_id (int, optional) – The id of the twitter status to mark as a favorite.
  • status (twitter.Status, optional) – The twitter.Status object to mark as a favorite.
  • include_entities (bool, optional) – The entities node will be omitted when set to False.
Returns:

A twitter.Status instance representing the newly-marked favorite.

CreateFriendship(user_id=None, screen_name=None, follow=True, retweets=True, **kwargs)[source]

Befriends the user specified by the user_id or screen_name.

Parameters:
  • user_id (int, optional) – A user_id to follow
  • screen_name (str, optional) – A screen_name to follow
  • follow (bool, optional) – Set to False to disable notifications for the target user
  • retweets (bool, optional) – Enable or disable retweets from the target user.
Returns:

A twitter.User instance representing the befriended user.

CreateList(name, mode=None, description=None)[source]

Creates a new list with the give name for the authenticated user.

Parameters:
  • name (str) – New name for the list
  • mode (str, optional) – ‘public’ or ‘private’. Defaults to ‘public’.
  • description (str, optional) – Description of the list.
Returns:

A twitter.List instance representing the new list

Return type:

twitter.list.List

CreateListsMember(list_id=None, slug=None, user_id=None, screen_name=None, owner_screen_name=None, owner_id=None)[source]

Add a new member (or list of members) to the specified list.

Parameters:
  • list_id (int, optional) – The numerical id of the list.
  • slug (str, optional) – 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.
  • user_id (int, optional) – The user_id or a list of user_id’s to add to the list. If not given, then screen_name is required.
  • screen_name (str, optional) – The screen_name or a list of screen_name’s to add to the list. If not given, then user_id is required.
  • owner_screen_name (str, optional) – The screen_name of the user who owns the list being requested by a slug.
  • owner_id (int, optional) – The user ID of the user who owns the list being requested by a slug.
Returns:

A twitter.List instance representing the list subscribed to.

Return type:

twitter.list.List

CreateMute(user_id=None, screen_name=None, include_entities=True, skip_status=False)[source]

Mutes the user specified by either user_id or screen_name.

Parameters:
  • user_id (int, optional) – The numerical ID of the user to mute.
  • screen_name (str, optional) – The screen name of the user to mute.
  • include_entities (bool, optional) – The entities node will not be included if set to False.
  • skip_status (bool, optional) – When set to False, the muted User’s statuses will not be included with the returned User object.
Returns:

A twitter.User instance representing the muted user.

CreateSubscription(owner_screen_name=None, owner_id=None, list_id=None, slug=None)[source]

Creates a subscription to a list by the authenticated user.

Parameters:
  • owner_screen_name (str, optional) – The screen_name of the user who owns the list being requested by a slug.
  • owner_id (int, optional) – The user ID of the user who owns the list being requested by a slug.
  • list_id (int, optional) – The numerical id of the list.
  • slug (str, optional) – 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.
Returns:

A twitter.User instance representing the user subscribed

Return type:

twitter.user.User

DEFAULT_CACHE_TIMEOUT = 60
DestroyBlock(user_id=None, screen_name=None, include_entities=True, skip_status=False)[source]

Unlocks the user specified by either user_id or screen_name.

Parameters:
  • user_id (int, optional) – The numerical ID of the user to block.
  • screen_name (str, optional) – The screen name of the user to block.
  • include_entities (bool, optional) – The entities node will not be included if set to False.
  • skip_status (bool, optional) – When set to False, the blocked User’s statuses will not be included with the returned User object.
Returns:

A twitter.User instance representing the blocked user.

DestroyDirectMessage(message_id, include_entities=True, return_json=False)[source]

Destroys the direct message specified in the required ID parameter.

The twitter.Api instance must be authenticated, and the authenticating user must be the recipient of the specified direct message.

Parameters:
  • message_id – The id of the direct message to be destroyed
  • return_json (bool, optional) – If True JSON data will be returned, instead of twitter.User
Returns:

A twitter.DirectMessage instance representing the message destroyed

DestroyFavorite(status=None, status_id=None, include_entities=True)[source]

Un-Favorites the specified status object or id as the authenticating user.

Returns the un-favorited status when successful.

Parameters:
  • status_id (int, optional) – The id of the twitter status to mark as a favorite.
  • status (twitter.Status, optional) – The twitter.Status object to mark as a favorite.
  • include_entities (bool, optional) – The entities node will be omitted when set to False.
Returns:

A twitter.Status instance representing the newly-unmarked favorite.

DestroyFriendship(user_id=None, screen_name=None)[source]

Discontinues friendship with a user_id or screen_name.

Parameters:
  • user_id – A user_id to unfollow [Optional]
  • screen_name – A screen_name to unfollow [Optional]
Returns:

A twitter.User instance representing the discontinued friend.

DestroyList(owner_screen_name=None, owner_id=None, list_id=None, slug=None)[source]

Destroys the list identified by list_id or slug and one of owner_screen_name or owner_id.

Parameters:
  • owner_screen_name (str, optional) – The screen_name of the user who owns the list being requested by a slug.
  • owner_id (int, optional) – The user ID of the user who owns the list being requested by a slug.
  • list_id (int, optional) – The numerical id of the list.
  • slug (str, optional) – 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.
Returns:

A twitter.List instance representing the removed list.

Return type:

twitter.list.List

DestroyListsMember(list_id=None, slug=None, owner_screen_name=None, owner_id=None, user_id=None, screen_name=None)[source]

Destroys the subscription to a list for the authenticated user.

Parameters:
  • list_id (int, optional) – The numerical id of the list.
  • slug (str, optional) – 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 (str, optional) – The screen_name of the user who owns the list being requested by a slug.
  • owner_id (int, optional) – The user ID of the user who owns the list being requested by a slug.
  • user_id (int, optional) – The user_id or a list of user_id’s to remove from the list. If not given, then screen_name is required.
  • screen_name (str, optional) – The screen_name or a list of Screen_name’s to remove from the list. If not given, then user_id is required.
Returns:

A twitter.List instance representing the removed list.

Return type:

twitter.list.List

DestroyMute(user_id=None, screen_name=None, include_entities=True, skip_status=False)[source]

Unlocks the user specified by either user_id or screen_name.

Parameters:
  • user_id (int, optional) – The numerical ID of the user to mute.
  • screen_name (str, optional) – The screen name of the user to mute.
  • include_entities (bool, optional) – The entities node will not be included if set to False.
  • skip_status (bool, optional) – When set to False, the muted User’s statuses will not be included with the returned User object.
Returns:

A twitter.User instance representing the muted user.

DestroyStatus(status_id, trim_user=False)[source]

Destroys the status specified by the required ID parameter.

The authenticating user must be the author of the specified status.

Parameters:
  • status_id (int) – The numerical ID of the status you’re trying to destroy.
  • trim_user (bool, optional) – When set to True, each tweet returned in a timeline will include a user object including only the status authors numerical ID.
Returns:

A twitter.Status instance representing the destroyed status message

DestroySubscription(owner_screen_name=None, owner_id=None, list_id=None, slug=None)[source]

Destroys the subscription to a list for the authenticated user.

Parameters:
  • owner_screen_name (str, optional) – The screen_name of the user who owns the list being requested by a slug.
  • owner_id (int, optional) – The user ID of the user who owns the list being requested by a slug.
  • list_id (int, optional) – The numerical id of the list.
  • slug (str, optional) – 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.
Returns:

A twitter.List instance representing the removed list.

Return type:

twitter.list.List

static GetAppOnlyAuthToken(consumer_key, consumer_secret)[source]

Generate a Bearer Token from consumer_key and consumer_secret

GetBlocks(skip_status=False, include_entities=False)[source]

Fetch the sequence of all users (as twitter.User instances), blocked by the currently authenticated user.

Parameters:
  • skip_status (bool, optional) – If True the statuses will not be returned in the user items.
  • include_entities (bool, optional) – When True, the user entities will be included.
Returns:

A list of twitter.User instances, one for each blocked user.

GetBlocksIDs(stringify_ids=False)[source]

Fetch the sequence of all user IDs blocked by the currently authenticated user.

Parameters:stringify_ids (bool, optional) – If True user IDs will be returned as strings rather than integers.
Returns:A list of user IDs for all blocked users.
GetBlocksIDsPaged(cursor=-1, stringify_ids=False)[source]

Fetch a page of the user IDs blocked by the currently authenticated user.

Parameters:
  • cursor (int, optional) – Should be set to -1 if you want the first page, thereafter denotes the page of blocked users that you want to return.
  • stringify_ids (bool, optional) – If True user IDs will be returned as strings rather than integers.
Returns:

next_cursor, previous_cursor, list of user IDs of blocked users.

GetBlocksPaged(cursor=-1, skip_status=False, include_entities=False)[source]

Fetch a page of the users (as twitter.User instances) blocked by the currently authenticated user.

Parameters:
  • cursor (int, optional) – Should be set to -1 if you want the first page, thereafter denotes the page of blocked users that you want to return.
  • skip_status (bool, optional) – If True the statuses will not be returned in the user items.
  • include_entities (bool, optional) – When True, the user entities will be included.
Returns:

next_cursor, previous_cursor, list of twitter.User instances, one for each blocked user.

GetDirectMessages(since_id=None, max_id=None, count=None, include_entities=True, skip_status=False, full_text=False, page=None, return_json=False)[source]

Returns a list of the direct messages sent to the authenticating user.

Parameters:
  • since_id – Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occurred since the since_id, the since_id will be forced to the oldest ID available. [Optional]
  • max_id – Returns results with an ID less than (that is, older than) or equal to the specified ID. [Optional]
  • count – Specifies the number of direct messages to try and retrieve, up to a maximum of 200. The value of count is best thought of as a limit to the number of Tweets to return because suspended or deleted content is removed after the count has been applied. [Optional]
  • include_entities – The entities node will be omitted when set to False. [Optional]
  • skip_status – When set to True statuses will not be included in the returned user objects. [Optional]
  • full_text – When set to True full message will be included in the returned message object if message length is bigger than CHARACTER_LIMIT characters. [Optional]
  • page – If you want more than 200 messages, you can use this and get 20 messages each time. You must recall it and increment the page value until it return nothing. You can’t use count option with it. First value is 1 and not 0.
  • return_json (bool, optional) – If True JSON data will be returned, instead of twitter.User
Returns:

A sequence of twitter.DirectMessage instances

GetFavorites(user_id=None, screen_name=None, count=None, since_id=None, max_id=None, include_entities=True, return_json=False)[source]

Return a list of Status objects representing favorited tweets.

Returns up to 200 most recent tweets for the authenticated user.

Parameters:
  • user_id (int, optional) – Specifies the ID of the user for whom to return the favorites. Helpful for disambiguating when a valid user ID is also a valid screen name.
  • screen_name (str, optional) – Specifies the screen name of the user for whom to return the favorites. Helpful for disambiguating when a valid screen name is also a user ID.
  • since_id (int, optional) – Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occurred since the since_id, the since_id will be forced to the oldest ID available.
  • max_id (int, optional) – Returns only statuses with an ID less than (that is, older than) or equal to the specified ID.
  • count (int, optional) – Specifies the number of statuses to retrieve. May not be greater than 200.
  • include_entities (bool, optional) – The entities node will be omitted when set to False.
  • return_json (bool, optional) – If True JSON data will be returned, instead of twitter.User
Returns:

A sequence of Status instances, one for each favorited tweet up to count

GetFollowerIDs(user_id=None, screen_name=None, cursor=None, stringify_ids=False, count=None, total_count=None)[source]

Returns a list of twitter user id’s for every person that is following the specified user.

Parameters:
  • user_id – The id of the user to retrieve the id list for. [Optional]
  • screen_name – The screen_name of the user to retrieve the id list for. [Optional]
  • cursor – Specifies the Twitter API Cursor location to start at. Note: there are pagination limits. [Optional]
  • stringify_ids – if True then twitter will return the ids as strings instead of integers. [Optional]
  • count – The number of user id’s to retrieve per API request. Please be aware that this might get you rate-limited if set to a small number. By default Twitter will retrieve 5000 UIDs per call. [Optional]
  • total_count – The total amount of UIDs to retrieve. Good if the account has many followers and you don’t want to get rate limited. The data returned might contain more UIDs if total_count is not a multiple of count (5000 by default). [Optional]
Returns:

A list of integers, one for each user id.

GetFollowerIDsPaged(user_id=None, screen_name=None, cursor=-1, stringify_ids=False, count=5000)[source]

Make a cursor driven call to return a list of one page followers.

The caller is responsible for handling the cursor value and looping to gather all of the data

Parameters:
  • user_id – The twitter id of the user whose followers you are fetching. If not specified, defaults to the authenticated user. [Optional]
  • screen_name – The twitter name of the user whose followers you are fetching. If not specified, defaults to the authenticated user. [Optional]
  • cursor – Should be set to -1 for the initial call and then is used to control what result page Twitter returns.
  • stringify_ids – if True then twitter will return the ids as strings instead of integers. [Optional]
  • count – The number of user id’s to retrieve per API request. Please be aware that this might get you rate-limited if set to a small number. By default Twitter will retrieve 5000 UIDs per call. [Optional]
Returns:

next_cursor, previous_cursor, data sequence of user ids, one for each follower

GetFollowers(user_id=None, screen_name=None, cursor=None, count=None, total_count=None, skip_status=False, include_user_entities=True)[source]

Fetch the sequence of twitter.User instances, one for each follower.

If both user_id and screen_name are specified, this call will return the followers of the user specified by screen_name, however this behavior is undocumented by Twitter and may change without warning.

Parameters:
  • user_id – The twitter id of the user whose followers you are fetching. If not specified, defaults to the authenticated user. [Optional]
  • screen_name – The twitter name of the user whose followers you are fetching. If not specified, defaults to the authenticated user. [Optional]
  • cursor – Should be set to -1 for the initial call and then is used to control what result page Twitter returns.
  • count – The number of users to return per page, up to a maximum of 200. Defaults to 200. [Optional]
  • total_count – The upper bound of number of users to return, defaults to None.
  • skip_status – If True the statuses will not be returned in the user items. [Optional]
  • include_user_entities – When True, the user entities will be included. [Optional]
Returns:

A sequence of twitter.User instances, one for each follower

GetFollowersPaged(user_id=None, screen_name=None, cursor=-1, count=200, skip_status=False, include_user_entities=True)[source]

Make a cursor driven call to return the list of all followers

Parameters:
  • user_id – The twitter id of the user whose followers you are fetching. If not specified, defaults to the authenticated user. [Optional]
  • screen_name – The twitter name of the user whose followers you are fetching. If not specified, defaults to the authenticated user. [Optional]
  • cursor – Should be set to -1 for the initial call and then is used to control what result page Twitter returns.
  • count – The number of users to return per page, up to a maximum of 200. Defaults to 200. [Optional]
  • skip_status – If True the statuses will not be returned in the user items. [Optional]
  • include_user_entities – When True, the user entities will be included. [Optional]
Returns:

next_cursor, previous_cursor, data sequence of twitter.User instances, one for each follower

GetFriendIDs(user_id=None, screen_name=None, cursor=None, count=None, stringify_ids=False, total_count=None)[source]

Fetch a sequence of user ids, one for each friend. Returns a list of all the given user’s friends’ IDs. If no user_id or screen_name is given, the friends will be those of the authenticated user.

Parameters:
  • user_id – The id of the user to retrieve the id list for. [Optional]
  • screen_name – The screen_name of the user to retrieve the id list for. [Optional]
  • cursor – Specifies the Twitter API Cursor location to start at. Note: there are pagination limits. [Optional]
  • stringify_ids – if True then twitter will return the ids as strings instead of integers. [Optional]
  • count – The number of user id’s to retrieve per API request. Please be aware that this might get you rate-limited if set to a small number. By default Twitter will retrieve 5000 UIDs per call. [Optional]
  • total_count – The total amount of UIDs to retrieve. Good if the account has many followers and you don’t want to get rate limited. The data returned might contain more UIDs if total_count is not a multiple of count (5000 by default). [Optional]
Returns:

A list of integers, one for each user id.

GetFriendIDsPaged(user_id=None, screen_name=None, cursor=-1, stringify_ids=False, count=5000)[source]

Make a cursor driven call to return the list of all friends

The caller is responsible for handling the cursor value and looping to gather all of the data

Parameters:
  • user_id – The twitter id of the user whose friends you are fetching. If not specified, defaults to the authenticated user. [Optional]
  • screen_name – The twitter name of the user whose friends you are fetching. If not specified, defaults to the authenticated user. [Optional]
  • cursor – Should be set to -1 for the initial call and then is used to control what result page Twitter returns.
  • stringify_ids – if True then twitter will return the ids as strings instead of integers. [Optional]
  • count – The number of user id’s to retrieve per API request. Please be aware that this might get you rate-limited if set to a small number. By default Twitter will retrieve 5000 UIDs per call. [Optional]
Returns:

next_cursor, previous_cursor, data sequence of twitter.User instances, one for each friend

GetFriends(user_id=None, screen_name=None, cursor=None, count=None, total_count=None, skip_status=False, include_user_entities=True)[source]

Fetch the sequence of twitter.User instances, one for each friend.

If both user_id and screen_name are specified, this call will return the followers of the user specified by screen_name, however this behavior is undocumented by Twitter and may change without warning.

Parameters:
  • user_id – The twitter id of the user whose friends you are fetching. If not specified, defaults to the authenticated user. [Optional]
  • screen_name – The twitter name of the user whose friends you are fetching. If not specified, defaults to the authenticated user. [Optional]
  • cursor – Should be set to -1 for the initial call and then is used to control what result page Twitter returns.
  • count – The number of users to return per page, up to a maximum of 200. Defaults to 200. [Optional]
  • total_count – The upper bound of number of users to return, defaults to None.
  • skip_status – If True the statuses will not be returned in the user items. [Optional]
  • include_user_entities – When True, the user entities will be included. [Optional]
Returns:

A sequence of twitter.User instances, one for each friend

GetFriendsPaged(user_id=None, screen_name=None, cursor=-1, count=200, skip_status=False, include_user_entities=True)[source]

Make a cursor driven call to return the list of all friends.

Parameters:
  • user_id – The twitter id of the user whose friends you are fetching. If not specified, defaults to the authenticated user. [Optional]
  • screen_name – The twitter name of the user whose friends you are fetching. If not specified, defaults to the authenticated user. [Optional]
  • cursor – Should be set to -1 for the initial call and then is used to control what result page Twitter returns.
  • count – The number of users to return per page, up to a current maximum of 200. Defaults to 200. [Optional]
  • skip_status – If True the statuses will not be returned in the user items. [Optional]
  • include_user_entities – When True, the user entities will be included. [Optional]
Returns:

next_cursor, previous_cursor, data sequence of twitter.User instances, one for each follower

GetHelpConfiguration()[source]

Get basic help configuration details from Twitter.

Parameters:None
Returns:Sets self._config and returns dict of help config values.
Return type:dict
GetHomeTimeline(count=None, since_id=None, max_id=None, trim_user=False, exclude_replies=False, contributor_details=False, include_entities=True)[source]

Fetch a collection of the most recent Tweets and retweets posted by the authenticating user and the users they follow.

The home timeline is central to how most users interact with Twitter.

Parameters:
  • count – Specifies the number of statuses to retrieve. May not be greater than 200. Defaults to 20. [Optional]
  • since_id – Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occurred since the since_id, the since_id will be forced to the oldest ID available. [Optional]
  • max_id – Returns results with an ID less than (that is, older than) or equal to the specified ID. [Optional]
  • trim_user – When True, each tweet returned in a timeline will include a user object including only the status authors numerical ID. Omit this parameter to receive the complete user object. [Optional]
  • exclude_replies – This parameter will prevent replies from appearing in the returned timeline. Using exclude_replies with the count parameter will mean you will receive up-to count tweets - this is because the count parameter retrieves that many tweets before filtering out retweets and replies. [Optional]
  • contributor_details – This parameter enhances the contributors element of the status response to include the screen_name of the contributor. By default only the user_id of the contributor is included. [Optional]
  • include_entities – The entities node will be disincluded when set to false. This node offers a variety of metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags. [Optional]
Returns:

A sequence of twitter.Status instances, one for each message

GetListMembers(list_id=None, slug=None, owner_id=None, owner_screen_name=None, skip_status=False, include_entities=False)[source]

Fetch the sequence of twitter.User instances, one for each member of the given list_id or slug.

Parameters:
  • list_id (int, optional) – Specifies the ID of the list to retrieve.
  • slug (str, optional) – The slug name for the list to retrieve. If you specify None for the list_id, then you have to provide either a owner_screen_name or owner_id.
  • owner_id (int, optional) – Specifies the ID of the user for whom to return the list timeline. Helpful for disambiguating when a valid user ID is also a valid screen name.
  • owner_screen_name (str, optional) – Specifies the screen name of the user for whom to return the user_timeline. Helpful for disambiguating when a valid screen name is also a user ID.
  • skip_status (bool, optional) – If True the statuses will not be returned in the user items.
  • include_entities (bool, optional) – If False, the timeline will not contain additional metadata. Defaults to True.
Returns:

A sequence of twitter.user.User instances, one for each member of the twitter.list.List.

Return type:

list

GetListMembersPaged(list_id=None, slug=None, owner_id=None, owner_screen_name=None, cursor=-1, count=100, skip_status=False, include_entities=True)[source]

Fetch the sequence of twitter.User instances, one for each member of the given list_id or slug.

Parameters:
  • list_id (int, optional) – Specifies the ID of the list to retrieve.
  • slug (str, optional) – The slug name for the list to retrieve. If you specify None for the list_id, then you have to provide either a owner_screen_name or owner_id.
  • owner_id (int, optional) – Specifies the ID of the user for whom to return the list timeline. Helpful for disambiguating when a valid user ID is also a valid screen name.
  • owner_screen_name (str, optional) – Specifies the screen name of the user for whom to return the user_timeline. Helpful for disambiguating when a valid screen name is also a user ID.
  • cursor (int, optional) – Should be set to -1 for the initial call and then is used to control what result page Twitter returns.
  • skip_status (bool, optional) – If True the statuses will not be returned in the user items.
  • include_entities (bool, optional) – If False, the timeline will not contain additional metadata. Defaults to True.
Returns:

A sequence of twitter.user.User instances, one for each member of the twitter.list.List.

Return type:

list

GetListTimeline(list_id=None, slug=None, owner_id=None, owner_screen_name=None, since_id=None, max_id=None, count=None, include_rts=True, include_entities=True, return_json=False)[source]

Fetch the sequence of Status messages for a given List ID.

Parameters:
  • list_id (int, optional) – Specifies the ID of the list to retrieve.
  • slug (str, optional) – The slug name for the list to retrieve. If you specify None for the list_id, then you have to provide either a owner_screen_name or owner_id.
  • owner_id (int, optional) – Specifies the ID of the user for whom to return the list timeline. Helpful for disambiguating when a valid user ID is also a valid screen name.
  • owner_screen_name (str, optional) – Specifies the screen name of the user for whom to return the user_timeline. Helpful for disambiguating when a valid screen name is also a user ID.
  • since_id (int, optional) – Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occurred since the since_id, the since_id will be forced to the oldest ID available.
  • max_id (int, optional) – Returns only statuses with an ID less than (that is, older than) or equal to the specified ID.
  • count (int, optional) – Specifies the number of statuses to retrieve. May not be greater than 200.
  • include_rts (bool, optional) – If True, the timeline will contain native retweets (if they exist) in addition to the standard stream of tweets.
  • include_entities (bool, optional) – If False, the timeline will not contain additional metadata. Defaults to True.
  • return_json (bool, optional) – If True JSON data will be returned, instead of twitter.User
Returns:

A list of twitter.status.Status instances, one for each message up to count.

Return type:

list

GetLists(user_id=None, screen_name=None)[source]

Fetch the sequence of lists for a user. If no user_id or screen_name is passed, the data returned will be for the authenticated user.

Parameters:
  • user_id – The ID of the user for whom to return results for. [Optional]
  • screen_name – The screen name of the user for whom to return results for. [Optional]
  • count – The amount of results to return per page. No more than 1000 results will ever be returned in a single page. Defaults to 20. [Optional]
  • cursor – The “page” value that Twitter will use to start building the list sequence from. Use the value of -1 to start at the beginning. Twitter will return in the result the values for next_cursor and previous_cursor. [Optional]
Returns:

A sequence of twitter.List instances, one for each list

GetListsList(screen_name=None, user_id=None, reverse=False, return_json=False)[source]

Returns all lists the user subscribes to, including their own. If no user_id or screen_name is specified, the data returned will be for the authenticated user.

Parameters:
  • screen_name (str, optional) – Specifies the screen name of the user for whom to return the user_timeline. Helpful for disambiguating when a valid screen name is also a user ID.
  • user_id (int, optional) – Specifies the ID of the user for whom to return the user_timeline. Helpful for disambiguating when a valid user ID is also a valid screen name.
  • reverse (bool, optional) – If False, the owned lists will be returned first, othewise subscribed lists will be at the top. Returns a maximum of 100 entries regardless. Defaults to False.
  • return_json (bool, optional) – If True JSON data will be returned, instead of twitter.User
Returns:

A sequence of twitter.List instances.

Return type:

list

GetListsPaged(user_id=None, screen_name=None, cursor=-1, count=20)[source]

Fetch the sequence of lists for a user. If no user_id or screen_name is passed, the data returned will be for the authenticated user.

Parameters:
  • user_id (int, optional) – The ID of the user for whom to return results for.
  • screen_name (str, optional) – The screen name of the user for whom to return results for.
  • count (int, optional) – The amount of results to return per page. No more than 1000 results will ever be returned in a single page. Defaults to 20.
  • cursor (int, optional) – The “page” value that Twitter will use to start building the list sequence from. Use the value of -1 to start at the beginning. Twitter will return in the result the values for next_cursor and previous_cursor.
Returns:

next_cursor (int), previous_cursor (int), list of twitter.List instances, one for each list

GetMemberships(user_id=None, screen_name=None, count=20, cursor=-1, filter_to_owned_lists=False, return_json=False)[source]

Obtain the lists the specified user is a member of. If no user_id or screen_name is specified, the data returned will be for the authenticated user.

Returns a maximum of 20 lists per page by default.

Parameters:
  • user_id (int, optional) – The ID of the user for whom to return results for.
  • screen_name (str, optional) – The screen name of the user for whom to return results for.
  • count (int, optional) – The amount of results to return per page. No more than 1000 results will ever be returned in a single page. Defaults to 20.
  • cursor (int, optional) – The “page” value that Twitter will use to start building the list sequence from. Use the value of -1 to start at the beginning. Twitter will return in the result the values for next_cursor and previous_cursor.
  • filter_to_owned_lists (bool, optional) – Set to True to return only the lists the authenticating user owns, and the user specified by user_id or screen_name is a member of. Default value is False.
  • return_json (bool, optional) – If True JSON data will be returned, instead of twitter.User
Returns:

A list of twitter.List instances, one for each list in which the user specified by user_id or screen_name is a member

Return type:

list

GetMentions(count=None, since_id=None, max_id=None, trim_user=False, contributor_details=False, include_entities=True, return_json=False)[source]

Returns the 20 most recent mentions (status containing @screen_name) for the authenticating user.

Parameters:
  • count – Specifies the number of tweets to try and retrieve, up to a maximum of 200. The value of count is best thought of as a limit to the number of tweets to return because suspended or deleted content is removed after the count has been applied. [Optional]
  • since_id – Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occurred since the since_id, the since_id will be forced to the oldest ID available. [Optional]
  • max_id – Returns only statuses with an ID less than (that is, older than) the specified ID. [Optional]
  • trim_user – When set to True, each tweet returned in a timeline will include a user object including only the status authors numerical ID. Omit this parameter to receive the complete user object. [Optional]
  • contributor_details – If set to True, this parameter enhances the contributors element of the status response to include the screen_name of the contributor. By default only the user_id of the contributor is included. [Optional]
  • include_entities – The entities node will be disincluded when set to False. [Optional]
  • return_json (bool, optional) – If True JSON data will be returned, instead of twitter.User
Returns:

A sequence of twitter.Status instances, one for each mention of the user.

GetMutes(skip_status=False, include_entities=False)[source]

Fetch the sequence of all users (as twitter.User instances), muted by the currently authenticated user.

Parameters:
  • skip_status (bool, optional) – If True the statuses will not be returned in the user items.
  • include_entities (bool, optional) – When True, the user entities will be included.
Returns:

A list of twitter.User instances, one for each muted user.

GetMutesIDs(stringify_ids=False)[source]

Fetch the sequence of all user IDs muted by the currently authenticated user.

Parameters:stringify_ids (bool, optional) – If True user IDs will be returned as strings rather than integers.
Returns:A list of user IDs for all muted users.
GetMutesIDsPaged(cursor=-1, stringify_ids=False)[source]

Fetch a page of the user IDs muted by the currently authenticated user.

Parameters:
  • cursor (int, optional) – Should be set to -1 if you want the first page, thereafter denotes the page of muted users that you want to return.
  • stringify_ids (bool, optional) – If True user IDs will be returned as strings rather than integers.
Returns:

next_cursor, previous_cursor, list of user IDs of muted users.

GetMutesPaged(cursor=-1, skip_status=False, include_entities=False)[source]

Fetch a page of the users (as twitter.User instances) muted by the currently authenticated user.

Parameters:
  • cursor (int, optional) – Should be set to -1 if you want the first page, thereafter denotes the page of muted users that you want to return.
  • skip_status (bool, optional) – If True the statuses will not be returned in the user items.
  • include_entities (bool, optional) – When True, the user entities will be included.
Returns:

next_cursor, previous_cursor, list of twitter.User instances, one for each muted user.

GetReplies(since_id=None, count=None, max_id=None, trim_user=False)[source]

Get a sequence of status messages representing the 20 most recent replies (status updates prefixed with @twitterID) to the authenticating user.

Parameters:
  • since_id – Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occurred since the since_id, the since_id will be forced to the oldest ID available. [Optional]
  • max_id – Returns results with an ID less than (that is, older than) or equal to the specified ID. [Optional]
  • trim_user – If True the returned payload will only contain the user IDs, otherwise the payload will contain the full user data item. [Optional]
Returns:

A sequence of twitter.Status instances, one for each reply to the user.

GetRetweeters(status_id, cursor=None, count=100, stringify_ids=False)[source]

Returns a collection of up to 100 user IDs belonging to users who have retweeted the tweet specified by the status_id parameter.

Parameters:
  • status_id – the tweet’s numerical ID
  • cursor – breaks the ids into pages of no more than 100.
  • stringify_ids – returns the IDs as unicode strings. [Optional]
Returns:

A list of user IDs

GetRetweets(statusid, count=None, trim_user=False)[source]

Returns up to 100 of the first retweets of the tweet identified by statusid

Parameters:
  • statusid (int) – The ID of the tweet for which retweets should be searched for
  • count (int, optional) – The number of status messages to retrieve.
  • trim_user (bool, optional) – If True the returned payload will only contain the user IDs, otherwise the payload will contain the full user data item.
Returns:

A list of twitter.Status instances, which are retweets of statusid

GetRetweetsOfMe(count=None, since_id=None, max_id=None, trim_user=False, include_entities=True, include_user_entities=True)[source]

Returns up to 100 of the most recent tweets of the user that have been retweeted by others.

Parameters:
  • count – The number of retweets to retrieve, up to 100. Defaults to 20. [Optional]
  • since_id – Returns results with an ID greater than (newer than) this ID. [Optional]
  • max_id – Returns results with an ID less than or equal to this ID. [Optional]
  • trim_user – When True, the user object for each tweet will only be an ID. [Optional]
  • include_entities – When True, the tweet entities will be included. [Optional]
  • include_user_entities – When True, the user entities will be included. [Optional]
GetSearch(term=None, raw_query=None, geocode=None, since_id=None, max_id=None, until=None, since=None, count=15, lang=None, locale=None, result_type='mixed', include_entities=None, return_json=False)[source]

Return twitter search results for a given term. You must specify one of term, geocode, or raw_query.

Parameters:
  • term (str, optional) – Term to search by. Optional if you include geocode.
  • raw_query (str, optional) – A raw query as a string. This should be everything after the “?” in the URL (i.e., the query parameters). You are responsible for all type checking and ensuring that the query string is properly formatted, as it will only be URL-encoded before be passed directly to Twitter with no other checks performed. For advanced usage only. This will override any other parameters passed
  • since_id (int, optional) – Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occurred since the since_id, the since_id will be forced to the oldest ID available.
  • max_id (int, optional) – Returns only statuses with an ID less than (that is, older than) or equal to the specified ID.
  • until (str, optional) – Returns tweets generated before the given date. Date should be formatted as YYYY-MM-DD.
  • since (str, optional) – Returns tweets generated since the given date. Date should be formatted as YYYY-MM-DD.
  • geocode (str or list or tuple, optional) –

    Geolocation within which to search for tweets. Can be either a string in the form of “latitude,longitude,radius” where latitude and longitude are floats and radius is a string such as “1mi” or “1km” (“mi” or “km” are the only units allowed). For example:

    >>> api.GetSearch(geocode="37.781157,-122.398720,1mi").
    

    Otherwise, you can pass a list of either floats or strings for lat/long and a string for radius:

    >>> api.GetSearch(geocode=[37.781157, -122.398720, "1mi"])
    >>> # or:
    >>> api.GetSearch(geocode=(37.781157, -122.398720, "1mi"))
    >>> # or:
    >>> api.GetSearch(geocode=("37.781157", "-122.398720", "1mi"))
    
  • count (int, optional) – Number of results to return. Default is 15 and maxmimum that Twitter returns is 100 irrespective of what you type in.
  • lang (str, optional) – Language for results as ISO 639-1 code. Default is None (all languages).
  • locale (str, optional) – Language of the search query. Currently only ‘ja’ is effective. This is intended for language-specific consumers and the default should work in the majority of cases.
  • result_type (str, optional) – Type of result which should be returned. Default is “mixed”. Valid options are “mixed, “recent”, and “popular”.
  • include_entities (bool, optional) – If True, each tweet will include a node called “entities”. This node offers a variety of metadata about the tweet in a discrete structure, including: user_mentions, urls, and hashtags.
  • return_json (bool, optional) – If True JSON data will be returned, instead of twitter.Userret
Returns:

A sequence of twitter.Status instances, one for each message containing the term, within the bounds of the geocoded area, or given by the raw_query.

Return type:

list

GetSentDirectMessages(since_id=None, max_id=None, count=None, page=None, include_entities=True, return_json=False)[source]

Returns a list of the direct messages sent by the authenticating user.

Parameters:
  • since_id (int, optional) – Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occured since the since_id, the since_id will be forced to the oldest ID available.
  • max_id (int, optional) – Returns results with an ID less than (that is, older than) or equal to the specified ID.
  • count (int, optional) – Specifies the number of direct messages to try and retrieve, up to a maximum of 200. The value of count is best thought of as a limit to the number of Tweets to return because suspended or deleted content is removed after the count has been applied.
  • page (int, optional) – Specifies the page of results to retrieve. Note: there are pagination limits. [Optional]
  • include_entities (bool, optional) – The entities node will be omitted when set to False.
  • return_json (bool, optional) – If True JSON data will be returned, instead of twitter.User
Returns:

A sequence of twitter.DirectMessage instances

GetShortUrlLength(https=False)[source]

Returns number of characters reserved per URL included in a tweet.

Parameters:https (bool, optional) – If True, return number of characters reserved for https urls or, if False, return number of character reserved for http urls.
Returns:Number of characters reserved per URL.
Return type:(int)
GetStatus(status_id, trim_user=False, include_my_retweet=True, include_entities=True, include_ext_alt_text=True)[source]

Returns a single status message, specified by the status_id parameter.

Parameters:
  • status_id – The numeric ID of the status you are trying to retrieve.
  • trim_user – When set to True, each tweet returned in a timeline will include a user object including only the status authors numerical ID. Omit this parameter to receive the complete user object. [Optional]
  • include_my_retweet – When set to True, any Tweets returned that have been retweeted by the authenticating user will include an additional current_user_retweet node, containing the ID of the source status for the retweet. [Optional]
  • include_entities – If False, the entities node will be disincluded. This node offers a variety of metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags. [Optional]
Returns:

A twitter.Status instance representing that status message

GetStatusOembed(status_id=None, url=None, maxwidth=None, hide_media=False, hide_thread=False, omit_script=False, align=None, related=None, lang=None)[source]

Returns information allowing the creation of an embedded representation of a Tweet on third party sites.

Specify tweet by the id or url parameter.

Parameters:
  • status_id – The numeric ID of the status you are trying to embed.
  • url – The url of the status you are trying to embed.
  • maxwidth – The maximum width in pixels that the embed should be rendered at. This value is constrained to be between 250 and 550 pixels. [Optional]
  • hide_media – Specifies whether the embedded Tweet should automatically expand images. [Optional]
  • hide_thread – Specifies whether the embedded Tweet should automatically show the original message in the case that the embedded Tweet is a reply. [Optional]
  • omit_script – Specifies whether the embedded Tweet HTML should include a <script> element pointing to widgets.js. [Optional]
  • align – Specifies whether the embedded Tweet should be left aligned, right aligned, or centered in the page. [Optional]
  • related – A comma sperated string of related screen names. [Optional]
  • lang – Language code for the rendered embed. [Optional]
Returns:

A dictionary with the response.

GetStatuses(status_ids, trim_user=False, include_entities=True, map=False)[source]

Returns a list of status messages, specified by the status_ids parameter.

Parameters:
  • status_ids – A list of the numeric ID of the statuses you are trying to retrieve.
  • trim_user – When set to True, each tweet returned in a timeline will include a user object including only the status authors numerical ID. Omit this parameter to receive the complete user object. [Optional]
  • include_entities – If False, the entities node will be disincluded. This node offers a variety of metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags. [Optional]
  • map – If True, returns a dictionary with status id as key and returned status data (or None if tweet does not exist or is inaccessible) as value. Otherwise returns an unordered list of successfully retrieved Tweets. [Optional]
Returns:

A dictionary or unordered list (depending on the parameter ‘map’) of twitter Status instances representing the status messages.

GetStreamFilter(follow=None, track=None, locations=None, languages=None, delimited=None, stall_warnings=None, filter_level=None)[source]

Returns a filtered view of public statuses.

Parameters:
  • follow – A list of user IDs to track. [Optional]
  • track – A list of expressions to track. [Optional]
  • locations – A list of Longitude,Latitude pairs (as strings) specifying bounding boxes for the tweets’ origin. [Optional]
  • delimited – Specifies a message length. [Optional]
  • stall_warnings – Set to True to have Twitter deliver stall warnings. [Optional]
  • languages – A list of Languages. Will only return Tweets that have been detected as being written in the specified languages. [Optional]
  • filter_level – Specifies level of filtering applied to stream. Set to None, ‘low’ or ‘medium’. [Optional]
Returns:

A twitter stream

GetStreamSample(delimited=False, stall_warnings=True)[source]

Returns a small sample of public statuses.

Parameters:
  • delimited – Specifies a message length. [Optional]
  • stall_warnings – Set to True to have Twitter deliver stall warnings. [Optional]
Returns:

A Twitter stream

GetSubscriptions(user_id=None, screen_name=None, count=20, cursor=-1, return_json=False)[source]

Obtain a collection of the lists the specified user is subscribed to. If neither user_id or screen_name is specified, the data returned will be for the authenticated user.

The list will contain a maximum of 20 lists per page by default.

Does not include the user’s own lists.

Parameters:
  • user_id (int, optional) – The ID of the user for whom to return results for.
  • screen_name (str, optional) – The screen name of the user for whom to return results for.
  • count (int, optional) – The amount of results to return per page. No more than 1000 results will ever be returned in a single page. Defaults to 20.
  • cursor (int, optional) – The “page” value that Twitter will use to start building the list sequence from. Use the value of -1 to start at the beginning. Twitter will return in the result the values for next_cursor and previous_cursor.
  • return_json (bool, optional) – If True JSON data will be returned, instead of twitter.User
Returns:

A sequence of twitter.List instances, one for each list

Return type:

twitter.list.List

GetTrendsCurrent(exclude=None)[source]

Get the current top trending topics (global)

Parameters:exclude – Appends the exclude parameter as a request parameter. Currently only exclude=hashtags is supported. [Optional]
Returns:A list with 10 entries. Each entry contains a trend.
GetTrendsWoeid(woeid, exclude=None)[source]

Return the top 10 trending topics for a specific WOEID, if trending information is available for it.

Parameters:
  • woeid – the Yahoo! Where On Earth ID for a location.
  • exclude – Appends the exclude parameter as a request parameter. Currently only exclude=hashtags is supported. [Optional]
Returns:

A list with 10 entries. Each entry contains a trend.

GetUser(user_id=None, screen_name=None, include_entities=True, return_json=False)[source]

Returns a single user.

Parameters:
  • user_id (int, optional) – The id of the user to retrieve.
  • screen_name (str, optional) – The screen name of the user for whom to return results for. Either a user_id or screen_name is required for this method.
  • include_entities (bool, optional) – The entities node will be omitted when set to False.
  • return_json (bool, optional) – If True JSON data will be returned, instead of twitter.User
Returns:

A twitter.User instance representing that user

GetUserRetweets(count=None, since_id=None, max_id=None, trim_user=False)[source]

Fetch the sequence of retweets made by the authenticated user.

Parameters:
  • count – The number of status messages to retrieve. [Optional]
  • since_id – Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occurred since the since_id, the since_id will be forced to the oldest ID available. [Optional]
  • max_id – Returns results with an ID less than (that is, older than) or equal to the specified ID. [Optional]
  • trim_user – If True the returned payload will only contain the user IDs, otherwise the payload will contain the full user data item. [Optional]
Returns:

A sequence of twitter.Status instances, one for each message up to count

GetUserStream(replies='all', withuser='user', track=None, locations=None, delimited=None, stall_warnings=None, stringify_friend_ids=False, filter_level=None, session=None, include_keepalive=False)[source]

Returns the data from the user stream.

Parameters:
  • replies – Specifies whether to return additional @replies in the stream. Defaults to ‘all’.
  • withuser – Specifies whether to return information for just the authenticating user, or include messages from accounts the user follows. [Optional]
  • track – A list of expressions to track. [Optional]
  • locations – A list of Latitude,Longitude pairs (as strings) specifying bounding boxes for the tweets’ origin. [Optional]
  • delimited – Specifies a message length. [Optional]
  • stall_warnings – Set to True to have Twitter deliver stall warnings. [Optional]
  • stringify_friend_ids – Specifies whether to send the friends list preamble as an array of integers or an array of strings. [Optional]
  • filter_level – Specifies level of filtering applied to stream. Set to None, low or medium. [Optional]
Returns:

A twitter stream

GetUserSuggestion(category)[source]

Returns a list of users in a category :param category: The Category object to limit the search by

Returns:A list of users in that category
GetUserSuggestionCategories()[source]
Return the list of suggested user categories, this can be used in
GetUserSuggestion function
Returns:A list of categories
GetUserTimeline(user_id=None, screen_name=None, since_id=None, max_id=None, count=None, include_rts=True, trim_user=False, exclude_replies=False)[source]

Fetch the sequence of public Status messages for a single user.

The twitter.Api instance must be authenticated if the user is private.

Parameters:
  • user_id (int, optional) – Specifies the ID of the user for whom to return the user_timeline. Helpful for disambiguating when a valid user ID is also a valid screen name.
  • screen_name (str, optional) – Specifies the screen name of the user for whom to return the user_timeline. Helpful for disambiguating when a valid screen name is also a user ID.
  • since_id (int, optional) – Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occurred since the since_id, the since_id will be forced to the oldest ID available.
  • max_id (int, optional) – Returns only statuses with an ID less than (that is, older than) or equal to the specified ID.
  • count (int, optional) – Specifies the number of statuses to retrieve. May not be greater than 200.
  • include_rts (bool, optional) – If True, the timeline will contain native retweets (if they exist) in addition to the standard stream of tweets.
  • trim_user (bool, optional) – If True, statuses will only contain the numerical user ID only. Otherwise a full user object will be returned for each status.
  • exclude_replies (bool, optional) – If True, this will prevent replies from appearing in the returned timeline. Using exclude_replies with the count parameter will mean you will receive up-to count tweets - this is because the count parameter retrieves that many tweets before filtering out retweets and replies. This parameter is only supported for JSON and XML responses.
Returns:

A sequence of Status instances, one for each message up to count

GetUsersSearch(term=None, page=1, count=20, include_entities=None)[source]

Return twitter user search results for a given term.

Parameters:
  • term – Term to search by.
  • page – Page of results to return. Default is 1 [Optional]
  • count – Number of results to return. Default is 20 [Optional]
  • include_entities – If True, each tweet will include a node called “entities,”. This node offers a variety of metadata about the tweet in a discrete structure, including: user_mentions, urls, and hashtags. [Optional]
Returns:

A sequence of twitter.User instances, one for each message containing the term

IncomingFriendship(cursor=None, stringify_ids=None)[source]

Returns a collection of user IDs belonging to users who have pending request to follow the authenticated user.

Parameters:
  • cursor – breaks the ids into pages of no more than 5000.
  • stringify_ids – returns the IDs as unicode strings. [Optional]
Returns:

A list of user IDs

InitializeRateLimit()[source]

Make a call to the Twitter API to get the rate limit status for the currently authenticated user or application.

Returns:None.
LookupFriendship(user_id=None, screen_name=None, return_json=False)[source]

Lookup friendship status for user to authed user.

Users may be specified either as lists of either user_ids, screen_names, or twitter.User objects. The list of users that are queried is the union of all specified parameters.

Up to 100 users may be specified.

Parameters:
  • user_id (int, User, or list of ints or Users, optional) – A list of user_ids to retrieve extended information.
  • screen_name (string, User, or list of strings or Users, optional) – A list of screen_names to retrieve extended information.
  • return_json (bool, optional) – If True JSON data will be returned, instead of twitter.User
Returns:

A list of twitter.UserStatus instance representing the friendship status between the specified users and the authenticated user.

Return type:

list

OutgoingFriendship(cursor=None, stringify_ids=None)[source]

Returns a collection of user IDs for every protected user for whom the authenticated user has a pending follow request.

Parameters:
  • cursor – breaks the ids into pages of no more than 5000.
  • stringify_ids – returns the IDs as unicode strings. [Optional]
Returns:

A list of user IDs

PostDirectMessage(text, user_id=None, screen_name=None, return_json=False)[source]

Post a twitter direct message from the authenticated user.

Parameters:
  • text – The message text to be posted.
  • user_id – The ID of the user who should receive the direct message.
  • return_json (bool, optional) – If True JSON data will be returned, instead of twitter.DirectMessage
Returns:

A twitter.DirectMessage instance representing the message posted

PostMediaMetadata(media_id, alt_text=None)[source]

Provide addtional data for uploaded media.

Parameters:
  • media_id – ID of a previously uploaded media item.
  • alt_text – Image Alternate Text.
PostRetweet(status_id, trim_user=False)[source]

Retweet a tweet with the Retweet API.

Parameters:
  • status_id – The numerical id of the tweet that will be retweeted
  • trim_user – If True the returned payload will only contain the user IDs, otherwise the payload will contain the full user data item. [Optional]
Returns:

A twitter.Status instance representing the original tweet with retweet details embedded.

PostUpdate(status, media=None, media_additional_owners=None, media_category=None, in_reply_to_status_id=None, auto_populate_reply_metadata=False, exclude_reply_user_ids=None, latitude=None, longitude=None, place_id=None, display_coordinates=False, trim_user=False, verify_status_length=True, attachment_url=None)[source]

Post a twitter status message from the authenticated user.

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

Parameters:
  • status (str) – The message text to be posted. Must be less than or equal to CHARACTER_LIMIT characters.
  • media (int, str, fp, optional) – A URL, a local file, or a file-like object (something with a read() method), or a list of any combination of the above.
  • media_additional_owners (list, optional) – A list of user ids representing Twitter users that should be able to use the uploaded media in their tweets. If you pass a list of media, then additional_owners will apply to each object. If you need more granular control, please use the UploadMedia* methods.
  • media_category (str, optional) – Only for use with the AdsAPI. See https://dev.twitter.com/ads/creative/promoted-video-overview if this applies to your application.
  • in_reply_to_status_id (int, optional) – The ID of an existing status that the status to be posted is in reply to. This implicitly sets the in_reply_to_user_id attribute of the resulting status to the user ID of the message being replied to. Invalid/missing status IDs will be ignored.
  • auto_populate_reply_metadata (bool, optional) – Automatically include the @usernames of the users mentioned or participating in the tweet to which this tweet is in reply.
  • exclude_reply_user_ids (list, optional) – Remove given user_ids (not @usernames) from the tweet’s automatically generated reply metadata.
  • attachment_url (str, optional) – URL to an attachment resource: one to four photos, a GIF, video, Quote Tweet, or DM deep link. If not specified and media parameter is not None, we will attach the first media object as the attachment URL. If a bad URL is passed, Twitter will raise an error.
  • latitude (float, optional) – Latitude coordinate of the tweet in degrees. Will only work in conjunction with longitude argument. Both longitude and latitude will be ignored by twitter if the user has a false geo_enabled setting.
  • longitude (float, optional) – Longitude coordinate of the tweet in degrees. Will only work in conjunction with latitude argument. Both longitude and latitude will be ignored by twitter if the user has a false geo_enabled setting.
  • place_id (int, optional) – A place in the world. These IDs can be retrieved from GET geo/reverse_geocode.
  • display_coordinates (bool, optional) – Whether or not to put a pin on the exact coordinates a tweet has been sent from.
  • trim_user (bool, optional) – If True the returned payload will only contain the user IDs, otherwise the payload will contain the full user data item.
  • verify_status_length (bool, optional) – If True, api throws a hard error that the status is over CHARACTER_LIMIT characters. If False, Api will attempt to post the status.
Returns:

(twitter.Status) A twitter.Status instance representing the message posted.

PostUpdates(status, continuation=None, **kwargs)[source]

Post one or more twitter status messages from the authenticated user.

Unlike api.PostUpdate, this method will post multiple status updates if the message is longer than CHARACTER_LIMIT characters.

Parameters:
  • status – The message text to be posted. May be longer than CHARACTER_LIMIT characters.
  • continuation – The character string, if any, to be appended to all but the last message. Note that Twitter strips trailing ‘…’ strings from messages. Consider using the unicode u2026 character (horizontal ellipsis) instead. [Defaults to None]
  • **kwargs – See api.PostUpdate for a list of accepted parameters.
Returns:

A of list twitter.Status instance representing the messages posted.

SetCache(cache)[source]

Override the default cache. Set to None to prevent caching.

Parameters:cache – An instance that supports the same API as the twitter._FileCache
SetCacheTimeout(cache_timeout)[source]

Override the default cache timeout.

Parameters:cache_timeout – Time, in seconds, that responses should be reused.
SetCredentials(consumer_key, consumer_secret, access_token_key=None, access_token_secret=None, application_only_auth=False)[source]

Set the consumer_key and consumer_secret for this instance

Parameters:
  • consumer_key – The consumer_key of the twitter account.
  • consumer_secret – The consumer_secret for the twitter account.
  • access_token_key – The oAuth access token key value you retrieved from running get_access_token.py.
  • access_token_secret – The oAuth access token’s secret, also retrieved from the get_access_token.py run.
  • application_only_auth – Whether to generate a bearer token and use Application-Only Auth
SetSource(source)[source]

Suggest the “from source” value to be displayed on the Twitter web site.

The value of the ‘source’ parameter must be first recognized by the Twitter server.

New source values are authorized on a case by case basis by the Twitter development team.

Parameters:source – The source name as a string. Will be sent to the server as the ‘source’ parameter.
SetUrllib(urllib)[source]

Override the default urllib implementation.

Parameters:urllib – An instance that supports the same API as the urllib2 module
SetUserAgent(user_agent)[source]

Override the default user agent.

Parameters:user_agent – A string that should be send to the server as the user-agent.
SetXTwitterHeaders(client, url, version)[source]

Set the X-Twitter HTTP headers that will be sent to the server.

Parameters:
  • client – The client name as a string. Will be sent to the server as the ‘X-Twitter-Client’ header.
  • url – The URL of the meta.xml as a string. Will be sent to the server as the ‘X-Twitter-Client-URL’ header.
  • version – The client version as a string. Will be sent to the server as the ‘X-Twitter-Client-Version’ header.
ShowFriendship(source_user_id=None, source_screen_name=None, target_user_id=None, target_screen_name=None)[source]

Returns information about the relationship between the two users.

Parameters:
  • source_id – The user_id of the subject user [Optional]
  • source_screen_name – The screen_name of the subject user [Optional]
  • target_id – The user_id of the target user [Optional]
  • target_screen_name – The screen_name of the target user [Optional]
Returns:

A Twitter Json structure.

ShowSubscription(owner_screen_name=None, owner_id=None, list_id=None, slug=None, user_id=None, screen_name=None, include_entities=False, skip_status=False, return_json=False)[source]

Check if the specified user is a subscriber of the specified list.

Returns the user if they are subscriber.

Parameters:
  • owner_screen_name (str, optional) – The screen_name of the user who owns the list being requested by a slug.
  • owner_id (int, optional) – The user ID of the user who owns the list being requested by a slug.
  • list_id (int, optional) – The numerical ID of the list.
  • slug (str, optional) – 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.
  • user_id (int, optional) – The user_id or a list of user_id’s to add to the list. If not given, then screen_name is required.
  • screen_name (str, optional) – The screen_name or a list of screen_name’s to add to the list. If not given, then user_id is required.
  • include_entities (bool, optional) – If False, the timeline will not contain additional metadata. Defaults to True.
  • skip_status (bool, optional) – If True the statuses will not be returned in the user items.
  • return_json (bool, optional) – If True JSON data will be returned, instead of twitter.User
Returns:

A twitter.User instance representing the user requested.

Return type:

twitter.user.User

UpdateBanner(image, include_entities=False, skip_status=False)[source]

Updates the authenticated users profile banner.

Parameters:
  • image – Location of image in file system
  • include_entities – If True, each tweet will include a node called “entities.” This node offers a variety of metadata about the tweet in a discrete structure, including: user_mentions, urls, and hashtags. [Optional]
Returns:

A twitter.List instance representing the list subscribed to

UpdateFriendship(user_id=None, screen_name=None, follow=True, retweets=True, **kwargs)[source]

Updates a friendship with the user specified by the user_id or screen_name.

Parameters:
  • user_id (int, optional) – A user_id to update
  • screen_name (str, optional) – A screen_name to update
  • follow (bool, optional) – Set to False to disable notifications for the target user
  • retweets (bool, optional) – Enable or disable retweets from the target user.
  • device – Set to False to disable notifications for the target user
Returns:

A twitter.User instance representing the befriended user.

UpdateImage(image, include_entities=False, skip_status=False)[source]

Update a User’s profile image. Change may not be immediately reflected due to image processing on Twitter’s side.

Parameters:
  • image (str) – Location of local image file to use.
  • include_entities (bool, optional) – Include the entities node in the return data.
  • skip_status (bool, optional) – Include the User’s last Status in the User entity returned.
Returns:

Updated User object.

Return type:

(twitter.models.User)

UpdateProfile(name=None, profileURL=None, location=None, description=None, profile_link_color=None, include_entities=False, skip_status=False)[source]

Update’s the authenticated user’s profile data.

Parameters:
  • name (str, optional) – Full name associated with the profile.
  • profileURL (str, optional) – URL associated with the profile. Will be prepended with “http://” if not present.
  • location (str, optional) – The city or country describing where the user of the account is located. The contents are not normalized or geocoded in any way.
  • description (str, optional) – A description of the user owning the account.
  • profile_link_color (str, optional) – hex value of profile color theme. formated without ‘#’ or ‘0x’. Ex: FF00FF
  • include_entities (bool, optional) – The entities node will be omitted when set to False.
  • skip_status (bool, optional) – When set to either True, t or 1 then statuses will not be included in the returned user objects.
Returns:

A twitter.User instance representing the modified user.

UploadMediaChunked(media, additional_owners=None, media_category=None)[source]

Upload a media file to Twitter in multiple requests.

Parameters:
  • media – File-like object to upload.
  • additional_owners – additional Twitter users that are allowed to use The uploaded media. Should be a list of integers. Maximum number of additional owners is capped at 100 by Twitter.
  • media_category – Category with which to identify media upload. Only use with Ads API & video files.
Returns:

ID of the uploaded media returned by the Twitter API. Raises if unsuccesful.

Return type:

media_id

UploadMediaSimple(media, additional_owners=None, media_category=None)[source]

Upload a media file to Twitter in one request. Used for small file uploads that do not require chunked uploads.

Parameters:
  • media – File-like object to upload.
  • additional_owners – additional Twitter users that are allowed to use The uploaded media. Should be a list of integers. Maximum number of additional owners is capped at 100 by Twitter.
  • media_category – Category with which to identify media upload. Only use with Ads API & video files.
Returns:

ID of the uploaded media returned by the Twitter API or 0.

Return type:

media_id

UsersLookup(user_id=None, screen_name=None, users=None, include_entities=True, return_json=False)[source]

Fetch extended information for the specified users.

Users may be specified either as lists of either user_ids, screen_names, or twitter.User objects. The list of users that are queried is the union of all specified parameters.

No more than 100 users may be given per request.

Parameters:
  • user_id (int, list, optional) – A list of user_ids to retrieve extended information.
  • screen_name (str, list, optional) – A list of screen_names to retrieve extended information.
  • users (list, optional) – A list of twitter.User objects to retrieve extended information.
  • include_entities (bool, optional) – The entities node that may appear within embedded statuses will be excluded when set to False.
  • return_json (bool, optional) – If True JSON data will be returned, instead of twitter.User
Returns:

A list of twitter.User objects for the requested users

VerifyCredentials(include_entities=None, skip_status=None, include_email=None)[source]

Returns a twitter.User instance if the authenticating user is valid.

Parameters:
  • include_entities – Specifies whether to return additional @replies in the stream.
  • skip_status – When set to either true, t or 1 statuses will not be included in the returned user object.
  • include_email – Use of this parameter requires whitelisting. When set to true email will be returned in the user objects as a string. If the user does not have an email address on their account, or if the email address is un-verified, null will be returned. If your app is not whitelisted, then the ‘email’ key will not be present in the json response.
Returns:

A twitter.User instance representing that user if the credentials are valid, None otherwise.

exception twitter.error.PythonTwitterDeprecationWarning[source]

Bases: exceptions.DeprecationWarning

Base class for python-twitter deprecation warnings

exception twitter.error.PythonTwitterDeprecationWarning330[source]

Bases: twitter.error.PythonTwitterDeprecationWarning

Warning for features to be removed in version 3.3.0

exception twitter.error.PythonTwitterDeprecationWarning340[source]

Bases: twitter.error.PythonTwitterDeprecationWarning

Warning for features to be removed in version 3.4.0

exception twitter.error.TwitterError[source]

Bases: exceptions.Exception

Base class for Twitter errors

message

Returns the first argument used to construct this error.

Models

class twitter.models.Category(**kwargs)[source]

Bases: twitter.models.TwitterModel

A class representing the suggested user category structure.

class twitter.models.DirectMessage(**kwargs)[source]

Bases: twitter.models.TwitterModel

A class representing a Direct Message.

class twitter.models.Hashtag(**kwargs)[source]

Bases: twitter.models.TwitterModel

A class representing a twitter hashtag.

class twitter.models.List(**kwargs)[source]

Bases: twitter.models.TwitterModel

A class representing the List structure used by the twitter API.

class twitter.models.Media(**kwargs)[source]

Bases: twitter.models.TwitterModel

A class representing the Media component of a tweet.

class twitter.models.Status(**kwargs)[source]

Bases: twitter.models.TwitterModel

A class representing the Status structure used by the twitter API.

classmethod NewFromJsonDict(data, **kwargs)[source]

Create a new instance based on a JSON dict.

Parameters:data – A JSON dict, as converted from the JSON in the twitter API
Returns:A twitter.Status instance
created_at_in_seconds

Get the time this status message was posted, in seconds since the epoch (1 Jan 1970).

Returns:The time this status message was posted, in seconds since the epoch.
Return type:int
class twitter.models.Trend(**kwargs)[source]

Bases: twitter.models.TwitterModel

A class representing a trending topic.

volume
class twitter.models.TwitterModel(**kwargs)[source]

Bases: object

Base class from which all twitter models will inherit.

AsDict()[source]

Create a dictionary representation of the object. Please see inline comments on construction when dictionaries contain TwitterModels.

AsJsonString(ensure_ascii=True)[source]

Returns the TwitterModel as a JSON string based on key/value pairs returned from the AsDict() method.

classmethod NewFromJsonDict(data, **kwargs)[source]

Create a new instance based on a JSON dict. Any kwargs should be supplied by the inherited, calling class.

Parameters:data – A JSON dict, as converted from the JSON in the twitter API.
class twitter.models.Url(**kwargs)[source]

Bases: twitter.models.TwitterModel

A class representing an URL contained in a tweet.

class twitter.models.User(**kwargs)[source]

Bases: twitter.models.TwitterModel

A class representing the User structure.

classmethod NewFromJsonDict(data, **kwargs)[source]
class twitter.models.UserStatus(**kwargs)[source]

Bases: twitter.models.TwitterModel

A class representing the UserStatus structure. This is an abbreviated form of the twitter.User object.

connections
class twitter.ratelimit.EndpointRateLimit(limit, remaining, reset)

Bases: tuple

limit

Alias for field number 0

remaining

Alias for field number 1

reset

Alias for field number 2

class twitter.ratelimit.RateLimit(**kwargs)[source]

Bases: object

Object to hold the rate limit status of various endpoints for the twitter.Api object.

This object is generally attached to the API as Api.rate_limit, but is not created until the user makes a method call that uses _RequestUrl() or calls Api.InitializeRateLimit(), after which it get created and populated with rate limit data from Twitter.

Calling Api.InitializeRateLimit() populates the object with all of the rate limits for the endpoints defined by Twitter; more info is available here:

Once a resource (i.e., an endpoint) has been requested, Twitter’s response will contain the current rate limit status as part of the headers, i.e.:

x-rate-limit-limit
x-rate-limit-remaining
x-rate-limit-reset

limit is the generic limit for that endpoint, remaining is how many more times you can make a call to that endpoint, and reset is the time (in seconds since the epoch) until remaining resets to its default for that endpoint.

Generally speaking, each endpoint has a 15-minute reset time and endpoints can either make 180 or 15 requests per window. According to Twitter, any endpoint not defined in the rate limit chart or the response from a GET request to application/rate_limit_status.json should be assumed to be 15 requests per 15 minutes.

get_limit(url)[source]

Gets a EndpointRateLimit object for the given url.

Parameters:url (str, optional) – URL of the endpoint for which to return the rate limit status.
Returns:EndpointRateLimit object containing rate limit information.
Return type:namedtuple
set_limit(url, limit, remaining, reset)[source]

If a resource family is unknown, add it to the object’s dictionary. This is to deal with new endpoints being added to the API, but not necessarily to the information returned by /account/rate_limit_status.json endpoint.

For example, if Twitter were to add an endpoint /puppies/lookup.json, the RateLimit object would create a resource family puppies and add /puppies/lookup as the endpoint, along with whatever limit, remaining hits available, and reset time would be applicable to that resource+endpoint pair.

Parameters:
  • url (str) – URL of the endpoint being fetched.
  • limit (int) – Max number of times a user or app can hit the endpoint before being rate limited.
  • remaining (int) – Number of times a user or app can access the endpoint before being rate limited.
  • reset (int) – Epoch time at which the rate limit window will reset.
set_unknown_limit(url, limit, remaining, reset)[source]
static url_to_resource(url)[source]

Take a fully qualified URL and attempts to return the rate limit resource family corresponding to it. For example:

>>> RateLimit.url_to_resource('https://api.twitter.com/1.1/statuses/lookup.json?id=317')
>>> '/statuses/lookup'
Parameters:url (str) – URL to convert to a resource family.
Returns:Resource family corresponding to the URL.
Return type:string
class twitter.ratelimit.ResourceEndpoint(regex, resource)

Bases: tuple

regex

Alias for field number 0

resource

Alias for field number 1

Utilities

twitter.twitter_utils.calc_expected_status_length(status, short_url_length=23)[source]

Calculates the length of a tweet, taking into account Twitter’s replacement of URLs with https://t.co links.

Parameters:
  • status – text of the status message to be posted.
  • short_url_length – the current published https://t.co links
Returns:

Expected length of the status message as an integer.

twitter.twitter_utils.enf_type(field, _type, val)[source]

Checks to see if a given val for a field (i.e., the name of the field) is of the proper _type. If it is not, raises a TwitterError with a brief explanation.

Parameters:
  • field – Name of the field you are checking.
  • _type – Type that the value should be returned as.
  • val – Value to convert to _type.
Returns:

val converted to type _type.

twitter.twitter_utils.http_to_file(http)[source]
twitter.twitter_utils.is_url(text)[source]

Checks to see if a bit of text is a URL.

Parameters:text – text to check.
Returns:Boolean of whether the text should be treated as a URL or not.
twitter.twitter_utils.parse_arg_list(args, attr)[source]
twitter.twitter_utils.parse_media_file(passed_media, async_upload=False)[source]

Parses a media file and attempts to return a file-like object and information about the media file.

Parameters:
  • passed_media – media file which to parse.
  • async_upload – flag, for validation media file attributes.
Returns:

file-like object, the filename of the media file, the file size, and the type of media.