Suhem Parack

Posted on Apr 4, 2022

A guide to teaching with the Twitter API v2

#beginners #api #twitter

Are you an educator looking to use Twitter API in your course? In this guide, you will learn:

What is the Twitter API
Why do educators use Twitter API in their course
What type of data is available in the Twitter API
What type of classes are being taught using the Twitter API
Available access levels and which ones should your students choose
How can students get keys and tokens to connect to the Twitter API in their code
How to download Twitter data about a topic in CSV or JSON format without writing code
What tools and resources are available for students to learn about the Twitter API

Note: In this guide, wherever I use the term Twitter API, I am referring to the Twitter API v2 only which is the primary API. We will not be using the old Twitter API v1.1.

Introduction

Twitter is a platform that is used by people across the world to exchange thoughts, ideas and information with one another, using Tweets. Each Tweet consists of up to 280 characters and may include media such as links, images and videos. The Twitter API provides a programmatic way to retrieve Twitter data.

Professors at various schools around the world use Twitter API in their class to teach students:

data science, text mining, machine learning etc.
how to write code
how to work with APIs
how to work with real-world social media data

The data from the Twitter API is available in JSON format. An example of how a Tweet on Twitter is represented in JSON format is shown below:

Examples of courses that use the Twitter API

Applying for access to the Twitter API

In order to use the Twitter API, students need to get their keys and tokens. In order to do so, they need to first apply for the appropriate Twitter API access. Currently, the Twitter API v2 has 3 access levels:

Essential access

This is the fastest and recommended way for students in a classroom to get started with the Twitter API. Students can simply sign up for a developer account here and they will get instant access to the Twitter API v2 without waiting for a use-case review. This access level lets them retrieve up to 500,000 Tweets per month from the Twitter API v2. When using search functionality in the Twitter API, they can get Tweets from the last 7 days in this access level.

Elevated access

If a student in your class needs more than 500,000 Tweets per month, then they can apply for elevated access here. This does require a use-case review, which is why it takes longer to get this access. This access level lets them retrieve up to 2 million Tweets per month from the Twitter API v2. When using search functionality in the Twitter API, they can get Tweets from the last 7 days in this access level.

Academic access

If your students are part of a Masters or PhD program and have a valid research use-case, they can apply for academic access here. This does require a use-case review, which is why it takes longer to get this access and students have to provide additional documentation. This access level lets them retrieve up to 10 million Tweets per month from the Twitter API v2. When using search functionality in the Twitter API v2, they can get any public Tweet from the full archive of public Tweets dating back to 2006. They can also get advanced search operators (such as geo) that let them filter the data they want returned, more precisely.

How to get your API Keys and tokens

The steps for getting the API keys and tokens vary based on the access levels. Below are the instruction for each access-level:

Getting keys and tokens for essential access

First, you need to apply for essential access. You will be asked to verify your email as part of this process. Additionally, you need to have phone number registered with your account in order to use the API.

After you have created your account, you will be asked some basic questions:

Review and agree to the developer agreement and policy

Next, you will be asked to verify your email

You should received an email that looks like this:

Once you click confirm, you will be directed to the developer portal. You can create an app by giving it a name

Once you click Get Keys, you will be able to see your keys and bearer token. Please keep those in a safe place, as you will be using those to connect to the Twitter API v2.

Getting keys and tokens for elevated access

Complete steps for getting keys and tokens for academic access can be found here

Getting keys and tokens for academic access

Complete steps for getting keys and tokens for academic access can be found here

What if my students just want Twitter data without writing any code?

Sometimes professors don't want their students spending too much time writing code to get Twitter data using the API. Twitter recently launched the Downloader tool that lets researchers specify the search query for which they want the data, the time period and the format in which they would like the data i.e. JSON or CSV. Once specified, they can download the data and use for their assignments and projects. Learn more about how to write search queries here

Step one: Enter your academic bearer token

Step two: Create a new download

Step three: Specify your query, time range and download format

Note: The downloader tool currently works for academic access only.

Tools and resources for students to get started with the Twitter API v2

There are a lot of resources available to students looking to get started with the Twitter API v2. Some of those are listed below:

Libraries and packages

If you are looking to use the Twitter API v2 in Python, two popular libraries that you can use:

Tweepy
Twarc

If you are looking to use the Twitter API v2 in R, you can use the academictwitteR package.

Twitter also has its own first-party libraries in Java and Typescript

Getting started with academic research with the Twitter API v2 (course)

Twitter has a dedicated course on getting started with academic research using the Twitter API v2. This course includes plug-n-play code samples and cheatsheets on writing search queries etc.

Videos

Blogs and articles

Twitter Community Forums

If students have any questions about the Twitter API, they can ask on the Twitter Community Forums.

Community datasets

Many researchers share their research datasets (Tweet IDs) on Github etc. An example of such a dataset is the COVID-19-Dataset from Emily Chen. Some professors have their students hydrate such datasets using a tool like DocNow's Hydrator and use those in their classroom.

Final thoughts

I hope this guide is helpful in understanding how you can teach with the Twitter API in your classroom. If you teach a course that uses the Twitter API and have any questions, feel free to reach to me on Twitter @suhemparack and please share what course you are teaching!