Twitter API Client Library for Java.

Note: This SDK is in beta and is not ready for production

You can find examples of using the SDK under the examples/ directory

Note: Only Twitter API V2 is supported

Twitter API v2 available endpoints

For more information, please visit https://developer.twitter.com/

Requirements

Building the API client library requires:

1. Java 1.8+
2. Maven/Gradle

Installation

To install the API client library to your local Maven repository, simply execute:

mvn clean install

To deploy it to a remote Maven repository instead, configure the settings of the repository and execute:

mvn clean deploy

Refer to the OSSRH Guide for more information.

Maven users

Add this dependency to your project's POM:

<dependency>
  <groupId>com.twitter</groupId>
  <artifactId>twitter-api-java-sdk</artifactId>
  <version>1.1.1</version>
</dependency>

Gradle users

Add this dependency to your project's build file:

implementation "com.twitter:twitter-api-java-sdk:1.1.1"

Others

At first generate the JAR by executing:

mvn clean package

Then manually install the following JARs:

• target/twitter-api-java-sdk-1.1.1.jar
• target/lib/*.jar

Twitter Credentials

Twitter APIs support three types of authentications:

• OAuth 2.0 Authorization with PKCE

TWITTER_OAUTH2_CLIENT_ID

TWITTER_OAUTH2_CLIENT_SECRET

TWITTER_OAUTH2_ACCESS_TOKEN

TWITTER_OAUTH2_REFRESH_TOKEN

TWITTER_OAUTH2_IS_AUTO_REFRESH_TOKEN - default value is false

• OAuth 2.0 Bearer Token (app-only)

TWITTER_BEARER_TOKEN

• OAuth 1.0a

TWITTER_CONSUMER_KEY

TWITTER_CONSUMER_SECRET

TWITTER_TOKEN

TWITTER_TOKEN_SECRET

You can use the following objects in order to set the credentials: TwitterCredentialsOAuth2, TwitterCredentialsBearer & TwitterCredentialsOAuth1.

TwitterApi apiInstance = new TwitterApi();
TwitterCredentialsOAuth2 credentials = new TwitterCredentialsOAuth2(System.getenv("TWITTER_OAUTH2_CLIENT_ID"),
        System.getenv("TWITTER_OAUTH2_CLIENT_SECRET"),
        System.getenv("TWITTER_OAUTH2_ACCESS_TOKEN"),
        System.getenv("TWITTER_OAUTH2_REFRESH_TOKEN"));
apiInstance.setTwitterCredentials(credentials);

Check the security tag of the required APIs in https://api.twitter.com/2/openapi.json in order to use the right credential object.

Getting Started

Please follow the installation instructions and execute the following Java code:

import java.util.HashSet;
import java.util.Set;
import com.twitter.clientlib.TwitterCredentialsOAuth2;
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) {
    /**
     * Set the credentials for the required APIs.
     * The Java SDK supports TwitterCredentialsOAuth2, TwitterCredentialsBearer & TwitterCredentialsOAuth1.
     * Check the 'security' tag of the required APIs in https://api.twitter.com/2/openapi.json in order
     * to use the right credential object.
     */
    TwitterApi apiInstance = new TwitterApi();
    TwitterCredentialsOAuth2 credentials = new TwitterCredentialsOAuth2(System.getenv("TWITTER_OAUTH2_CLIENT_ID"),
          System.getenv("TWITTER_OAUTH2_CLIENT_SECRET"),
          System.getenv("TWITTER_OAUTH2_ACCESS_TOKEN"),
          System.getenv("TWITTER_OAUTH2_REFRESH_TOKEN"));
    apiInstance.setTwitterCredentials(credentials);

    Set<String> tweetFields = new HashSet<>();
    tweetFields.add("author_id");
    tweetFields.add("id");
    tweetFields.add("created_at");

    try {
     // findTweetById
     SingleTweetLookupResponse result = apiInstance.tweets().findTweetById("20", null, tweetFields, null , null, null, null);
     if(result.getErrors() != null && result.getErrors().size() > 0) {
       System.out.println("Error:");

       result.getErrors().forEach(e -> {
         System.out.println(e.toString());
         if (e instanceof ResourceUnauthorizedProblem) {
           System.out.println(((ResourceUnauthorizedProblem) e).getTitle() + " " + ((ResourceUnauthorizedProblem) e).getDetail());
         }
       });
     } else {
       System.out.println("findTweetById - Tweet Text: " + result.toString());
     }
    } catch (ApiException e) {
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Authentication

The Twitter API has multiple authentication methods that support different endpoints. To see what method an endpoint needs go here.

This library has support for OAuth 2.0, use TwitterOAuth20Service in order to get the OAuth 2.0 services. You can see various examples on how to use the authentication in examples/

Auto Refresh Token

By default the OAuth 2.0 access token should be maintained and refreshed by the user.

In order to change it to be automatically refreshed, set the TwitterCredentialsOAuth2.isOAuth2AutoRefreshToken to be true.

You can implement the callback ApiClientCallback.onAfterRefreshToken() in order to maintain the refreshed access token.

Check this example of implementing ApiClientCallback

Documentation for API Endpoints

All URIs are relative to https://api.twitter.com

Class	Method	HTTP request	Description
BookmarksApi	getUsersIdBookmarks	GET /2/users/{id}/bookmarks	Bookmarks by User
BookmarksApi	postUsersIdBookmarks	POST /2/users/{id}/bookmarks	Add Tweet to Bookmarks
BookmarksApi	usersIdBookmarksDelete	DELETE /2/users/{id}/bookmarks/{tweet_id}	Remove a bookmarked Tweet
ComplianceApi	createBatchComplianceJob	POST /2/compliance/jobs	Create compliance job
ComplianceApi	getBatchComplianceJob	GET /2/compliance/jobs/{id}	Get compliance job
ComplianceApi	listBatchComplianceJobs	GET /2/compliance/jobs	List compliance jobs
GeneralApi	getOpenApiSpec	GET /2/openapi.json	Returns the open api spec document.
ListsApi	getUserListMemberships	GET /2/users/{id}/list_memberships	Get a User's List Memberships
ListsApi	listAddMember	POST /2/lists/{id}/members	Add a List member
ListsApi	listIdCreate	POST /2/lists	Create List
ListsApi	listIdDelete	DELETE /2/lists/{id}	Delete List
ListsApi	listIdGet	GET /2/lists/{id}	List lookup by List ID
ListsApi	listIdUpdate	PUT /2/lists/{id}	Update List
ListsApi	listRemoveMember	DELETE /2/lists/{id}/members/{user_id}	Remove a List member
ListsApi	listUserFollow	POST /2/users/{id}/followed_lists	Follow a List
ListsApi	listUserOwnedLists	GET /2/users/{id}/owned_lists	Get a User's Owned Lists
ListsApi	listUserPin	POST /2/users/{id}/pinned_lists	Pin a List
ListsApi	listUserPinnedLists	GET /2/users/{id}/pinned_lists	Get a User's Pinned Lists
ListsApi	listUserUnfollow	DELETE /2/users/{id}/followed_lists/{list_id}	Unfollow a List
ListsApi	listUserUnpin	DELETE /2/users/{id}/pinned_lists/{list_id}	Unpin a List
ListsApi	userFollowedLists	GET /2/users/{id}/followed_lists	Get User's Followed Lists
SpacesApi	findSpaceById	GET /2/spaces/{id}	Space lookup by Space ID
SpacesApi	findSpacesByCreatorIds	GET /2/spaces/by/creator_ids	Space lookup by their creators
SpacesApi	findSpacesByIds	GET /2/spaces	Space lookup up Space IDs
SpacesApi	searchSpaces	GET /2/spaces/search	Search for Spaces
SpacesApi	spaceBuyers	GET /2/spaces/{id}/buyers	Retrieve the list of users who purchased a ticket to the given space
SpacesApi	spaceTweets	GET /2/spaces/{id}/tweets	Retrieve tweets from a Space
TweetsApi	addOrDeleteRules	POST /2/tweets/search/stream/rules	Add/Delete rules
TweetsApi	createTweet	POST /2/tweets	Creation of a Tweet
TweetsApi	deleteTweetById	DELETE /2/tweets/{id}	Tweet delete by Tweet ID
TweetsApi	findTweetById	GET /2/tweets/{id}	Tweet lookup by Tweet ID
TweetsApi	findTweetsById	GET /2/tweets	Tweet lookup by Tweet IDs
TweetsApi	findTweetsThatQuoteATweet	GET /2/tweets/{id}/quote_tweets	Retrieve tweets that quote a tweet.
TweetsApi	getRules	GET /2/tweets/search/stream/rules	Rules lookup
TweetsApi	hideReplyById	PUT /2/tweets/{id}/hidden	Hide replies
TweetsApi	listsIdTweets	GET /2/lists/{id}/tweets	List Tweets timeline by List ID
TweetsApi	sampleStream	GET /2/tweets/sample/stream	Sample stream
TweetsApi	searchStream	GET /2/tweets/search/stream	Filtered stream
TweetsApi	spaceBuyers	GET /2/spaces/{id}/buyers	Retrieve the list of users who purchased a ticket to the given space
TweetsApi	spaceTweets	GET /2/spaces/{id}/tweets	Retrieve tweets from a Space
TweetsApi	tweetCountsFullArchiveSearch	GET /2/tweets/counts/all	Full archive search counts
TweetsApi	tweetCountsRecentSearch	GET /2/tweets/counts/recent	Recent search counts
TweetsApi	tweetsFullarchiveSearch	GET /2/tweets/search/all	Full-archive search
TweetsApi	tweetsRecentSearch	GET /2/tweets/search/recent	Recent search
TweetsApi	usersIdLike	POST /2/users/{id}/likes	Causes the user (in the path) to like the specified tweet
TweetsApi	usersIdLikedTweets	GET /2/users/{id}/liked_tweets	Returns Tweet objects liked by the provided User ID
TweetsApi	usersIdMentions	GET /2/users/{id}/mentions	User mention timeline by User ID
TweetsApi	usersIdRetweets	POST /2/users/{id}/retweets	Causes the user (in the path) to retweet the specified tweet
TweetsApi	usersIdTweets	GET /2/users/{id}/tweets	User Tweets timeline by User ID
TweetsApi	usersIdUnlike	DELETE /2/users/{id}/likes/{tweet_id}	Causes the user (in the path) to unlike the specified tweet
TweetsApi	usersIdUnretweets	DELETE /2/users/{id}/retweets/{source_tweet_id}	Causes the user (in the path) to unretweet the specified tweet
UsersApi	findMyUser	GET /2/users/me	User lookup me
UsersApi	findUserById	GET /2/users/{id}	User lookup by ID
UsersApi	findUserByUsername	GET /2/users/by/username/{username}	User lookup by username
UsersApi	findUsersById	GET /2/users	User lookup by IDs
UsersApi	findUsersByUsername	GET /2/users/by	User lookup by usernames
UsersApi	listGetFollowers	GET /2/lists/{id}/followers	Returns user objects that follow a List by the provided List ID
UsersApi	listGetMembers	GET /2/lists/{id}/members	Returns user objects that are members of a List by the provided List ID
UsersApi	tweetsIdLikingUsers	GET /2/tweets/{id}/liking_users	Returns user objects that have liked the provided Tweet ID
UsersApi	tweetsIdRetweetingUsers	GET /2/tweets/{id}/retweeted_by	Returns user objects that have retweeted the provided Tweet ID
UsersApi	usersIdBlock	POST /2/users/{id}/blocking	Block User by User ID
UsersApi	usersIdBlocking	GET /2/users/{id}/blocking	Returns user objects that are blocked by provided user ID
UsersApi	usersIdFollow	POST /2/users/{id}/following	Follow User
UsersApi	usersIdFollowers	GET /2/users/{id}/followers	Returns user objects that follow the provided user ID
UsersApi	usersIdFollowing	GET /2/users/{id}/following	Following by User ID
UsersApi	usersIdMute	POST /2/users/{id}/muting	Mute User by User ID
UsersApi	usersIdMuting	GET /2/users/{id}/muting	Returns user objects that are muted by the provided user ID
UsersApi	usersIdUnblock	DELETE /2/users/{source_user_id}/blocking/{target_user_id}	Unblock User by User ID
UsersApi	usersIdUnfollow	DELETE /2/users/{source_user_id}/following/{target_user_id}	Unfollow User
UsersApi	usersIdUnmute	DELETE /2/users/{source_user_id}/muting/{target_user_id}	Unmute User by User ID

Documentation for Models

• AddBookmarkRequest
• AddOrDeleteRulesRequest
• AddOrDeleteRulesResponse
• AddRulesRequest
• AnimatedGif
• AnimatedGifAllOf
• BookmarkMutationResponse
• BookmarkMutationResponseData
• CashtagEntity
• CashtagFields
• ClientDisconnectedProblem
• ClientForbiddenProblem
• ClientForbiddenProblemAllOf
• ComplianceJob
• ComplianceJobStatus
• ComplianceJobType
• ConflictProblem
• ConnectionExceptionProblem
• ConnectionExceptionProblemAllOf
• ContextAnnotation
• ContextAnnotationDomainFields
• ContextAnnotationEntityFields
• CreateBatchComplianceJobRequest
• CreateTweetRequest
• CreateTweetRequestGeo
• CreateTweetRequestMedia
• CreateTweetRequestPoll
• CreateTweetRequestReply
• DeleteRulesRequest
• DeleteRulesRequestDelete
• DisallowedResourceProblem
• DisallowedResourceProblemAllOf
• DuplicateRuleProblem
• DuplicateRuleProblemAllOf
• EntityIndicesInclusiveExclusive
• EntityIndicesInclusiveInclusive
• Error
• Expansions
• FieldUnauthorizedProblem
• FieldUnauthorizedProblemAllOf
• FilteredStreamingTweet
• FilteredStreamingTweetOneOf
• FilteredStreamingTweetOneOf1
• FilteredStreamingTweetOneOfMatchingRules
• FullTextEntities
• GenericMultipleUsersLookupResponse
• GenericMultipleUsersLookupResponseMeta
• GenericProblem
• GenericTweetsTimelineResponse
• GenericTweetsTimelineResponseMeta
• Geo
• GetRulesResponse
• Granularity
• HashtagEntity
• HashtagFields
• HideReplyByIdRequest
• HideReplyByIdResponse
• HideReplyByIdResponseData
• InvalidRequestProblem
• InvalidRequestProblemAllOf
• InvalidRequestProblemAllOfErrors
• InvalidRuleProblem
• ListAddMemberRequest
• ListCreateRequest
• ListCreateResponse
• ListDeleteResponse
• ListDeleteResponseData
• ListFollowRequest
• ListFollowedResponse
• ListFollowedResponseData
• ListLookupMultipleUsersLookupResponse
• ListLookupMultipleUsersLookupResponseMeta
• ListMemberResponse
• ListMemberResponseData
• ListPinRequest
• ListPinnedResponse
• ListPinnedResponseData
• ListUpdateRequest
• ListUpdateResponse
• ListUpdateResponseData
• ListsIdTweetsResponse
• Media
• MentionEntity
• MentionFields
• ModelList
• MultiComplianceJobResponse
• MultiListNoPaginationResponse
• MultiListNoPaginationResponseMeta
• MultiListResponse
• MultiListResponseMeta
• MultiSpaceLookupResponse
• MultiTweetLookupResponse
• MultiTweetLookupResponseMeta
• MultiUserLookupResponse
• NonCompliantRulesProblem
• OperationalDisconnectProblem
• OperationalDisconnectProblemAllOf
• Photo
• PhotoAllOf
• Place
• PlaceType
• Point
• Poll
• PollOption
• Problem
• ProblemOrError
• QuoteTweetLookupResponse
• QuoteTweetLookupResponseMeta
• ReplySettings
• ResourceNotFoundProblem
• ResourceNotFoundProblemAllOf
• ResourceUnauthorizedProblem
• ResourceUnauthorizedProblemAllOf
• ResourceUnavailableProblem
• ResourceUnavailableProblemAllOf
• Rule
• RuleNoId
• RulesCapProblem
• RulesRequestSummary
• RulesRequestSummaryOneOf
• RulesRequestSummaryOneOf1
• RulesResponseMetadata
• SearchCount
• SingleComplianceJobResponse
• SingleListLookupResponse
• SingleListLookupResponseIncludes
• SingleSpaceLookupResponse
• SingleTweetLookupResponse
• SingleUserLookupResponse
• Space
• SpaceTopics
• StreamingTweet
• Tweet
• TweetAttachments
• TweetCountsResponse
• TweetCountsResponseMeta
• TweetCreateResponse
• TweetCreateResponseData
• TweetDeleteResponse
• TweetDeleteResponseData
• TweetGeo
• TweetNonPublicMetrics
• TweetOrganicMetrics
• TweetPromotedMetrics
• TweetPublicMetrics
• TweetReferencedTweets
• TweetSearchResponse
• TweetSearchResponseMeta
• TweetWithheld
• URLFields
• URLImage
• UnsupportedAuthenticationProblem
• UrlEntity
• UsageCapExceededProblem
• UsageCapExceededProblemAllOf
• User
• UserEntities
• UserEntitiesUrl
• UserPublicMetrics
• UserWithheld
• UsersBlockingMutationResponse
• UsersBlockingMutationResponseData
• UsersFollowingCreateResponse
• UsersFollowingCreateResponseData
• UsersFollowingDeleteResponse
• UsersFollowingLookupResponse
• UsersIdBlockRequest
• UsersIdFollowRequest
• UsersIdLikedTweetsResponse
• UsersIdLikedTweetsResponseMeta
• UsersIdMuteRequest
• UsersLikesCreateRequest
• UsersLikesCreateResponse
• UsersLikesCreateResponseData
• UsersLikesDeleteResponse
• UsersMutingMutationResponse
• UsersMutingMutationResponseData
• UsersRetweetsCreateRequest
• UsersRetweetsCreateResponse
• UsersRetweetsCreateResponseData
• UsersRetweetsDeleteResponse
• Video
• VideoAllOf
• VideoAllOfNonPublicMetrics
• VideoAllOfOrganicMetrics
• VideoAllOfPromotedMetrics
• VideoAllOfPublicMetrics