Creating a Twitter Collection via API

Ever wanted a nice timeline view of all of your favorite tweets?! Collections are for you! The end result will look something like this:

Example collection. Can also be viewed here: https://twitter.com/laurenfratamico/timelines/1180945428222595074

This tutorial goes through how to create and add to collections via python3, and the code can be seen in a gist here.

Getting Started

You’ll need both a Twitter account and a Twitter developer account. You can obtain the developer account here. You’ll then need to create an app in order to obtain all the necessary API keys and tokens, as seen below. Note that you should have both read and write access. Sometimes this will require applying for access (including verifying your phone number and answering a few short response questions), but it seems Twitter instantly approves these requests.

Authenticating with Twitter

Now that you have all 4 API keys and tokens, we can set up the Twitter OAuth session which will be needed for creating and adding to collections.

import json
from requests_oauthlib import OAuth1Session
api_key = 'your api key'
api_secret_key = 'your api secret key'
access_token = 'your access token'
access_token_secret = 'your access token secret'
# twitter oauth
twitter = OAuth1Session(api_key,
                        client_secret=api_secret_key,
                        resource_owner_key=access_token,
                        resource_owner_secret=access_token_secret)

Creating a Collection

Now that Twitter OAuth is setup, a collection can be created by hitting the creations/create endpoint.

# create
url = 'https://api.twitter.com/1.1/collections/create.json'
params_create = {
    'name': 'cutest puppies EVER',
    'timeline_order': 'tweet_reverse_chron'
}
r = twitter.post(url, data=params_create)
# print the full returned json to ensure success
print(r.json())
# print the response to get the id of the timeline created. This is needed for adding/removing tweets
print(r.json()['response'])

Be sure to save the timeline_id, which will be something like custom-1180945428222595074. But if you forgot what your timeline_id is, it can always be retrieved later via the collections/list endpoint. This timeline id will also enable you to view your collection on the web via a URL of the form: https://twitter.com/[user’s twitter handle]/timelines/[timeline id], eg https://twitter.com/laurenfratamico/timelines/1180945428222595074.

Additionally, collections will always cary the same permissions as the user who created them, meaning that if the creating user is a protected account, others will need to be following them in order to view the collection.

Adding Tweets to a Collection

Adding tweets is done via the collections/entries/add endpoint, as seen below:

tweet_ids = [1148286877616803840, 1180845365542752256, 1180123991165607937, 1158830129080098823]
# add
url = 'https://api.twitter.com/1.1/collections/entries/add.json'
for tweet_id in tweet_ids:
    params_add = {
        'tweet_id': tweet_id,
        'id': 'custom-1180945428222595074'
    }
    r = twitter.post(url, data=params_add)
    print(r.json())

Bulk Adding Tweets to a Collection

Because Twitter has rate limiting, and limits you to ~180 calls per 15 minutes, it can be useful to use the bulk endpoint instead. This allows you to operate on up to 100 tweets per API call. Below is how to bulk add tweets to your collection:

# bulk add
url = 'https://api.twitter.com/1.1/collections/entries/curate.json'
# split into batches of 100 for the uploads
n = 100
batches = [tweet_ids[i:i + n] for i in range(0, len(tweet_ids), n)]
print (len(batches))
for batch in batches:
    params_add = {
        "id": "custom-1180945428222595074",
        "changes": []
    }
    for tweet_id in batch:
        sub_params_add = {
            "tweet_id": str(tweet_id),
            "op": "add"
        }
        params_add['changes'].append(sub_params_add)
    
    r = twitter.post(url, data=json.dumps(params_add))
    print(r.json())

Other useful collections endpoints

There are a number of other useful endpoints, including the ability to list all tweets in a given collection, list all collections of a given user, destroy a collection, and remove tweets.

Limitations

Collections are great for creating timelines of even large numbers of tweets. I couldn’t find any documentation on the max number of tweets allowed in a collection, but empirically it seems to be around 25k.