Extract data from the Twitter Application Programming Interface (API).

options (Object = {}) options for this function.
Name Description
options.twitter Object (default {}) options for twitter .
options.twitter.method Object (default process.env.TWITTER_METHOD||'get') Twitter API request method in lowercase letters ('get', 'post', 'delete', or 'stream').
options.twitter.path Object (default process.env.TWITTER_PATH||'search/tweets') Twitter API endpoint path (such as 'search/tweets' for 'get' or 'statuses/filter' for 'stream').
options.twitter.params Object (default process.env.TWITTER_PARAMS||{q:'twitter'}) Twitter API parameters for the options.twitter.method and options.twitter.path . function (default function(err,data){}) callback function on a stream 'data' event for the returned Twitter stream .
  • err is the Error object (unused in this case)
  • data is in the form of {twitter: {stream: stream, tweets: Object}}
  • is the twitter stream
  • data.twitter.tweets are the tweets in JSON format
options.twitter.connection Object (default {}) Twitter API connection credentials:
  1. Login at
  2. Create a new application
  3. Go to your applications
  4. Click on your created application
  5. Click on Keys and Access Tokens
  6. Keep note of the following:
  • Consumer Key (API Key)
  • Consumer Secret (API Secret)
  • Access Token
  • Access Token Secret
options.twitter.connection.consumer_key string (default process.env.TWITTER_CONSUMER_KEY) Twitter API Consumer Key (API Key) .
options.twitter.connection.consumer_secret string (default process.env.TWITTER_CONSUMER_SECRET) Twitter API Consumer Secret (API Secret) .
options.twitter.connection.access_token_key string (default process.env.TWITTER_ACCESS_TOKEN_KEY) Twitter API Access Token Key .
options.twitter.connection.access_token_secret string (default process.env.TWITTER_ACCESS_TOKEN_SECRET) Twitter API Access Token Secret .
options.twitter.connection.bearer_token string (default process.env.TWITTER_BEARER_TOKEN) Twitter API Bearer Token .
options.jsonata string (default process.env.JSONATA) jsonata query for the received tweet object in JSON format before returning the tweet data.
(Promise | stream): Returns a stream if options.twitter.method is 'stream', otherwise returns a Promise:

If options.twitter.method == 'stream'

  • Return a Twitter stream
  • stream.on('data', function): calls function when a tweet is available
  • stream.on('error', function): calls function when there is an error


  • Return a Promise object that resolves a data object in the form {twitter: {client: ..., tweets: ...}}

  • data.twitter.client: contains a Twitter client object created from options.twitter.connection

  • data.twitter.tweets: contains the tweets in JSON format

var twitter2return = require('twitter2return');

// (options) Initialize options object
var options = {twitter: {}};


// (options_twitter_connection) Twitter API connection keys
options.twitter.connection =  {
	consumer_key: '***', // process.env.TWITTER_CONSUMER_KEY
	consumer_secret: '***', // process.env.TWITTER_CONSUMER_SECRET
	access_token_key: '***', // process.env.TWITTER_ACCESS_TOKEN_KEY
	access_token_secret: '***' // process.env.TWITTER_ACCESS_TOKEN_SECRET

// *** SEARCH TWEETS ***

// (options_twitter_rest) Search for keyword 'twitter' in path 'GET search/tweets'
options.twitter.method = 'get'; // get, post, or stream
options.twitter.path = 'search/tweets'; // api path
options.twitter.params = {q: 'twitter'}; // query tweets

// (options_jsonata) Filter for statuses array using jsonata
options.jsonata = 'statuses';

// (twitter2return_rest) Query tweets using REST API
	.then(data => {
	}).catch(err => {

// *** STREAM TWEETS ***

// (options_twitter_connection) Track keyword 'twitter' in path 'POST statuses/filter'
options.twitter.method = 'stream'; // get, post, or stream
options.twitter.path = 'statuses/filter'; // api path
options.twitter.params = {track: 'twitter'}; // query tweets

// (options_jsonata) Remove jsonata filter
delete options.jsonata;

// (options_twitter_stream) Log the tweets when received = function(err, data) {
	if (err) {console.error(err)};

// (twitter2return_stream) Stream tweets
var stream = twitter2return(options);
stream.on('error', function(error) {