Last Updated: Wednesday 14th August 2013

Python is great language for all sorts of things. Very active developer community creates many libraries which extend the language and make it easier to use various services. One of those libraries is tweepy. Tweepy is open-sourced, hosted on GitHub and enables Python to communicate with Twitter platform and use its API. For an introduction on the library Twython - check out this article.

At the time of writing, the current version of tweepy is 1.13. It was released on January 17, and offers various bug fixes and new functionality compared to the previous version. The 2.x version is being developed but it is currently unstable so a huge majority of the users should use the regular version.

Installing tweepy is easy, it can be cloned from the Github repository:

Or using easy install:

Either way provides you with the latest version.

Using tweepy

Tweepy supports accessing Twitter via Basic Authentication and the newer method, OAuth. Twitter has stopped accepting Basic Authentication so OAuth is now the only way to use the Twitter API.

Here is a sample of how to access the Twitter API using tweepy with OAuth:

The result of this code is the following:
Tweepy Hello World Status

The main difference between Basic and OAuth authentication are the consumer and access keys. With Basic Authentication, it was possible to provide a username and password and access the API, but since 2010 when the Twitter started requiring OAuth, the process is a bit more complicated. An app has to be created at dev.twitter.com.

OAuth is a bit more complicated initially than Basic Auth, since it requires more effort, but the benefits it offers are very lucrative:

  • Tweets can be customized to have a string which identifies the app which was used.
  • It doesn’t reveal user password, making it more secure.
  • It's easier to manage the permissions, for example a set of tokens and keys can be generated that only allows reading from the timelines, so in case someone obtains those credentials, he/she won’t be able to write or send direct messages, minimizing the risk.
  • The application doesn't reply on a password, so even if the user changes it, the application will still work.

After logging in to the portal, and going to "Applications", a new application can be created which will provide the needed data for communicating with Twitter API.

Twiter OAuth Dashboard

This is a screen which has all of the data needed to talk to Twitter network. It is important to note that by default, the app has no access to direct messages, so by going to the settings and changing the appropriate option to “Read, write and direct messages”, you can enable your app to have access to every Twitter feature.

Twitter API

Tweepy provides access to the well documented Twitter API. With tweepy, it's possible to get any object and use any method that the official Twitter API offers. For example, a User object has its documentation at https://dev.twitter.com/docs/platform-objects/users and following those guidelines, tweepy can get the appropriate information.

Main Model classes in the Twitter API are Tweets, Users, Entities and Places. Access to each returns a JSON-formatted response and traversing through information is very easy in Python.

Gives us the following output:

All of the API methods are documented here: http://packages.python.org/tweepy/html/api.html

Tweepy StreamingAPI

One of the main usage cases of tweepy is monitoring for tweets and doing actions when some event happens. Key component of that is the StreamListener object, which monitors tweets in real time and catches them.

StreamListener has several methods, with on_data() and on_status() being the most useful ones. Here is a sample program which implements this behavior:

So, this program has a StreamListener implemented and the code is set up to use OAuth. The Stream object is created, which uses that listener as output. Stream, being another important object in tweepy also has many methods, in this case filter() is used with parameters passed. "follow" is a list of followers whose tweets are monitored, and "track" is a list of hashtags which will trigger the StreamListener.

In this example, we have used my user ID to follow and the #pythoncentral hashtag as a condition. After running the program and tweeting this status:

Tweepy "Hello World" with hashtag

The program almost instantly catches the tweet, and calls the on_status() method, which produces the following output in the console:

Besides printing the tweet, in the on_status() method there are some additional things which illustrate the number of possibilities that can be done with the tweet data:

This code traverses through entities, picks the "hashtags" one and for each hashtag the tweet contains, it prints its value. This is just a sample; a complete list of tweet entities is located here: https://dev.twitter.com/docs/tweet-entities.

Conclusion

To sum up, tweepy is a great open-source library which provides access to the Twitter API for Python. Although the documentation for tweepy is a bit scarce and doesn't have many examples, the fact that it heavily relies on the Twitter API, which has excellent documentation, makes it probably the best Twitter library for Python, especially when considering the Streaming API support, which is where tweepy excels. Other libraries like python-twitter provide many functions too, but the tweepy has most active community and most commits to the code in the last year.

Additional resources used for tweepy can be obtained here:

About The Author

  • flora

    Hello everybody,

    Can somebody tell me how to use the count parameter in the filter () in tweepy?
    Please reply ASAP.
    Its urgent.
    Thank you !

  • TonyLima

    I’m working on a script to back up some Twitter data. I can get the authentication url and the PIN. But then I get this error:

    Traceback (most recent call last):
    File “b.py”, line 47, in
    auth.get_access_token(api)
    File “build/bdist.macosx-10.9-intel/egg/tweepy/auth.py”, line 119, in get_access_token
    tweepy.error.TweepError: HTTP Error 401: Unauthorized

    Any ideas and/or suggestions will be greatly appreciated.

    • http://jacksonc.com Jackson Cooper

      Hi Tony. It depends on what mode you want to run in, as a server or client. If you’re wanting to backup your data, you won’t have to get the access token, only set it (with set_access_token). Also, make sure you’ve given the app you created sufficient credentials.

      • TonyLima

        I think your suggestion about the app credentials is the problem. I’m having other difficulties, but will play with this stuff a bit longer before I bother you again. Thanks, Jackson!

        Best,
        Tony

        • http://jacksonc.com Jackson Cooper

          No worries Tony, good luck 😉

  • TonyLima

    OK, I decided to run the script on my Mac just to see if this was a problem being caused by Windows. Now I’m even more confused. Here’s the error message:

    Traceback (most recent call last):
    File “buddyadd_osx.py”, line 66, in
    api.create_friendship(line)
    File “build/bdist.macosx-10.9-intel/egg/tweepy/binder.py”, line 200, in _call
    File “build/bdist.macosx-10.9-intel/egg/tweepy/binder.py”, line 176, in execute
    tweepy.error.TweepError: [{u’message': u’Sorry, that page does not exist’, u’code': 34}]

    All ideas, suggestions, comments, and criticism gladly accepted. Thanks in advance,
    Tony

  • bhubaneswari

    getting this error while installing.. plz suggest solution

    C:Python27Libtweepy2>python setup.py install
    Traceback (most recent call last):
    File “setup.py”, line 4, in
    from tweepy import __version__
    File “C:Python27Libtweepy2tweepy__init__.py”, line 14, in
    from tweepy.api import API
    File “C:Python27Libtweepy2tweepyapi.py”, line 8, in
    from tweepy.binder import bind_api
    File “C:Python27Libtweepy2tweepybinder.py”, line 5, in
    import requests
    ImportError: No module named requests

    • http://jacksonc.com Jackson Cooper

      You need to install the requests library. Try pip install requests

    • shashivs

      Why not let the pip take care of modules installation procedure : pip install . It will take care of installing dependencies as well :-)

  • Jorge Saldivar Galli

    I think there is a little mistake in the code. The parameter “follow” in the method “filter” of “streaming” should receive an array of strings, not an array of integers. So, instead of

    stream.filter(follow=[38744894], track=[‘#pythoncentral’])

    it should be

    stream.filter(follow=[‘38744894′], track=[‘#pythoncentral’])

  • Eman Naguib

    python setup.py install …. this error appear why ?
    `Traceback (most recent call last):
    File “setup.py”, line 5, in
    from pip.req import parse_requirements
    File “/usr/lib/python2.7/dist-packages/pip/__init__.py”, line 11, in
    from pip.vcs import git, mercurial, subversion, bazaar # noqa
    File “/usr/lib/python2.7/dist-packages/pip/vcs/mercurial.py”, line 9, in
    from pip.download import path_to_url
    File “/usr/lib/python2.7/dist-packages/pip/download.py”, line 25, in
    from requests.compat import IncompleteRead
    ImportError: cannot import name IncompleteRead`

    and in terminal write python , import tweepy
    `Traceback (most recent call last):
    File “”, line 1, in
    File “tweepy/__init__.py”, line 16, in
    from tweepy.auth import OAuthHandler, AppAuthHandler
    File “tweepy/auth.py”, line 9, in
    from requests_oauthlib import OAuth1Session, OAuth1
    File “/usr/local/lib/python2.7/dist-package/requests_oauthlib-0.4.1-py2.7.egg/requests_oauthlib/__init__.py”, line 3, in
    from .oauth2_auth import OAuth2
    File “/usr/local/lib/python2.7/dist-packages/requests_oauthlib-0.4.1-py2.7.egg/requests_oauthlib/oauth2_auth.py”, line 3, in
    from oauthlib.oauth2 import is_secure_transport
    ImportError: cannot import name is_secure_transport `

    • http://jacksonc.com Jackson Cooper

      Check if $PYTHONPATH is set correctly, and oauthlib’s correctly installed. If not `sudo pip install oauthlib --upgrade`

  • http://www.skyberrys.com Carrie

    Tweepy api has updated, the update_status is this: api.update_status(status=’Hello Python Central!’)

  • unique

    HI i am entirely focusing on finding out the following information from twittter
    by passing the screen name , i want to extract all tweet of particular user
    in above code this stream.filter(follow=[38744894] does not work but if i want to find out the tweets on particular topic by doing stream.filter(track=[‘car’]) works

    and my second problem

    if i want to display or extract the tweet from twitter timeline with the attribute of person who tweets, timestamp, and tweet

    i could able to extract tweets only as much as i specify in items in following code

    statuses = tweepy.Cursor(api.home_timeline).items(4)
    print(‘n’)
    #data = [s.text.encode(‘utf8′) for s in statuses]
    data = [s.text for (s) in statuses]
    print ‘Tweet %s: tnn’ %(data)

    suggesstion pls as i am new in python and in API

  • pravarag

    Heya, i’ve been studying the tweepy docs for couple of days now but kinda stuck on few things:

    1. We access an API method to use the tweepy API and we call the methods of API class such as me(), get_user() etc. now in the above example the user accesses the screen name and the location from the me() object so how do they get called? is the models.py file involved anyhow? i read the docs and there was a statement that : “When we invoke an API method most of the time returned back to us will be a Tweepy model class instance”, so what does this statement means? and what is that most of the times the model class instance is invoked?can anybody help me with this… thank you!!

  • pravarag

    Heya, i’ve been studying the docs of tweepy and kinda stuck on few things: — the user in the above example makes an API class object and then calls the me() function with that instance.Now, i’ve tried logging through the details of the API class but wasn’t able to find the name and location fields in the function..actually there is no me() function the in api class…what am i doing wrong here? i am trying to retrace the call of the object back to it’s source..i really need help..also in the docs the author has mentioned that most of the time when an instance of api is created, models are called from the models.py, how is this related to everything?? can anybody explain it in a better or i would just say an easier way..the docs are not of great help…thank you

  • itisha

    hi,i used above code for extrcating tweets using tweepy and python but m able to extract only few tweets and after that i got error…Plz help me out how can i extract tweets using python and tweepy

    • http://jacksonc.com Jackson Cooper

      What was the error?