A CLI tool and an API for fetching data from Twitter for free!
It is recommended to install the package globally, if you want to use it from the CLI. Use the following steps to install the package and ensure it's installed correctly:
npm install -g rettiwt-api.rettiwt help.For using the package in your own project, you can install it as a dependency.
Rettiwt-API can be used with or without logging in to Twitter. As such, the two authentication strategies are:
'Guest' authentication (without logging in) grants access to the following resources/actions:
'User' authentication (logging in) grants access to the following resources/actions:
By default, Rettiwt-API uses 'guest' authentication. If however, access to the full set of resources is required, 'user' authentication can be used. This is done by using the cookies associated with your Twitter/X account, and encoding them into an API_KEY for convenience. The said API_KEY can be obtained by using a browser extension, as follows:
Get Key button, this will generate the API_KEY and will show up in the text-area.API_KEY by either clicking on the Copy Key button or manually from the text-area.API_KEY still remains valid.API_KEY for use.Get API Key button, this will generate the API_KEY and will show up in the text-area.API_KEY by either clicking on the Copy API Key button or manually from the text-area.API_KEY still remains valid.API_KEY for use.API_KEY created in this way should last 5 years from the date of login, as long as the credentials to the account aren't changed.API_KEY to last only as long as the Twitter/X account isn't logged out of (you may exit the browser as usual) or 5 years, whichever comes first. That's why it's recommended to use incognito/in-private mode, so that the API_KEY isn't accidentially revoked by logging out.The API_KEY generated by logging in is what allows Rettiwt-API to authenticate as a logged in user while interacting with the Twitter API ('user' authentication). As such it is a very sensitive information and therefore, must be stored securely. The following points must be kept in mind while using the API_KEY for 'user' authentication:
Rettiwt-API can be used as a dependency for your NodeJS project. In such a case, it is not required to install Rettiwt-API globally and you may install it locally in the root of your project using the command:
npm install --save rettiwt-api (using npm)
or
yarn add rettiwt-api (using yarn)
However, in this case, for accessing the CLI, you will be required to prepend the CLI commands with npx in order to tell NodeJS to use the locally installed package.
When used as a dependency, the Rettiwt class is entry point for accessing the Twitter API.
A new Rettiwt instance can be initialized using the following code snippets:
const rettiwt = new Rettiwt() (for 'guest' authentication)const rettiwt = new Rettiwt({ apiKey: API_KEY }) (for 'user' authentication)The Rettiwt class has three members:
list memeber, for accessing resources related to lists.tweet member, for accessing resources related to tweets.user member, for accessing resources related to users.For details regarding usage of these members for accessing the Twitter API, refer to features.
When initializing a new Rettiwt instance, it can be configures using various parameters, namely:
apiKey (string) - The API key to use for user authentication.proxyUrl (URL) - The URL to the proxy server to use.timeout (number) - The timeout to use for HTTP requests used by Rettiwt.logging (boolean) - Whether to enable logging or not.errorHandler (interface) - The custom error handler to use.tidProvider (interface) - The custom TID provider to use for generating transaction token.headers (object) - Custom HTTP headers to append to the default headers.delay (number/function) - The delay to use between concurrent requests, can either be a number in milliseconds, or a function that returns the number.Of these parameters, the following are hot-swappable, using their respective setters:
apiKeyheadersproxyUrlThe following example demonstrates changing the API key on the fly:
import { Rettiwt } from 'rettiwt-api';
// Initializing a new Rettiwt instance with API key 1
const rettiwt = new Rettiwt({ apiKey: '<API_KEY_1>' });
rettiwt.user.details().then((res) => {
console.log(res); // Returns details of the user associated with API_KEY_1
});
// Changing API key to API key 2
rettiwt.apiKey = '<API_KEY_2>';
rettiwt.user.details().then((res) => {
console.log(res); // Returns details of the user associated with API_KEY_2
});
The following examples may help you to get started using the library:
import { Rettiwt } from 'rettiwt-api';
// Creating a new Rettiwt instance
// Note that for accessing user details, 'guest' authentication can be used
const rettiwt = new Rettiwt();
// Fetching the details of the user whose username is <username>
rettiwt.user.details('<username>')
.then(details => {
...
})
.catch(error => {
...
});
import { Rettiwt } from 'rettiwt-api';
// Creating a new Rettiwt instance using the API_KEY
const rettiwt = new Rettiwt({ apiKey: API_KEY });
/**
* Fetching the list of tweets that:
* - are made by a user with username <username>,
* - contain the words <word1> and <word2>
*/
rettiwt.tweet.search({
fromUsers: ['<username>'],
words: ['<word1>', '<word2>']
})
.then(data => {
...
})
.catch(err => {
...
});
For more information regarding the different available filter options, please refer to TweetFilter.
The previous example fetches the the list of tweets matching the given filter. Since no count is specified, in this case, a default of 20 such Tweets are fetched initially. The following example demonstrates how to use the cursor string obtained from the response object's next field, from the previous example, to fetch the next batch of tweets:
import { Rettiwt } from 'rettiwt-api';
// Creating a new Rettiwt instance using the API_KEY
const rettiwt = new Rettiwt({ apiKey: API_KEY });
/**
* Fetching the list of tweets that:
* - are made by a user with username <username>,
* - contain the words <word1> and <word2>
*
* 'data' is the response object received in the previous example.
*
* 'count' is a number less or equal to 20 (the quantity of tweets to return)
*/
rettiwt.tweet.search({
fromUsers: ['<username>'],
words: ['<word1>', '<word2>']
}, count, data.next.value)
.then(data => {
...
})
.catch(err => {
...
});
Sometimes, you might want to generate an API_KEY on the fly, in situations such as implementing Twitter login in your application. The following example demonstrates how to generate an API_KEY during runtime:
import { Rettiwt } from 'rettiwt-api';
// Creating a new Rettiwt instance
const rettiwt = new Rettiwt();
// Logging in an getting the API_KEY
rettiwt.auth.login('<email>', '<username>', '<password>')
.then(apiKey => {
// Use the API_KEY
...
})
.catch(err => {
console.log(err);
});
Where,
<email> is the email associated with the Twitter account to be logged into.<username> is the username associated with the Twitter account.<password> is the password to the Twitter account.For masking of IP address using a proxy server, use the following code snippet for instantiation of Rettiwt:
/**
* PROXY_URL is the URL or configuration for the proxy server you want to use.`
*/
const rettiwt = new Rettiwt({ apiKey: API_KEY, proxyUrl: PROXY_URL });
This creates a Rettiwt instance which uses the given proxy server for making requests to Twitter.
Sometimes, when the library shows unexpected behaviour, for troubleshooting purposes, debug logs can be enabled which will help in tracking down the issue and working on a potential fix. Currently, debug logs are printed to the console and are enabled by setting the 'logging' property of the config to true, while creating an instance of Rettiwt:
/**
* By default, is no value for 'logging' is supplied, logging is disabled.
*/
const rettiwt = new Rettiwt({ apiKey: API_KEY, logging: true });
For getting the raw data instead of the parsed results, all data models provide a getter raw which returns the raw data entity as returned by Twitter, instead of parsing them to Rettiwt's own data entity formats. The following example demonstrates the use of the raw getter:
import { Rettiwt } from 'rettiwt-api';
// Creating a new Rettiwt instance
// Note that for accessing user details, 'guest' authentication can be used
const rettiwt = new Rettiwt();
// Fetching the details of the user whose username is <username>
rettiwt.user.details('<username>')
.then(details => {
console.log(details);
// {
// "createdAt": "2021-07-24T14:25:32.000Z",
// "description": "Coder, Gamer and Tech Enthusiast",
// "followersCount": 3,
// "followingsCount": 44,
// "fullName": "Rishikant Sahu",
// "id": "1418940387037782018",
// "isVerified": false,
// "likeCount": 762,
// "profileImage": "https://abs.twimg.com/sticky/default_profile_images/default_profile_normal.png",
// "statusesCount": 5,
// "userName": "negmatico"
// }
console.log(details.raw);
// {
// "__typename": "User",
// "id": "VXNlcjoxNDE4OTQwMzg3MDM3NzgyMDE4",
// "rest_id": "1418940387037782018",
// "affiliates_highlighted_label": {},
// "has_graduated_access": true,
// "is_blue_verified": false,
// "legacy": {
// "following": false,
// "can_dm": true,
// "can_media_tag": true,
// "created_at": "Sat Jul 24 14:25:32 +0000 2021",
// "default_profile": true,
// "default_profile_image": true,
// "description": "Coder, Gamer and Tech Enthusiast",
// "entities": { "description": { "urls": [] } },
// "fast_followers_count": 0,
// "favourites_count": 762,
// "followers_count": 3,
// "friends_count": 44,
// "has_custom_timelines": false,
// "is_translator": false,
// "listed_count": 0,
// "location": "",
// "media_count": 0,
// "name": "Rishikant Sahu",
// "needs_phone_verification": false,
// "normal_followers_count": 3,
// "pinned_tweet_ids_str": [],
// "possibly_sensitive": false,
// "profile_image_url_https": "https://abs.twimg.com/sticky/default_profile_images/default_profile_normal.png",
// "profile_interstitial_type": "",
// "screen_name": "negmatico",
// "statuses_count": 5,
// "translator_type": "none",
// "verified": false,
// "want_retweets": false,
// "withheld_in_countries": []
// },
// "parody_commentary_fan_label": "None",
// "profile_image_shape": "Circle",
// "tipjar_settings": {},
// "verified_phone_status": false,
// "legacy_extended_profile": {
// "birthdate": { "day": 18, "month": 1, "year": 2001, "visibility": "Self", "year_visibility": "Self" }
// },
// "is_profile_translatable": false,
// "has_hidden_subscriptions_on_profile": false,
// "verification_info": { "is_identity_verified": false },
// "highlights_info": { "can_highlight_tweets": false, "highlighted_tweets": "0" },
// "user_seed_tweet_count": 0,
// "premium_gifting_eligible": true,
// "business_account": {},
// "creator_subscriptions_count": 0
// }
})
.catch(error => {
...
});
However, if further control over the raw response is required, Rettiwt-API provides the FetcherService class which provides direct access to the raw response, but keep in mind, this delegates the task of parsing and filtering the results to the consumer of the library. The following example demonstrates using the FetcherService class:
import { RettiwtConfig, FetcherService, EResourceType, IUserDetailsResponse } from 'rettiwt-api';
// Creating the configuration for Rettiwt
const config = new RettiwtConfig({ apiKey: '<API_KEY>' });
// Creating a new FetcherService instance using the config
const fetcher = new FetcherService(config);
// Fetching the details of the given user
fetcher
.request<IUserDetailsResponse>(EResourceType.USER_DETAILS_BY_USERNAME, { id: 'user1' })
.then((res) => {
console.log(res);
})
.catch((err) => {
console.log(err);
});
As demonstrated by the example, the raw data can be accessed by using the request method of the FetcherService class, which takes two parameters. The first parameter is the name of the requested resource, while the second is an object specifying the associated arguments required for the given resource. The complete list of resource type can be checked here. As for the resource specific argurments, they are the same as that of the methods of Rettiwt class' methods for the respective resources, but structured as an object. Notice how the FetcherService class takes the same arguments as the Rettiwt class, and the arguments have the same effects as they have in case of Rettiwt class.
FetcherService, the setters are accessed from the config object as config.apiKey = ..., config.proxyUrl = ..., etc.So far, the following operations are supported:
Rettiwt-API provides an easy to use command-line interface which does not require any programming knowledge.
By default, the CLI operates in 'guest' authentication. If you want to use 'user' authentication:
rettiwt -k <API_KEY> <command>Help for the CLI can be obtained from the CLI itself:
rettiwt helprettiwt help <command_name>The complete API reference can be found at this page.
Support this project by donating at my PayPal.