API Usage

The TwitterPandas client is a wrapper around a tweepy connection that allows you to simply interact with the twitter api and get back pandas dataframes pre-flattened. You can always also access the underlying tweepy connection to get back raw responses if you prefer.

Setting up a connection

To set up a connection just:

from twitterpandas import TwitterPandas
# create a twitter pandas client object
tp = TwitterPandas(
    TWITTER_OAUTH_TOKEN,
    TWITTER_OAUTH_SECRET,
    TWITTER_CONSUMER_KEY,
    TWITTER_CONSUMER_SECRET
)
# create a dataframe with 10 of my own followers
df = tp.followers(limit=10)
print(df.head())
# create a dataframe with my own information
df = tp.me()
print(df)
# get a dataframe with the information of user willmcginnis
df = tp.get_user(screen_name='willmcginnis')
print(df)
# get back 10 users who match the query willmcginnis
df = tp.search_users(query='willmcginnis', limit=10)
print(df)

Detailed API Documentation

class twitterpandas.client.TwitterPandas(oauth_token, oauth_secret, consumer_key, consumer_secret, timeout=60)

The primary interface into twitter pandas, the client.

direct_messages(since_id=None, max_id=None, limit=1, page=1, full_text=False, include_user_data=False)

Returns direct messages sent to the user tied to the API keys, in the form of a Pandas DataFrame

Parameters:
  • since_id –
  • max_id –
  • count –
  • page –
  • full_text –
Returns:
exists_friendship(source_id=None, source_user_id=None, source_screen_name=None, target_id=None, target_user_id=None, target_screen_name=None)

Checks if a friendship exists between two users. Will return True if user_a follows user_b, otherwise False.

Parameters:
  • source_id – Specifies the ID or screen name of the source user.
  • source_user_id – Specifies the ID of the source user. Helpful for disambiguating when a valid user ID is also a valid screen name.
  • source_screen_name – Specifies the screen name of the source user. Helpful for disambiguating when a valid screen name is also a user ID.
  • target_id – Specifies the ID or screen name of the target user.
  • target_user_id – Specifies the ID of the target user. Helpful for disambiguating when a valid user ID is also a valid screen name.
  • target_screen_name – Specifies the screen name of the target user. Helpful for disambiguating when a valid screen name is also a user ID.
Returns:
favorites(id_=None, limit=None)

Returns a dataframe of all data about followers for the user tied to the API keys.

Parameters:
  • id – Specifies the ID or screen name of the user.
  • limit – the maximum number of rows to return (optional, default None for all rows)
Returns:
followers(id_=None, user_id=None, screen_name=None, limit=None)

Returns a dataframe of all data about followers for the user tied to the API keys.

Parameters:
  • id – Specifies the ID or screen name of the user.
  • user_id – Specifies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name.
  • screen_name – Specifies the screen name of the user. Helpful for disambiguating when a valid screen name is also a user ID.
  • limit – the maximum number of rows to return (optional, default None for all rows)
Returns:
followers_ids(id_=None, screen_name=None, user_id=None, limit=None)

Returns an array containing the IDs of users following the specified user.

Parameters:
  • id – Specifies the ID or screen name of the user.
  • user_id – Specifies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name.
  • screen_name – Specifies the screen name of the user. Helpful for disambiguating when a valid screen name is also a user ID.
  • limit – the maximum number of rows to return (optional, default None for all rows)
Returns:
friends_ids(id_=None, screen_name=None, user_id=None, limit=None)

Returns an array containing the IDs of users being followed by the specified user.

Parameters:
  • id – Specifies the ID or screen name of the user.
  • user_id – Specifies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name.1
  • screen_name – Specifies the screen name of the user. Helpful for disambiguating when a valid screen name is also a user ID.
  • limit – the maximum number of rows to return (optional, default None for all rows)
Returns:
get_direct_message(id_=None, include_user_data=False)

Returns a single direct message object sent to the user tied to the API keys in the form of a Pandas DataFrame

Parameters:
  • since_id –
  • id –
  • full_text –
Returns:
get_list(owner=None, slug=None, limit=None)

Show the specified list. Private lists will only be shown if the authenticated user owns the specified list.

Parameters:
  • owner – the screen name of the owner of the list
  • slug – the slug name or numerical ID of the list
  • limit – the maximum number of rows to return (optional, default None for all rows)
Returns:

Returns saved search attributes for one specific saved search object as a Pandas DataFrame that contains created_at, id, id_str, name, position, query as columns

Parameters:id – Specifies the ID of the saved search object to convert to a DataFrame
Returns:
get_status(id_)

Returns a single status specified by the ID parameter.

Parameters:id – The numerical ID of the status.
Returns:
get_user(id_=None, user_id=None, screen_name=None)

Returns a dataframe with just one row, which contains all the information we have about that specific user.

Parameters:
  • id – Specifies the ID or screen name of the user.
  • user_id – Specifies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name.
  • screen_name – Specifies the screen name of the user. Helpful for disambiguating when a valid screen name is also a user ID.
Returns:
home_timeline(since_id=None, max_id=None, limit=None)
Parameters:
  • since_id – Returns only statuses with an ID greater than (that is, more recent than) the specified ID.
  • max_id – Returns only statuses with an ID less than (that is, older than) or equal to the specified ID.
  • limit – the maximum number of rows to return (optional, default None for all rows)
Returns:
list_members(owner=None, slug=None, limit=None)

Returns the members of the specified list.

Parameters:
  • owner – the screen name of the owner of the list
  • slug – the slug name or numerical ID of the list
  • limit – the maximum number of rows to return (optional, default None for all rows)
Returns:
list_subscribers(owner=None, slug=None, limit=None)

Returns the subscribers of the specified list.

Parameters:
  • owner – the screen name of the owner of the list
  • slug – the slug name or numerical ID of the list
  • limit – the maximum number of rows to return (optional, default None for all rows)
Returns:
list_timeline(owner, slug, since_id=None, max_id=None, limit=None)

Show tweet timeline for members of the specified list.

Parameters:
  • owner – the screen name of the owner of the list
  • slug – the slug name or numerical ID of the list
  • limit – the maximum number of rows to return (optional, default None for all rows)
  • since_id – Returns only statuses with an ID greater than (that is, more recent than) the specified ID.
  • max_id – Returns only statuses with an ID less than (that is, older than) or equal to the specified ID.
Returns:
me()

Returns a dataframe with just one row, which has all of the data avilable about the user tied to the API key.

Returns:
rate_limit_status()

Returns a dataframe with the rate limit status for all resources and endpoints in the API.

Returns:
retweets(id_=None, count=None)

Returns up to 100* of the first retweets of the given tweet. Please read the discrepancies below.

DISCREPANCIES:
  • while the tweepy API states that the first 100 tweets are returned, testing shows that the limit actually seems to waver between 89-91
  • testing shows that self.client.retweets always returns one less Status obect than specified in count
  • if the count <1, the number of retweets returned is 19
Parameters:
  • id – The numerical ID of the status.
  • count – Specifies the number of retweets to retrieve.
retweets_of_me(since_id=None, max_id=None, limit=None)
Parameters:
  • since_id – Returns only statuses with an ID greater than (that is, more recent than) the specified ID.
  • max_id – Returns only statuses with an ID less than (that is, older than) or equal to the specified ID.
  • limit – the maximum number of rows to return (optional, default None for all rows)
Returns:
saved_searches()

Returns saved search attributes for the user tied to the API keys, as a Pandas DataFrame that contains created_at, id, id_str, name, position, query as columns

Returns:
search_users(query=None, limit=None)

Lets you structure a query and returns a dataframe with all of the users that match that query (max 1000 results as per API rules)

Parameters:
  • query – The query to run against people search.
  • limit – the maximum number of rows to return (optional, default None for all rows)
Returns:
sent_direct_messages(since_id=None, max_id=None, limit=1, page=1, full_text=False, include_user_data=False)

Returns direct message objects sent by the user tied to the API keys in the form of a Pandas DataFrame

Parameters:
  • since_id –
  • max_id –
  • count –
  • page –
  • full_text –
Returns:
show_friendship(source_id=None, source_screen_name=None, target_id=None, target_screen_name=None)

Returns detailed information about the relationship between two users.

Parameters:
  • source_id – The user_id of the subject user.
  • source_screen_name – The screen_name of the subject user.
  • target_id – The user_id of the target user.
  • target_screen_name – The screen_name of the target user.
Returns:
statuses_lookup(id_=None, include_entities=None, trim_user=None, limit=None)
Parameters:
  • id – A list of Tweet IDs to lookup, up to 100
  • include_entities – A boolean indicating whether or not to include [entities](https://dev.twitter.com/docs/entities) in the returned tweets. Defaults to False.
  • trim_user – A boolean indicating if user IDs should be provided, instead of full user information. Defaults to False.
Returns:
trends_available()
Returns:
trends_closest(lat=None, long=None)

Returns a one row dataframe with the woeid and location information closes to the coordinates passed.

Parameters:
  • lat – If provided with a long parameter the available trend locations will be sorted by distance, nearest to furthest, to the co-ordinate pair. The valid ranges for longitude is -180.0 to +180.0 (West is negative, East is positive) inclusive.
  • long – If provided with a lat parameter the available trend locations will be sorted by distance, nearest to furthest, to the co-ordinate pair. The valid ranges for longitude is -180.0 to +180.0 (West is negative, East is positive) inclusive.
Returns:
trends_place(id_=None, exclude=None)

Returns the trending topics for a given location id (can find it with the trends closest function).

Parameters:
  • id – 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 – Setting this equal to hashtags will remove all hashtags from the trends list.
Returns:
user_timeline(id_=None, user_id=None, screen_name=None, since_id=None, max_id=None, limit=None)
Parameters:
  • id – Specifies the ID or screen name of the user.
  • user_id – Specifies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name.
  • screen_name – Specifies the screen name of the user. Helpful for disambiguating when a valid screen name is also a user ID.
  • since_id – Returns only statuses with an ID greater than (that is, more recent than) the specified ID.
  • max_id – Returns only statuses with an ID less than (that is, older than) or equal to the specified ID.
  • limit – the maximum number of rows to return (optional, default None for all rows)
Returns: