A guide to working with the Twitter API v2 in Java using twitter-api-java-sdk
Tags: java, beginners, twitter, api
Published: 2022-06-17 17:54:00

[twitter-api-java-sdk](https://github.com/twitterdev/twitter-api-java-sdk/) is Twitter's official SDK for Java that supports the Twitter API v2 and the academic research product track. In this guide, we will learn how to use the various functionality available in the Twitter API v2, using this twitter-api-java-sdk.

## Prerequisite

In order to work with the Twitter API, you need to have a developer account and your API keys and tokens to connect to the API. Learn more on how to obtain these keys and tokens [here](https://developer.twitter.com/en/docs/twitter-api/getting-started/getting-access-to-the-twitter-api).

In order to work with twitter-api-java-sdk, make sure you have Java installed on your machine. If you use Maven, add the following dependency:

```xml
<dependency>
  <groupId>com.twitter</groupId>
  <artifactId>twitter-api-java-sdk</artifactId>
  <version>2.0.0</version>
</dependency>
```

For all the examples in this section, you will first need to create an instance of the TwitterApi class and pass it your bearer token. Once you have the instance set up, you will be ready to start using the various functions in this library.

```java
TwitterApi apiInstance = new TwitterApi();
TwitterCredentialsBearer credentials = new TwitterCredentialsBearer("BEARER_TOKEN");
apiInstance.setTwitterCredentials(credentials);
```

## 1. Searching for Tweets from the last 7 days

In order to search Tweets from the last 7 days, you can use the `tweetsRecentSearch` method. You will have to pass it a [search query](https://github.com/twitterdev/getting-started-with-the-twitter-api-v2-for-academic-research/blob/main/modules/5-how-to-write-search-queries.md) to specify the data that you are looking for. In the example below, we are searching for Tweets from the last 7 days that contain the term `covid` and we are excluding retweets using `-is:retweet`.

By default, in your response, you will only get the Tweet ID and Tweet text for each Tweet. If you need additional Tweet fields such as [context_annotations](https://developer.twitter.com/en/docs/twitter-api/annotations/overview), created_at (the time the tweet was created) etc., you can specifiy those fields using the tweetFields parameter, as shown in the example 2. Learn more about available fields [here](https://developer.twitter.com/en/docs/twitter-api/fields). By default, a request returns 10 Tweets. If you want more than 10 Tweets per request, you can specify that using the `maxResults` parameter. The maximum Tweets per request for this recent search endpoint is 100.

```java
import java.util.*;

import com.twitter.clientlib.TwitterCredentialsBearer;
import com.twitter.clientlib.ApiException;
import com.twitter.clientlib.api.TwitterApi;
import com.twitter.clientlib.model.*;

public class TwitterApiExample {

    public static void main(String[] args) throws ApiException {

        TwitterApi apiInstance = new TwitterApi();
        TwitterCredentialsBearer credentials = new TwitterCredentialsBearer("BEARER_TOKEN");
        apiInstance.setTwitterCredentials(credentials);

        String query = "covid -is:retweet";

        int maxResults = 100;

        TweetSearchResponse result = apiInstance.tweets().tweetsRecentSearch(query, null, null, null, null, maxResults,
                null, null, null, null, null, null, null, null, null);

        if (result.getData() != null) {
            for (Tweet tweet : result.getData()) {
                System.out.println(tweet.getId());
                System.out.println(tweet.getText());
            }

        }

    }

}
```

## 2. Searching for Tweets from the full-archive of public Tweets

If you have access to the [academic research product track](https://developer.twitter.com/en/products/twitter-api/academic-research), you can get Tweets older than 7 days i.e. from the full archive of publicly available Tweets. In order to get these Tweets, make sure to use the bearer token from an app connected to your academic project in the Twitter developer portal. You can use the `tweetsFullarchiveSearch` method and pass it the search query. As shown in the example below, you can also specify additional Tweet fields such as `created_at`, `lang` etc. that you'd like returned for your request to the Twitter API.

**Note:** Not all Tweets have context_annotations associated with them, which is why, in the sample below, we only print the context_annotations if those are available for a Tweet.

```java
import java.util.*;

import com.twitter.clientlib.TwitterCredentialsBearer;
import com.twitter.clientlib.ApiException;
import com.twitter.clientlib.api.TwitterApi;
import com.twitter.clientlib.model.*;

public class TwitterApiExample {

    public static void main(String[] args) throws ApiException {

        TwitterApi apiInstance = new TwitterApi();
        TwitterCredentialsBearer credentials = new TwitterCredentialsBearer("BEARER_TOKEN");
        apiInstance.setTwitterCredentials(credentials);

        Set<String> tweetFields = new HashSet<>(Arrays.asList("created_at", "lang", "context_annotations"));

        String query = "covid -is:retweet";

        int maxResults = 500;

        TweetSearchResponse result = apiInstance.tweets().tweetsFullarchiveSearch(query, null, null, null, null,
                maxResults, null, null, null, null, tweetFields, null, null, null, null);

        if (result.getData() != null) {
            for (Tweet tweet : result.getData()) {
                System.out.println(tweet.getId());
                if (tweet.getContextAnnotations() != null) {
                    for (ContextAnnotation contextAnnotation : tweet.getContextAnnotations()) {
                        System.out.println(contextAnnotation.getDomain().getName());
                        System.out.println(contextAnnotation.getEntity().getName());
                    }
                }
            }

        }

    }

}
```

## 3. Getting Tweets from the full-archive of public Tweets for a specific time-frame

If you want to get Tweets from the full-archive for a specific time-period, you can specify the time-period using the `startTime` and `endTime` parameters, as shown in the example below:

```java
import java.time.OffsetDateTime;

import com.twitter.clientlib.TwitterCredentialsBearer;
import com.twitter.clientlib.ApiException;
import com.twitter.clientlib.api.TwitterApi;
import com.twitter.clientlib.model.*;

public class TwitterApiExample {

    public static void main(String[] args) throws ApiException {

        TwitterApi apiInstance = new TwitterApi();
        TwitterCredentialsBearer credentials = new TwitterCredentialsBearer("BEARER_TOKEN");
        apiInstance.setTwitterCredentials(credentials);

        String query = "covid -is:retweet";

        int maxResults = 100;

        OffsetDateTime startTime = OffsetDateTime.parse("2020-01-01T00:00:00Z");

        OffsetDateTime endTime = OffsetDateTime.parse("2021-01-01T11:59:59Z");

        TweetSearchResponse result = apiInstance.tweets().tweetsFullarchiveSearch(query, startTime, endTime, null, null,
                maxResults, null, null, null, null, null, null, null, null, null);

        if (result.getData() != null) {
            for (Tweet tweet : result.getData()) {
                System.out.println(tweet.getId());
                System.out.println(tweet.getText());
            }

        }

    }

}
```

## 4. Writing Tweets to a text file

This example shows how you can write the Tweet IDs for each Tweet obtained for a search result, to a text file. Make sure to replace the `fileName` with the a name of your chosing. If you wish to write other fields to the text file, make sure to adjust the script below accordingly.

```java
import java.io.FileNotFoundException;
import java.io.PrintWriter;
import java.io.UnsupportedEncodingException;
import java.time.OffsetDateTime;
import java.util.*;

import com.twitter.clientlib.TwitterCredentialsBearer;
import com.twitter.clientlib.ApiException;
import com.twitter.clientlib.api.TwitterApi;
import com.twitter.clientlib.model.*;

public class TwitterApiExample {

    public static void main(String[] args) throws ApiException, FileNotFoundException, UnsupportedEncodingException {

        TwitterApi apiInstance = new TwitterApi();
        TwitterCredentialsBearer credentials = new TwitterCredentialsBearer("BEARER_TOKEN");
        apiInstance.setTwitterCredentials(credentials);

        String query = "covid -is:retweet";

        int maxResults = 100;

        String fileName = "tweet_ids.txt";

        TweetSearchResponse result = apiInstance.tweets().tweetsFullarchiveSearch(query, null, null, null, null,
                maxResults, null, null, null, null, null, null, null, null, null);

        if (result.getData() != null) {
            PrintWriter writer = new PrintWriter(fileName, "UTF-8");
            for (Tweet tweet : result.getData()) {
                writer.println(tweet.getId());
            }
            writer.close();
        }

    }

}
```

## 5. Getting Tweets with user information, for each Tweet

In the examples so far, we have seen how to get Tweet information for the Tweets that we have searched for. However, if you need additional information associated with the Tweet, such as the information of the user Tweeting it, you can use [expansions](https://developer.twitter.com/en/docs/twitter-api/expansions) and pass it to the `tweetsRecentSearch` method.

In this example, we want user information, which is why the value for `expansions` that we pass is `author_id`. Additionally, we will specify the `userFields` that we want returned such as profile_image_url, description (aka user's bio) etc. Learn more about available fields [here](https://developer.twitter.com/en/docs/twitter-api/fields).

From the response, we will get the users list from the `includes` object. Then, we will look up the user information for each Tweet, using the `author_id` of the Tweet.

```java
import java.util.*;

import com.twitter.clientlib.TwitterCredentialsBearer;
import com.twitter.clientlib.ApiException;
import com.twitter.clientlib.api.TwitterApi;
import com.twitter.clientlib.model.*;

public class TwitterApiExample {

    public static void main(String[] args) throws ApiException {

        TwitterApi apiInstance = new TwitterApi();
        // Replace with your own bearer token below
        TwitterCredentialsBearer credentials = new TwitterCredentialsBearer("BEARER_TOKEN");
        apiInstance.setTwitterCredentials(credentials);

        Set<String> tweetFields = new HashSet<>(Arrays.asList("created_at", "lang", "conversation_id"));

        Set<String> userFields = new HashSet<>(Arrays.asList("description", "profile_image_url"));

        Set<String> expansions = new HashSet<>(Arrays.asList("author_id"));

        // Replace with your own query below
        String query = "covid -is:retweet";

        TweetSearchResponse result = apiInstance.tweets().tweetsRecentSearch(query, null, null, null, null, 100, null,
                null, null, expansions, tweetFields, userFields, null, null, null);

        // Create a map with User ID and User Object
        Map<String, User> userMap = new HashMap<>();
        if (result.getIncludes() != null && result.getIncludes().getUsers() != null) {
            List<User> users = result.getIncludes().getUsers();
            for (User user : users) {
                userMap.put(user.getId(), user);
            }
        }

        if (result.getData() != null) {
            for (Tweet tweet : result.getData()) {
                User user = userMap.get(tweet.getAuthorId());
                System.out.println(tweet.getId());
                System.out.println(user.getUsername());
                System.out.println(user.getDescription());
            }

        }

    }

}
```

## 6. Searching for geo-tagged Tweets

Some Tweets have geographic information associated with them. The search endpoints in the Twitter API v2 support operators such as `place`, `place_country`, `bounding_box`, `point_radius` etc. (these operators are currently only available in the academic research product track) that allow you to get these geo-tagged Tweets.

In the example below, we want all Tweets that are from the country `US`, which is why we specify it in our search query using the `place_country:US` operator. Now because by default, only the Tweet ID and Tweet text are returned, we have to specify the fact that we want the geo information in our response as well. We do this by setting the `expansions` to `geo.place_id` in the `tweetsRecentSearch` method and we also specify the geo fields that we are looking for.

In our response, we get the list of places from the `includes` object, and we match on the `place_id` to get the relevant geo information associated with the Tweet (the place name in the example below)

```java
import java.util.*;

import com.twitter.clientlib.TwitterCredentialsBearer;
import com.twitter.clientlib.ApiException;
import com.twitter.clientlib.api.TwitterApi;
import com.twitter.clientlib.model.*;

public class TwitterApiExample {

    public static void main(String[] args) throws ApiException {

        TwitterApi apiInstance = new TwitterApi();
        TwitterCredentialsBearer credentials = new TwitterCredentialsBearer("BEARER_TOKEN");
        apiInstance.setTwitterCredentials(credentials);

        Set<String> tweetFields = new HashSet<>(Arrays.asList("created_at", "lang", "geo"));

        Set<String> placeFields = new HashSet<>(Arrays.asList("name", "place_type"));

        Set<String> expansions = new HashSet<>(Arrays.asList("geo.place_id"));

        String query = "covid -is:retweet place_country:US";

        TweetSearchResponse result = apiInstance.tweets().tweetsRecentSearch(query, null, null, null, null, 100, null,
                null, null, expansions, tweetFields, null, null, placeFields, null);

        // Create a map with Place ID and Place Object
        Map<String, Place> placeMap = new HashMap<>();
        if (result.getIncludes() != null && result.getIncludes().getPlaces() != null) {
            List<Place> places = result.getIncludes().getPlaces();
            for (Place place : places) {
                placeMap.put(place.getId(), place);
            }
        }

        if (result.getData() != null) {
            for (Tweet tweet : result.getData()) {
                Place place = placeMap.get(tweet.getGeo().getPlaceId());
                System.out.println(tweet.getId());
                System.out.println(place.getName());
            }

        }

    }

}
```

## 7. Getting Tweet counts (volume) for a search query

So far, we have seen examples of how to get Tweets for a search query. However, if you want to get the count of Tweets (volume) for a search term, you can use the `tweetCountsRecentSearch` function. You can pass it the search `query` and specify the `granularity` for the data aggregation e.g. if you want the daily count, hourly count or 15-minute count for a search term.

```java
import com.twitter.clientlib.TwitterCredentialsBearer;
import com.twitter.clientlib.ApiException;
import com.twitter.clientlib.api.TwitterApi;
import com.twitter.clientlib.model.*;

public class TwitterApiExample {

    public static void main(String[] args) throws ApiException {

        TwitterApi apiInstance = new TwitterApi();
        TwitterCredentialsBearer credentials = new TwitterCredentialsBearer("BEARER_TOKEN");
        apiInstance.setTwitterCredentials(credentials);

        String query = "covid -is:retweet";

        TweetCountsResponse result = apiInstance.tweets().tweetCountsRecentSearch(query, null, null, null, null, null,
                null, Granularity.DAY);

        if (result.getData() != null) {
            for (SearchCount searchCount : result.getData()) {
                System.out.println(searchCount.getTweetCount());
            }

        }

    }

}
```

## 8. Getting a user's timeline

In order to get the most recent 3200 Tweets from a user's timeline, we can use the `usersIdTweets` method and pass it the user id. We can also specify additional fields that we want using the `tweetFields` and `expansions` (as shown in the examples above).

```java
import com.twitter.clientlib.TwitterCredentialsBearer;
import com.twitter.clientlib.ApiException;
import com.twitter.clientlib.api.TwitterApi;
import com.twitter.clientlib.model.*;

public class TwitterApiExample {

    public static void main(String[] args) throws ApiException {

        TwitterApi apiInstance = new TwitterApi();
        TwitterCredentialsBearer credentials = new TwitterCredentialsBearer("BEARER_TOKEN");
        apiInstance.setTwitterCredentials(credentials);

        String userID = "2244994945";

        int maxResults = 100;

        GenericTweetsTimelineResponse result = apiInstance.tweets().usersIdTweets(userID, null, null, maxResults, null,
                null, null, null, null, null, null, null, null, null);

        if (result.getData() != null) {
            for (Tweet tweet : result.getData()) {
                System.out.println(tweet.getId());
            }
        }

    }

}
```

## 9. Getting a user's mentions

In order to get the most recent 3200 mentions for a user, we can use the `get_users_musersIdMentionsentions` method and pass it the user id. We can also specify additional fields that we want using the `tweetFields` and `expansions` (as shown in the examples above).

```java
import com.twitter.clientlib.TwitterCredentialsBearer;
import com.twitter.clientlib.ApiException;
import com.twitter.clientlib.api.TwitterApi;
import com.twitter.clientlib.model.*;

public class TwitterApiExample {

    public static void main(String[] args) throws ApiException {

        TwitterApi apiInstance = new TwitterApi();
        TwitterCredentialsBearer credentials = new TwitterCredentialsBearer("BEARER_TOKEN");
        apiInstance.setTwitterCredentials(credentials);

        String userID = "2244994945";

        int maxResults = 100;

        GenericTweetsTimelineResponse result = apiInstance.tweets().usersIdMentions(userID, null, null, maxResults,
                null, null, null, null, null, null, null, null, null);

        if (result.getData() != null) {
            for (Tweet tweet : result.getData()) {
                System.out.println(tweet.getId());
            }
        }

    }

}
```

## 10. Getting a user's followers

In order to get the followers of a user, we can use the `usersIdFollowers` function and pass it the user ID. If we want additional fields for the User object such as `profile_image_url`, we can specify those using the `userFields` parameter.

```java
import com.twitter.clientlib.TwitterCredentialsBearer;
import com.twitter.clientlib.ApiException;
import com.twitter.clientlib.api.TwitterApi;
import com.twitter.clientlib.model.*;

public class TwitterApiExample {

    public static void main(String[] args) throws ApiException {

        TwitterApi apiInstance = new TwitterApi();
        TwitterCredentialsBearer credentials = new TwitterCredentialsBearer("BEARER_TOKEN");
        apiInstance.setTwitterCredentials(credentials);

        String userID = "2244994945";

        GenericMultipleUsersLookupResponse result = apiInstance.users().usersIdFollowers(userID, null, null);

        if (result.getData() != null) {
            for (User user : result.getData()) {
                System.out.println(user.getId());
                System.out.println(user.getUsername());
            }
        }

    }

}
```

## 11. Getting users that a user follows

In order to get the list of users that a user follows, we can use the `usersIdFollowing` function and pass it the user ID. If we want additional fields for the User object such as `profile_image_url`, we can specify those using the `userFields` parameter.

```java
import com.twitter.clientlib.TwitterCredentialsBearer;
import com.twitter.clientlib.ApiException;
import com.twitter.clientlib.api.TwitterApi;
import com.twitter.clientlib.model.*;

public class TwitterApiExample {

    public static void main(String[] args) throws ApiException {

        TwitterApi apiInstance = new TwitterApi();
        TwitterCredentialsBearer credentials = new TwitterCredentialsBearer("BEARER_TOKEN");
        apiInstance.setTwitterCredentials(credentials);

        String userID = "2244994945";

        UsersFollowingLookupResponse result = apiInstance.users().usersIdFollowing(userID, null, null);

        if (result.getData() != null) {
            for (User user : result.getData()) {
                System.out.println(user.getId());
                System.out.println(user.getUsername());
            }
        }

    }

}
```

## 12. Getting users that like a Tweet

In order to get the list of users that like a Tweet, we can use the `tweetsIdLikingUsers` function and pass it the Tweet ID. If we want additional fields for the User object such as `profile_image_url`, we can specify those using the `userFields` parameter.

```java
import com.twitter.clientlib.TwitterCredentialsBearer;
import com.twitter.clientlib.ApiException;
import com.twitter.clientlib.api.TwitterApi;
import com.twitter.clientlib.model.*;

public class TwitterApiExample {

    public static void main(String[] args) throws ApiException {

        TwitterApi apiInstance = new TwitterApi();
        TwitterCredentialsBearer credentials = new TwitterCredentialsBearer("BEARER_TOKEN");
        apiInstance.setTwitterCredentials(credentials);

        String tweetId = "20";

        GenericMultipleUsersLookupResponse result = apiInstance.users().tweetsIdLikingUsers(tweetId, null, null);

        if (result.getData() != null) {
            for (User user : result.getData()) {
                System.out.println(user.getId());
                System.out.println(user.getUsername());
            }
        }

    }

}
```

## 13. Getting users that retweeted a Tweet

In order to get the list of users that retweeted a Tweet, we can use the `tweetsIdRetweetingUsers` function and pass it the Tweet ID. If we want additional fields for the User object such as `profile_image_url`, we can specify those using the `userFields` parameter.

```java
import com.twitter.clientlib.TwitterCredentialsBearer;
import com.twitter.clientlib.ApiException;
import com.twitter.clientlib.api.TwitterApi;
import com.twitter.clientlib.model.*;

public class TwitterApiExample {

    public static void main(String[] args) throws ApiException {

        TwitterApi apiInstance = new TwitterApi();
        TwitterCredentialsBearer credentials = new TwitterCredentialsBearer("BEARER_TOKEN");
        apiInstance.setTwitterCredentials(credentials);

        String tweetId = "20";

        GenericMultipleUsersLookupResponse result = apiInstance.users().tweetsIdRetweetingUsers(tweetId, null, null);

        if (result.getData() != null) {
            for (User user : result.getData()) {
                System.out.println(user.getId());
                System.out.println(user.getUsername());
            }
        }

    }

}
```

## 14. Getting Tweets that a user liked

In order to get the list of Tweets that a user liked, we can use the `usersIdLikedTweets` function and pass it the User ID. If we want additional fields for the Tweet object such as `context_annotations`, `created_at` etc. we can specify those using the `tweetFields` parameter.

```java
import com.twitter.clientlib.TwitterCredentialsBearer;
import com.twitter.clientlib.ApiException;
import com.twitter.clientlib.api.TwitterApi;
import com.twitter.clientlib.model.*;

public class TwitterApiExample {

    public static void main(String[] args) throws ApiException {

        TwitterApi apiInstance = new TwitterApi();
        TwitterCredentialsBearer credentials = new TwitterCredentialsBearer("BEARER_TOKEN");
        apiInstance.setTwitterCredentials(credentials);

        String userId = "2244994945";

        UsersIdLikedTweetsResponse result = apiInstance.tweets().usersIdLikedTweets(userId, null, null, null, null,
                null, null, null, null);

        if (result.getData() != null) {
            for (Tweet tweet : result.getData()) {
                System.out.println(tweet.getId());
            }
        }

    }

}
```

## 15. Lookup Tweets using Tweet IDs

In some cases, if we have a list of Tweet IDs and want to build the Tweet dataset for these Tweet IDs, we can use the `findTweetsById` function and pass it the list of Tweet IDs. By default, only the Tweet ID and Tweet text are returned. If we want additional Tweet fields, we can specify those using `tweetFields` parameter.

```java
import com.twitter.clientlib.TwitterCredentialsBearer;
import com.twitter.clientlib.ApiException;
import com.twitter.clientlib.api.TwitterApi;
import com.twitter.clientlib.model.*;

import java.util.Arrays;
import java.util.HashSet;
import java.util.List;
import java.util.Set;

public class TwitterApiExample {

    public static void main(String[] args) throws ApiException {

        TwitterApi apiInstance = new TwitterApi();
        TwitterCredentialsBearer credentials = new TwitterCredentialsBearer("BEARER_TOKEN");
        apiInstance.setTwitterCredentials(credentials);

        List<String> tweetIds = Arrays.asList("1460323737035677698", "1519781379172495360", "1519781381693353984");

        Set<String> tweetFields = new HashSet<>(Arrays.asList("created_at", "lang", "context_annotations"));

        MultiTweetLookupResponse result = apiInstance.tweets().findTweetsById(tweetIds, null, tweetFields, null, null,
                null, null);

        if (result.getData() != null) {
            for (Tweet tweet : result.getData()) {
                System.out.println(tweet.getId());
                System.out.println(tweet.getLang());
                System.out.println(tweet.getCreatedAt().toString());
            }
        }

    }

}
```

These are some common examples of working with the Twitter API v2 using twitter-api-java-sdk.

If you have any questions or feedback about this guide, please feel free to reach out to me on [Twitter](https://twitter.com/suhemparack)!