Next, let’s create a Cursor object that will call the followers method for NASA’s account, which is specified with the screen_name keyword argument:

In [18]: cursor = tweepy.Cursor(api.followers, screen_name='nasa')

The Cursor’s constructor receives as its argument the name of the method to call—api.followers indicates that the Cursor will call the api object’s followers method. If the Cursor constructor receives any additional keyword arguments, like screen_name, these will be passed to the method specified in the constructor’s first argument. So, this Cursor specifically gets followers for the @nasa Twitter account.

Now, we can use the Cursor to get some followers. The following for statement iterates through the results of the expression cursor.items(10). The Cursor’s items method initiates the call to api.followers and returns the followers method’s results. In this case, we pass 10 to the items method to request only 10 results:

In [19]: for account in cursor.items(10):
    ...:     followers.append(account.screen_name)
    ...:

In [20]: print('Followers:',
    ...:       ' '.join(sorted(followers, key=lambda s: s.lower())))
    ...:
Followers: abhinavborra BHood1976 Eshwar12341 Harish90469614 heshamkisha
Highyaan2407 JiraaJaarra KimYooJ91459029 Lindsey06771483 Wendy_UAE_NL

The preceding snippet displays the followers in ascending order by calling the built-in sorted function. The function’s second argument is the function used to determine how the elements of followers are sorted. In this case, we used a lambda that converts every follower name to lowercase letters so we can perform a case-insensitive sort.

If the number of results requested is more than can be returned by one call to followers, the items method automatically “pages” through the results by making multiple calls to api.followers. Recall that followers returns up to 20 followers at a time by default, so the preceding code needs to call followers only once. To get up to 200 followers at a time, we can create the Cursor with the count keyword argument, as in:

cursor = tweepy.Cursor(api.followers, screen_name='nasa', count=200)

If you do not specify an argument to the items method, The Cursor attempts to get all of the account’s followers. For large numbers of followers, this could take a significant amount of time due to Twitter’s rate limits. The Twitter API’s followers/list method can return a maximum of 200 followers at a time and Twitter allows a maximum of 15 calls every 15 minutes. Thus, you can only get 3000 followers every 15 minutes using Twitter’s free APIs. Recall that we configured the API object to automatically wait when it hits a rate limit, so if you try to get all followers and an account has more than 3000, Tweepy will automatically pause for 15 minutes after every 3000 followers and display a message. At the time of this writing, NASA has over 29.5 million followers. At 12,000 followers per hour, it would take over 100 days to get all of NASA’s followers.

Note that for this example, we could have called the followers method directly, rather than using a Cursor, since we’re getting only a small number of followers. We used a Cursor here to show how you’ll typically call followers. In some later examples, we’ll call API methods directly to get just a few results, rather than using Cursors.

Though you can get complete User objects for a maximum of 200 followers at a time, you can get many more Twitter ID numbers by calling the API object’s followers_ids method. This calls the Twitter API’s followers/ids method, which returns up to 5000 ID numbers at a time (again, these rate limits could change).¹² You can invoke this method up to 15 times every 15 minutes, so you can get 75,000 account ID numbers per rate-limit interval. This is particularly useful when combined with the API object’s lookup_users method. This calls the Twitter API’s users/lookup method¹³ which can return up to 100 User objects at a time and can be called up to 300 times every 15 minutes. So using this combination, you could get up to 30,000 User objects per rate-limit interval.

You can call the API method home_timeline, as in:

api.home_timeline()

to get tweets from your home timeline¹⁶—that is, your tweets and tweets from the people you follow. This method calls Twitter’s statuses/home_timeline method.¹⁷ By default, home_timeline returns the most recent 20 tweets, but can get up to 200 at a time. Again, for more than 200 tweets from your home timeline, you should use a Tweepy Cursor to call home_timeline.