Twitter Data API

Easily connect to the Twitter API and start your analysis immediately.

Main Features:

1 Get the results in a DataFrame: With the exception of three functions that return a list of ID's, everything else returns a pandas DataFrame, ready to use. This allows you to spend more time analyzing data, and less time figuring out the structure of the JSON response object. It's not complicated or anything, just takes time.

2 Manage looping and merging: there is a limit on how many results you get per request (typically in the 100 - 200 range), several requests have to be made, and merged together. Not all responses have the same structure, so this is also handled. You only have to provide the number of responses you want through the count parameter where applicable (provided you are within your app's rate limits).

3 Unnesting nested objects: Many response objects contain very rich embedded data, which is usually meta data about the response. For example, when you request tweets, you get a user object along with that. This is very helpful in better understanding who made the tweet, and how influential/credible they are.

4 Documentation: All available parameters are included in the function signatures, to make it easier to explore interactively, as well as descriptions of the parameters imported from the Twitter documentation.

Authentication

Before starting you will have to create an app through developer.twitter.com, and then you can get your authentication keys from your dashboard. Then you can authenticate as follows:

>>> auth_params = {
...     'app_key': 'YOUR_APP_KEY',
...     'app_secret': 'YOUR_APP_SECRET',
... }
>>> import advertools as adv
>>> adv.twitter.set_auth_params(**auth_params)

In some cases, you might be required to add oauth_token and oauth_token_secret, which case you ``auth_params will look like this:

>>> auth_params = {
...     'app_key': 'YOUR_APP_KEY',
...     'app_secret': 'YOUR_APP_SECRET',
...     'oauth_token': 'YOUR_OAUTH_TOKEN',
...     'oauth_token_secret': 'YOUR_OAUTH_TOKEN_SECRET',
... }

Now every request you send will include your auth_params in it, and if valid you will get the respective response, for example:

>>> python_tweets = adv.twitter.search(q='#python', tweet_mode='extended')

Make sure you always specify tweet_mode='extended' because otherwise you will get tweets that are 140 characters long.

When you have tweets and user data in the DataFrame, the column names would be prepended with tweet_ and user_ to make it clear what the data belong to.

Functions

authenticate(func)[source]

Used internally, please use set_auth_params for authentication.

get_application_rate_limit_status(consumed_only=True)[source]
Returns the current rate limits for methods belonging to the

specified resource families.

Parameters:

consumed_only -- Whether or not to return only items that have been consumed. Otherwise returns the full list.

https://developer.twitter.com/en/docs/developer-utilities/rate-limit-status/api-reference/get-application-rate_limit_status

Returns the locations that Twitter has trending topic information for.

https://developer.twitter.com/en/docs/trends/locations-with-trending-topics/api-reference/get-trends-available

get_favorites(user_id=None, screen_name=None, count=None, since_id=None, max_id=None, include_entities=None, tweet_mode=None)[source]
Returns the 20 most recent Tweets favorited by the authenticating

or specified user.

Parameters:

  • user_id -- (int - optional) The ID of the user for whom to return results.

  • screen_name -- (str - optional) The screen name of the user for whom to return results.

  • count -- (int - optional) Specifies the number of results to retrieve.

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

  • include_entities -- (bool - optional) The entities node will be omitted when set to False .

  • tweet_mode -- (str - optional) Valid request values are compat and extended, which give compatibility mode and extended mode, respectively for Tweets that contain over 140 characters

https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-favorites-list

get_followers_ids(user_id=None, screen_name=None, cursor=None, stringify_ids=None, count=None)[source]
Returns a cursored collection of user IDs for every user

following the specified user.

Parameters:

  • user_id -- (int - optional) The ID of the user for whom to return results.

  • screen_name -- (str - optional) The screen name of the user for whom to return results.

  • cursor -- (cursor - semi-optional) Causes the list of connections to be broken into pages of no more than 5000 IDs at a time. The number of IDs returned is not guaranteed to be 5000 as suspended users are filtered out after connections are queried. If no cursor is provided, a value of -1 will be assumed, which is the first “page.” The response from the API will include a previous_cursor and next_cursor to allow paging back and forth. See Using cursors to navigate collections for more information.

  • stringify_ids -- (bool - optional) Some programming environments will not consume Twitter IDs due to their size. Provide this option to have IDs returned as strings instead. More about Twitter IDs.

  • count -- (int - optional) Specifies the number of results to retrieve.

https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-followers-ids

get_followers_list(user_id=None, screen_name=None, cursor=None, count=None, skip_status=None, include_user_entities=None)[source]
Returns a cursored collection of user objects for users

following the specified user.

Parameters:

  • user_id -- (int - optional) The ID of the user for whom to return results.

  • screen_name -- (str - optional) The screen name of the user for whom to return results.

  • cursor -- (cursor - semi-optional) Causes the results to be broken into pages. If no cursor is provided, a value of -1 will be assumed, which is the first “page.” The response from the API will include a previous_cursor and next_cursor to allow paging back and forth. See Using cursors to navigate collections for more information.

  • count -- (int - optional) Specifies the number of results to retrieve.

  • skip_status -- (bool - optional) When set to True, statuses will not be included in the returned user objects. If set to any other value, statuses will be included.

  • include_user_entities -- (bool - optional) The user object entities node will not be included when set to False.

https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-followers-list

get_friends_ids(user_id=None, screen_name=None, cursor=None, stringify_ids=None, count=None)[source]
Returns a cursored collection of user IDs for every user the

specified user is following (otherwise known as their "friends").

Parameters:

  • user_id -- (int - optional) The ID of the user for whom to return results.

  • screen_name -- (str - optional) The screen name of the user for whom to return results.

  • cursor -- (cursor - semi-optional) Causes the list of connections to be broken into pages of no more than 5000 IDs at a time. The number of IDs returned is not guaranteed to be 5000 as suspended users are filtered out after connections are queried. If no cursor is provided, a value of -1 will be assumed, which is the first “page.” The response from the API will include a previous_cursor and next_cursor to allow paging back and forth. See Using cursors to navigate collections for more information.

  • stringify_ids -- (bool - optional) Some programming environments will not consume Twitter IDs due to their size. Provide this option to have IDs returned as strings instead. More about Twitter IDs.

  • count -- (int - optional) Specifies the number of results to retrieve.

https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friends-ids

get_friends_list(user_id=None, screen_name=None, cursor=None, count=None, skip_status=None, include_user_entities=None)[source]
Returns a cursored collection of user objects for every user the

specified user is following (otherwise known as their "friends").

Parameters:

  • user_id -- (int - optional) The ID of the user for whom to return results.

  • screen_name -- (str - optional) The screen name of the user for whom to return results.

  • cursor -- (cursor - semi-optional) Causes the results to be broken into pages. If no cursor is provided, a value of -1 will be assumed, which is the first “page.” The response from the API will include a previous_cursor and next_cursor to allow paging back and forth. See Using cursors to navigate collections for more information.

  • count -- (int - optional) Specifies the number of results to retrieve.

  • skip_status -- (bool - optional) When set to True statuses will not be included in the returned user objects.

  • include_user_entities -- (bool - optional) The user object entities node will not be included when set to False.

https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friends-list

get_home_timeline(count=None, since_id=None, max_id=None, trim_user=None, exclude_replies=None, include_entities=None, tweet_mode=None)[source]
Returns a collection of the most recent Tweets and retweets

posted by the authenticating user and the users they follow.

Parameters:

  • count -- (int - optional) Specifies the number of results to retrieve.

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

  • 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. Omit this parameter to receive the complete user object.

  • exclude_replies -- (bool - optional) 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.

  • include_entities -- (bool - optional) The entities node will not be included when set to False.

  • tweet_mode -- (str - optional) Valid request values are compat and extended, which give compatibility mode and extended mode, respectively for Tweets that contain over 140 characters

https://developer.twitter.com/en/docs/tweets/timelines/api-reference/get-statuses-home_timeline

get_list_members(list_id=None, slug=None, owner_screen_name=None, owner_id=None, count=None, cursor=None, include_entities=None, skip_status=None)[source]

Returns the members of the specified list.

Parameters:

  • list_id -- (str - required) The numerical id of the list.

  • slug -- (str - required) 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.

  • count -- (int - optional) Specifies the number of results to retrieve.

  • cursor -- (cursor - semi-optional) Causes the collection of list members to be broken into “pages” of consistent sizes (specified by the count parameter). If no cursor is provided, a value of -1 will be assumed, which is the first “page.” The response from the API will include a previous_cursor and next_cursor to allow paging back and forth. See Using cursors to navigate collections for more information.

  • include_entities -- (bool - optional) The entities node will not be included when set to False.

  • skip_status -- (bool - optional) When set to True statuses will not be included in the returned user objects.

https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-members

get_list_memberships(user_id=None, screen_name=None, count=None, cursor=None, filter_to_owned_lists=None)[source]

Returns the lists the specified user has been added to.

Parameters:

  • user_id -- (int - optional) The ID of the user for whom to return results. Helpful for disambiguating when a valid user ID is also a valid screen name.

  • screen_name -- (str - optional) The screen name of the user for whom to return results. Helpful for disambiguating when a valid screen name is also a user ID.

  • count -- (int - optional) Specifies the number of results to retrieve.

  • cursor -- (cursor - optional) Breaks the results into pages. Provide a value of -1 to begin paging. Provide values as returned in the response body’s next_cursor and previous_cursor attributes to page back and forth in the list. It is recommended to always use cursors when the method supports them. See Cursoring for more information.

  • filter_to_owned_lists -- (bool - optional) When True, will return just lists the authenticating user owns, and the user represented by user_id or screen_name is a member of.

https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-memberships

get_list_statuses(list_id=None, slug=None, owner_screen_name=None, owner_id=None, since_id=None, max_id=None, count=None, include_entities=None, include_rts=None, tweet_mode=None)[source]

Returns a timeline of tweets authored by members of the specified list.

Parameters:

  • list_id -- (str - required) The numerical id of the list.

  • slug -- (str - required) 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 .

  • 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 results to retrieve.

  • include_entities -- (bool - optional) Entities are ON by default in API 1.1, each tweet includes a node called “entities”. This node offers a variety of metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags. You can omit entities from the result by using include_entities=False

  • include_rts -- (bool - optional) When set to True, the list timeline will contain native retweets (if they exist) in addition to the standard stream of tweets. The output format of retweeted tweets is identical to the representation you see in home_timeline.

  • tweet_mode -- (str - optional) Valid request values are compat and extended, which give compatibility mode and extended mode, respectively for Tweets that contain over 140 characters

https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-statuses

get_list_subscribers(list_id=None, slug=None, owner_screen_name=None, owner_id=None, count=None, cursor=None, include_entities=None, skip_status=None)[source]

Returns the subscribers of the specified list.

Parameters:

  • list_id -- (str - required) The numerical id of the list.

  • slug -- (str - required) 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 .

  • count -- (int - optional) Specifies the number of results to retrieve.

  • cursor -- (cursor - optional) Breaks the results into pages. A single page contains 20 lists. 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. See Using cursors to navigate collections for more information.

  • include_entities -- (bool - optional) When set to True, each tweet will include a node called “entities”. This node offers a variety of metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags. While entities are opt-in on timelines at present, they will be made a default component of output in the future. See Tweet Entities for more details.

  • skip_status -- (bool - optional) When set to Truestatuses will not be included in the returned user objects.

https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-subscribers

get_list_subscriptions(user_id=None, screen_name=None, count=None, cursor=None)[source]

Obtain a collection of the lists the specified user is subscribed to.

Parameters:

  • user_id -- (int - optional) The ID of the user for whom to return results. Helpful for disambiguating when a valid user ID is also a valid screen name.

  • screen_name -- (str - optional) The screen name of the user for whom to return results. Helpful for disambiguating when a valid screen name is also a user ID.

  • count -- (int - optional) Specifies the number of results to retrieve.

  • cursor -- (cursor - optional) Breaks the results into pages. Provide a value of -1 to begin paging. Provide values as returned in the response body’s next_cursor and previous_cursor attributes to page back and forth in the list. It is recommended to always use cursors when the method supports them. See Cursoring for more information.

https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-subscriptions

get_mentions_timeline(count=None, since_id=None, max_id=None, trim_user=None, include_entities=None, tweet_mode=None)[source]
Returns the 20 most recent mentions (tweets containing a users's

@screen_name) for the authenticating user.

Parameters:

  • count -- (int - optional) Specifies the number of results to retrieve.

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

  • 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. Omit this parameter to receive the complete user object.

  • include_entities -- (bool - optional) The entities node will not be included when set to False.

  • tweet_mode -- (str - optional) Valid request values are compat and extended, which give compatibility mode and extended mode, respectively for Tweets that contain over 140 characters

https://developer.twitter.com/en/docs/tweets/timelines/api-reference/get-statuses-mentions_timeline

Returns the top 10 trending topics for a specific WOEID, if

trending information is available for it.

Parameters:

  • id -- (int or list of ints - required) run get_available_trends() for the full listing. The Yahoo! Where On Earth ID of the location to return trending information for. Global information is available by using 1 as the WOEID .

  • exclude -- (str - optional) Setting this equal to hashtags will remove all hashtags from the trends list.

https://developer.twitter.com/en/docs/trends/trends-for-location/api-reference/get-trends-place

get_retweeters_ids(id, count=None, cursor=None, stringify_ids=None)[source]
Returns a collection of up to 100 user IDs belonging to users who

have retweeted the tweet specified by the id parameter. It's better to use get_retweets because passing a count > 100 will only get you duplicated data. 100 is the maximum even if there were more retweeters.

Parameters:

  • id -- (int - required) The numerical ID of the desired status.

  • count -- (int - optional) Specifies the number of results to retrieve.

  • cursor -- (cursor - semi-optional) Causes the list of IDs to be broken into pages of no more than 100 IDs at a time. The number of IDs returned is not guaranteed to be 100 as suspended users are filtered out after connections are queried. If no cursor is provided, a value of -1 will be assumed, which is the first “page.” The response from the API will include a previous_cursor and next_cursor to allow paging back and forth. See our cursor docs for more information. While this method supports the cursor parameter, the entire result set can be returned in a single cursored collection. Using the count parameter with this method will not provide segmented cursors for use with this parameter.

  • stringify_ids -- (bool - optional) Many programming environments will not consume Tweet ids due to their size. Provide this option to have ids returned as strings instead.

https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-retweeters-ids

get_retweets(id, trim_user=None, tweet_mode=None)[source]

Returns up to 100 of the first retweets of a given tweet.

Parameters:

  • id -- (int - required) The numerical ID of the desired status.

  • 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. Omit this parameter to receive the complete user object.

  • tweet_mode -- (str - optional) Valid request values are compat and extended, which give compatibility mode and extended mode, respectively for Tweets that contain over 140 characters

https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-retweet-id

get_supported_languages()[source]
Returns the list of languages supported by Twitter along with

their ISO 639-1 code.

https://developer.twitter.com/en/docs/developer-utilities/supported-languages/api-reference/get-help-languages

get_user_timeline(user_id=None, screen_name=None, since_id=None, count=None, max_id=None, trim_user=None, exclude_replies=None, include_rts=None, tweet_mode=None)[source]
Returns a collection of the most recent Tweets posted by the user

indicated by the screen_name or user_id parameters.

Parameters:

  • user_id -- (int - optional) The ID of the user for whom to return results.

  • screen_name -- (str - optional) The screen name of the user for whom to return results.

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

  • count -- (int - optional) Specifies the number of results to retrieve.

  • max_id -- (int - optional) Returns results with an ID less than (that is, older than) or equal to the specified ID.

  • 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. Omit this parameter to receive the complete user object.

  • exclude_replies -- (bool - optional) 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.

  • include_rts -- (bool - optional) When set to False , the timeline will strip any native retweets (though they will still count toward both the maximal length of the timeline and the slice selected by the count parameter). Note: If you’re using the trim_user parameter in conjunction with include_rts, the retweets will still contain a full user object.

  • tweet_mode -- (str - optional) Valid request values are compat and extended, which give compatibility mode and extended mode, respectively for Tweets that contain over 140 characters

https://developer.twitter.com/en/docs/tweets/timelines/api-reference/get-statuses-user_timeline

lookup_status(id, include_entities=None, trim_user=None, map=None, include_ext_alt_text=None, include_card_uri=None, tweet_mode=None)[source]
Returns fully-hydrated tweet objects for up to 100 tweets per

request, as specified by comma-separated values passed to the id parameter.

Parameters:

  • id -- (int - required) A comma separated list of Tweet IDs, up to 100 are allowed in a single request.

  • include_entities -- (bool - optional) The entities node that may appear within embedded statuses will not be included when set to False.

  • 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. Omit this parameter to receive the complete user object.

  • map -- (bool - optional) When using the map parameter, Tweets that do not exist or cannot be viewed by the current user will still have their key represented but with an explicitly null value paired with it

  • include_ext_alt_text -- (bool - optional) If alt text has been added to any attached media entities, this parameter will return an ext_alt_text value in the top-level key for the media entity. If no value has been set, this will be returned as null

  • include_card_uri -- (bool - optional) When set to True, each Tweet returned will include a card_uri attribute when there is an ads card attached to the Tweet and when that card was attached using the card_uri value.

  • tweet_mode -- (str - optional) Valid request values are compat and extended, which give compatibility mode and extended mode, respectively for Tweets that contain over 140 characters

https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-lookup

lookup_user(screen_name=None, user_id=None, include_entities=None, tweet_mode=None)[source]
Returns fully-hydrated user objects for up to 100 users per request,

as specified by comma-separated values passed to the user_id and/or screen_name parameters.

Parameters:

  • screen_name -- (str - optional) A comma separated list of screen names, up to 100 are allowed in a single request. You are strongly encouraged to use a POST for larger (up to 100 screen names) requests.

  • user_id -- (int - optional) A comma separated list of user IDs, up to 100 are allowed in a single request. You are strongly encouraged to use a POST for larger requests.

  • include_entities -- (bool - optional) The entities node that may appear within embedded statuses will not be included when set to False.

  • tweet_mode -- (str - optional) Valid request values are compat and extended, which give compatibility mode and extended mode, respectively for Tweets that contain over 140 characters

https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup

make_dataframe(func)[source]
retweeted_of_me(count=None, since_id=None, max_id=None, trim_user=None, include_entities=None, include_user_entities=None, tweet_mode=None)[source]
Returns the most recent tweets authored by the authenticating user

that have been retweeted by others.

Parameters:

  • count -- (int - optional) Specifies the number of results to retrieve.

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

  • 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. Omit this parameter to receive the complete user object.

  • include_entities -- (bool - optional) The tweet entities node will not be included when set to False .

  • include_user_entities -- (bool - optional) The user entities node will not be included when set to False .

  • tweet_mode -- (str - optional) Valid request values are compat and extended, which give compatibility mode and extended mode, respectively for Tweets that contain over 140 characters

https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-retweets_of_me

search(q, geocode=None, lang=None, locale=None, result_type=None, count=None, until=None, since_id=None, max_id=None, include_entities=None, tweet_mode=None)[source]

Returns a collection of relevant Tweets matching a specified query.

Parameters:

  • q -- (str - required) A UTF-8, URL-encoded search query of 500 characters maximum, including operators. Queries may additionally be limited by complexity.

  • geocode -- (lat lon dist - optional) Returns tweets by users located within a given radius of the given latitude/longitude. The location is preferentially taking from the Geotagging API, but will fall back to their Twitter profile. The parameter value is specified by ” latitude,longitude,radius “, where radius units must be specified as either ” mi ” (miles) or ” km ” (kilometers). Note that you cannot use the near operator via the API to geocode arbitrary locations; however you can use this geocode parameter to search near geocodes directly. A maximum of 1,000 distinct “sub- regions” will be considered when using the radius modifier.

  • lang -- (str - optional) Restricts tweets to the given language, given by an ISO 639-1 code. Language detection is best-effort.

  • locale -- (str - optional) Specify the language of the query you are sending (only ja is currently effective). This is intended for language- specific consumers and the default should work in the majority of cases.

  • result_type -- (str - optional) Optional. Specifies what type of search results you would prefer to receive. The current default is “mixed.” Valid values include: * mixed : Include both popular and real time results in the response. * recent : return only the most recent results in the response * popular : return only the most popular results in the response.

  • count -- (int - optional) Specifies the number of results to retrieve.

  • until -- (date - optional) Returns tweets created before the given date. Date should be formatted as YYYY-MM-DD. Keep in mind that the search index has a 7-day limit. In other words, no tweets will be found for a date older than one week.

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

  • include_entities -- (bool - optional) The entities node will not be included when set to False.

  • tweet_mode -- (str - optional) Valid request values are compat and extended, which give compatibility mode and extended mode, respectively for Tweets that contain over 140 characters

Operator

Finds Tweets...

watching now

containing both “watching” and “now”. This is the default operator.

“happy hour”

containing the exact phrase “happy hour”.

love OR hate

containing either “love” or “hate” (or both).

beer -root

containing “beer” but not “root”.

#haiku

containing the hashtag “haiku”.

from:interior

sent from Twitter account “interior”.

list:NASA/astronauts-in-space-now

sent from a Twitter account in the NASA list astronauts-in-space-now

to:NASA

a Tweet authored in reply to Twitter account “NASA”.

@NASA

mentioning Twitter account “NASA”.

politics filter:safe

containing “politics” with Tweets marked as potentially sensitive removed.

puppy filter:media

containing “puppy” and an image or video.

puppy -filter:retweets

containing “puppy”, filtering out retweets

puppy filter:native_video

containing “puppy” and an uploaded video, Amplify video, Periscope, or Vine.

puppy filter:periscope

containing “puppy” and a Periscope video URL.

puppy filter:vine

containing “puppy” and a Vine.

puppy filter:images

containing “puppy” and links identified as photos, including third parties such as Instagram.

puppy filter:twimg

containing “puppy” and a pic.twitter.com link representing one or more photos.

hilarious filter:links

containing “hilarious” and linking to URL.

puppy url:amazon

containing “puppy” and a URL with the word “amazon” anywhere within it.

superhero since:2015-12-21

containing “superhero” and sent since date “2015-12-21” (year-month-day).

puppy until:2015-12-21

containing “puppy” and sent before the date “2015-12-21”.

movie -scary :)

containing “movie”, but not “scary”, and with a positive attitude.

flight :(

containing “flight” and with a negative attitude.

traffic ?

containing “traffic” and asking a question.

https://developer.twitter.com/en/docs/tweets/search/api-reference/get-search-tweets

search_users(q, page=None, count=None, include_entities=None)[source]
Provides a simple, relevance-based search interface to public user

accounts on Twitter.

Parameters:

  • q -- (str - required) The search query to run against people search.

  • page -- (int - optional) Specifies the page of results to retrieve.

  • count -- (int - optional) Specifies the number of results to retrieve.

  • include_entities -- (bool - optional) The entities node will not be included in embedded Tweet objects when set to False .

https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-search

set_auth_params(app_key=None, app_secret=None, oauth_token=None, oauth_token_secret=None, access_token=None, token_type='bearer', oauth_version=1, api_version='1.1', client_args=None, auth_endpoint='authenticate')[source]

The main function for authentication. Needs to be called once in a session.

First you need to create a developer account and app: https://developer.twitter.com/ to get your credentials.

Different ways to authenticate: https://twython.readthedocs.io/en/latest/usage/starting_out.html

show_lists(user_id=None, screen_name=None, reverse=None)[source]
Returns all lists the authenticating or specified user subscribes to,

including their own.

Parameters:

  • user_id -- (int - optional) The ID of the user for whom to return results. Helpful for disambiguating when a valid user ID is also a valid screen name. Note: : Specifies the ID of the user to get lists from. Helpful for disambiguating when a valid user ID is also a valid screen name.

  • screen_name -- (str - optional) The screen name of the user for whom to return results. Helpful for disambiguating when a valid screen name is also a user ID.

  • reverse -- (bool - optional) Set this to true if you would like owned lists to be returned first. See description above for information on how this parameter works.

https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-list

show_owned_lists(user_id=None, screen_name=None, count=None, cursor=None)[source]

Returns the lists owned by the specified Twitter user.

Parameters:

  • user_id -- (int - optional) The ID of the user for whom to return results. Helpful for disambiguating when a valid user ID is also a valid screen name.

  • screen_name -- (str - optional) The screen name of the user for whom to return results. Helpful for disambiguating when a valid screen name is also a user ID.

  • count -- (int - optional) Specifies the number of results to retrieve.

  • cursor -- (cursor - optional) Breaks the results into pages. Provide a value of -1 to begin paging. Provide values as returned in the response body’s next_cursor and previous_cursor attributes to page back and forth in the list. It is recommended to always use cursors when the method supports them. See Cursoring for more information.

https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-ownerships