twitter_api_v2 2.4.0

The lightweight and powerful wrapper library for Twitter API v2.0 written in Dart language. It works cross-platform.

The Lightweight and Cross-Platform Wrapper for Twitter API v2.0 🐦

---

---

• 1. Guide
  • 1.1. Getting Started
    • 1.1.1. Install Library
    • 1.1.2. Import
    • 1.1.3. Implementation
  • 1.2. Supported Endpoints and Matrix
    • 1.2.1. Tweets Service
    • 1.2.2. Users Service
    • 1.2.3. Spaces Service
    • 1.2.4. Lists Service
    • 1.2.5. Compliance Service
  • 1.3. Tips
    • 1.3.1. Method Names
    • 1.3.2. Generate App-Only Bearer Token
    • 1.3.3. Null Parameter at Request
    • 1.3.4. Expand Object Fields with expansions
    • 1.3.5. Expand Object Fields with fields
  • 1.4. Contribution
  • 1.5. Support
  • 1.6. License
  • 1.7. More Information

1. Guide

This library provides the easiest way to use Twitter API v2.0 in Dart and Flutter apps.

Show some ❤️ and star the repo to support the project.

1.1. Getting Started

1.1.1. Install Library

With Dart:

 dart pub add twitter_api_v2

Or With Flutter:

 flutter pub add twitter_api_v2

1.1.2. Import

import 'package:twitter_api_v2/twitter_api_v2';

1.1.3. Implementation

void main() async {
  //! You need to get keys and tokens at https://developer.twitter.com
  final twitter = v2.TwitterApi(
    //! Authentication with OAuth2.0 is the default.
    //!
    //! Note that to use endpoints that require certain user permissions,
    //! such as Tweets and Likes, you need a token issued by OAuth2.0 PKCE.
    bearerToken: 'YOUR_TOKEN_HERE',

    //! Or perhaps you would prefer to use the good old OAuth1.0a method
    //! over the OAuth2.0 PKCE method. Then you can use the following code
    //! to set the OAuth1.0a tokens.
    //!
    //! However, note that some endpoints cannot be used for OAuth 1.0a method
    //! authentication.
    oauthTokens: v2.OAuthTokens(
      consumerKey: 'YOUR_CONSUMER_KEY_HERE',
      consumerSecret: 'YOUR_CONSUMER_SECRET_HERE',
      accessToken: 'YOUR_ACCESS_TOKEN_HERE',
      accessTokenSecret: 'YOUR_ACCESS_TOKEN_SECRET_HERE',
    ),
  );

  try {
    // Get the authenticated user's profile.
    final me = await twitter.usersService.lookupMe();
    // Get the tweets associated with the search query.
    final tweets = await twitter.tweetsService.searchRecent(
      query: '#ElonMusk',
      maxResults: 20,
      // You can expand the search result.
      expansions: [
        v2.TweetExpansion.authorId,
        v2.TweetExpansion.inReplyToUserId,
      ],
      tweetFields: [
        v2.TweetField.conversationId,
        v2.TweetField.publicMetrics,
      ],
      userFields: [
        v2.UserField.location,
        v2.UserField.verified,
        v2.UserField.entities,
        v2.UserField.publicMetrics,
      ],
    );

    await twitter.tweetsService.createLike(
      userId: me.data.id,
      tweetId: tweets.data.first.id,
    );

    // High-performance Volume Stream endpoint is available.
    final volumeStream = await twitter.tweetsService.connectVolumeStream();
    await for (final response in volumeStream.handleError(print)) {
      print(response);
    }

    // Also high-performance Filtered Stream endpoint is available.
    await twitter.tweetsService.createFilteringRules(
      rules: [
        v2.FilteringRuleData(value: '#ElonMusk'),
        v2.FilteringRuleData(value: '#Tesla'),
        v2.FilteringRuleData(value: '#SpaceX'),
      ],
    );

    final filteredStream = await twitter.tweetsService.connectFilteredStream();
    await for (final response in filteredStream.handleError(print)) {
      print(response);
    }
  } on v2.TwitterException catch (e) {
    print(e.response.headers);
    print(e.body);
    print(e);
  }
}

1.2. Supported Endpoints and Matrix

1.2.1. Tweets Service

1. Manage Tweet

   Endpoint	Method Name
   POST /2/tweets	createTweet
   DELETE /2/tweets/:id	destroyTweet

2. Likes

   Endpoint	Method Name
   POST /2/users/:id/likes	createLike
   DELETE /2/users/:id/likes/:tweet_id	destroyLike
   GET /2/tweets/:id/liking_users	lookupLikingUsers
   GET /2/users/:id/liked_tweets	lookupLikedTweets

3. Retweets

   Endpoint	Method Name
   POST /2/users/:id/retweets	createRetweet
   DELETE /2/users/:id/retweets/:source_tweet_id	destroyRetweet
   GET /2/tweets/:id/retweeted_by	lookupRetweetedUsers

4. Quote Tweets

   Endpoint	Method Name
   GET /2/tweets/:id/quote_tweets	lookupQuoteTweets

5. Search Tweets

   Endpoint	Method Name
   GET /2/tweets/search/all	searchAll
   GET /2/tweets/search/recent	searchRecent

6. Lookup Tweets

   Endpoint	Method Name
   GET /2/tweets	lookupByIds
   GET /2/tweets/:id	lookupById

7. Tweet Counts

   Endpoint	Method Name
   GET /2/tweets/counts/all	countAll
   GET /2/tweets/counts/recent	countRecent

8. Bookmarks

   Endpoint	Method Name
   POST /2/users/:id/bookmarks	createBookmark
   DELETE /2/users/:id/bookmarks/:tweet_id	destroyBookmark
   GET /2/users/:id/bookmarks	lookupBookmarks

9. Timelines

   Endpoint	Method Name
   GET /2/users/:id/mentions	lookupMentions
   GET /2/users/:id/tweets	lookupTweets
   GET /2/users/:id/timelines/reverse_chronological	lookupHomeTimeline

10. Hide Replies

    Endpoint	Method Name
    PUT /2/tweets/:id/hidden	createHiddenReply
    PUT /2/tweets/:id/hidden	destroyHiddenReply

11. Volume Stream

    Endpoint	Method Name
    GET /2/tweets/sample/stream	connectVolumeStream

12. Filtered Stream

    Endpoint	Method Name
    POST /2/tweets/search/stream/rules	createFilteringRules
    GET /2/tweets/search/stream/rules	lookupFilteringRules
    GET /2/tweets/search/stream	connectFilteredStream

1.2.2. Users Service

1. Follows

   Endpoint	Method Name
   POST /2/users/:id/following	createFollow
   DELETE /2/users/:source_user_id/following/:target_user_id	destroyFollow
   GET /2/users/:id/followers	lookupFollowers
   GET /2/users/:id/following	lookupFollowings

2. Lookup Users

   Endpoint	Method Name
   GET /2/users	lookupByIds
   GET /2/users/:id	lookupById
   GET /2/users/by	lookupByNames
   GET /2/users/by/username/:username	lookupByName
   GET /2/users/me	lookupMe

3. Users Mutes

   Endpoint	Method Name
   POST /2/users/:id/muting	createMute
   DELETE /2/users/:source_user_id/muting/:target_user_id	destroyMute
   GET /2/users/:id/muting	lookupMutingUsers

4. Blocks

   Endpoint	Method Name
   POST /2/users/:id/blocking	createBlock
   DELETE /2/users/:source_user_id/blocking/:target_user_id	destroyBlock
   GET /2/users/:id/blocking	lookupBlockingUsers

1.2.3. Spaces Service

1. Search Spaces

   Endpoint	Method Name
   GET /2/spaces/search	search

2. Lookup Spaces

   Endpoint	Method Name
   GET /2/spaces	lookupByIds
   GET /2/spaces/:id	lookupById
   GET /2/spaces/:id/buyers	lookupBuyers
   GET /2/spaces/:id/tweets	lookupTweets
   GET /2/spaces/by/creator_ids	lookupByCreatorIds

1.2.4. Lists Service

1. Lookup Lists

   Endpoint	Method Name
   GET /2/lists/:id	lookupById
   GET /2/users/:id/owned_lists	lookupOwnedBy

2. Pinnings

   Endpoint	Method Name
   POST /2/users/:id/pinned_lists	createPinnedList
   DELETE /2/users/:id/pinned_lists/:list_id	destroyPinnedList
   GET /2/users/:id/pinned_lists	lookupPinnedLists

3. Tweet Lookup

   Endpoint	Method Name
   GET /2/lists/:id/tweets	lookupTweets

4. Manage

   Endpoint	Method Name
   POST /2/lists	createPublicList
   POST /2/lists	createPrivateList
   DELETE /2/lists/:id	destroyList
   PUT /2/lists/:id	updateListAsPublic
   PUT /2/lists/:id	updateListAsPrivate

5. Follows

   Endpoint	Method Name
   POST /2/users/:id/followed_lists	createFollow
   DELETE /2/users/:id/followed_lists/:list_id	destroyFollow
   GET /2/lists/:id/followers	lookupFollowers
   GET /2/users/:id/followed_lists	lookupFollowedLists

6. Members

   Endpoint	Method Name
   POST /2/lists/:id/members	createMember
   DELETE /2/lists/:id/members/:user_id	destroyMember
   GET /2/lists/:id/members	lookupMembers
   GET /2/users/:id/list_memberships	lookupMemberships

1.2.5. Compliance Service

1. Batch Compliance

   Endpoint	Method Name
   POST /2/compliance/jobs	createJob
   GET /2/compliance/jobs	lookupJobs
   GET /2/compliance/jobs/:id	lookupJob

Note
Not all additional fields listed in the official documentation are supported. We intend to support them step by step. Also you can create an Issue or Pull Request if you wish to suggest or contribute!

1.3. Tips

1.3.1. Method Names

twitter_api_v2 uses the following standard prefixes depending on endpoint characteristics. It's very easy to find the method corresponding to the endpoint you want to use!

Prefix	Description
lookup	This prefix is attached to the endpoint performing the search. However, it's distinguished from the higher-performance Search endpoint.
search	This prefix is attached to high-performance Search endpoints.
connect	This prefix is attached to the endpoint performing the high-performance streaming.
count	This prefix is attached to the endpoint that counts tweets, etc.
create	This prefix is attached to the endpoint performing the create state such as Tweet and Follow.
destroy	This prefix is attached to the endpoint performing the destroy state such as Tweet and Follow.
update	This prefix is attached to the endpoint performing the update state.

1.3.2. Generate App-Only Bearer Token

twitter_api_v2 provides utility to generate/find your app-only bearer token.

import 'package:twitter_api_v2/twitter_api_v2.dart' as v2;

void main() async {
  final bearerToken = await v2.OAuthUtils.generateAppOnlyBearerToken(
    consumerKey: 'YOUR_CONSUMER_KEY',
    consumerSecret: 'YOUR_CONSUMER_SECRET',
  );

  print(bearerToken);
}

1.3.3. Null Parameter at Request

In this library, parameters that are not required at request time, i.e., optional parameters, are defined as nullable. However, developers do not need to be aware of the null parameter when sending requests when using this library.

It means the parameters specified with a null value are safely removed and ignored before the request is sent.

For example, arguments specified with null are ignored in the following request.

import 'package:twitter_api_v2/twitter_api_v2.dart' as v2;

void main() async {
  final twitter = v2.TwitterApi(bearerToken: 'YOUR_TOKEN_HERE');

  await twitter.tweetsService.createTweet(
    text: 'Hello, World!',
    // These parameters are ignored at request because they are null.
    mediaIds: null,
    expansions: null,
  );
}

1.3.4. Expand Object Fields with expansions

For example, there may be a situation where data contains only an ID, and you want to retrieve the data object associated with that ID as well. In such cases, the Twitter API v2.0 specification called expansions is useful, and this library supports that specification.

Basically it can be used in endpoints that perform GET communication such as lookup and search processing. Some fields may also be included in the includes property of TwitterResponse.

You can use expansions like below:

import 'package:twitter_api_v2/twitter_api_v2.dart' as v2;

void main() async {
  final twitter = v2.TwitterApi(bearerToken: 'YOUR_TOKEN_HERE');

  try {
    final tweets = await twitter.tweetsService.searchRecent(
      query: '#ElonMusk',
      // Specify fields you need!
      expansions: [
        v2.TweetExpansion.authorId,
        v2.TweetExpansion.inReplyToUserId,
      ],
    );

    print(tweets);
  } on v2.TwitterException catch (e) {
    print(e);
  }
}

You can see more details about expansions from Official Documentation.

1.3.5. Expand Object Fields with fields

Twitter API v2.0 supports a very interesting specification, allowing users to control the amount of data contained in the response object for each endpoint depending on the situation. It's called fields, and this library supports this specification.

Basically it can be used in endpoints that perform GET communication such as lookup and search processing. Some fields may also be included in the includes property of TwitterResponse.

You can use fields like below:

import 'package:twitter_api_v2/twitter_api_v2.dart' as v2;

void main() async {
  final twitter = v2.TwitterApi(bearerToken: 'YOUR_TOKEN_HERE');

  try {
    final tweets = await twitter.tweetsService.searchRecent(
      query: '#ElonMusk',
      maxResults: 20,
      expansions: v2.TweetExpansion.values,
      tweetFields: [
        v2.TweetField.conversationId,
        v2.TweetField.publicMetrics,
      ],
      userFields: [
        v2.UserField.location,
        v2.UserField.publicMetrics,
      ],
    );

    print(tweets);
  } on v2.TwitterException catch (e) {
    print(e);
  }
}

Note
Some fields must be combined with expansions.

You can see more details about fields from Official Documentation.

1.4. Contribution

If you would like to contribute to twitter_api_v2, please create an issue or create a Pull Request.

There are many ways to contribute to the OSS. For example, the following subjects can be considered:

• There are request parameters or response fields that are not implemented.
• Documentation is outdated or incomplete.
• Have a better way or idea to achieve the functionality.
• etc...

You can see more details from resources below:

• Contributor Covenant Code of Conduct
• Contribution Guidelines
• Style Guide

Or you can create a discussion if you like.

Feel free to join this development, diverse opinions make software better!

1.5. Support

The simplest way to show us your support is by giving the project a star at GitHub and Pub.dev.

You can also support this project by becoming a sponsor on GitHub:

You can also show on your repository that your app is made with twitter_api_v2 by using one of the following badges:

[![Powered by twitter_api_v2](https://img.shields.io/badge/Powered%20by-twitter_api_v2-00acee.svg)](https://github.com/twitter-dart/twitter-api-v2)
[![Powered by twitter_api_v2](https://img.shields.io/badge/Powered%20by-twitter_api_v2-00acee.svg?style=flat-square)](https://github.com/twitter-dart/twitter-api-v2)
[![Powered by twitter_api_v2](https://img.shields.io/badge/Powered%20by-twitter_api_v2-00acee.svg?style=for-the-badge)](https://github.com/twitter-dart/twitter-api-v2)

1.6. License

All resources of twitter_api_v2 is provided under the BSD-3 license.

Note
License notices in the source are strictly validated based on .github/header-checker-lint.yml. Please check header-checker-lint.yml for the permitted standards.

1.7. More Information

twitter_api_v2 was designed and implemented by Kato Shinya (@myConsciousness).

• Creator Profile
• License
• API Document
• Release Note
• Bug Report