twitter2return

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

twitter2return
Parameters
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 .
options.twitter.stream 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}}
  • data.twitter.stream 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 https://apps.twitter.com/
  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.
Returns
(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

Else

  • 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

Example
var twitter2return = require('twitter2return');

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

// *** CONNECTION SETUP ***

// (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
twitter2return(options)
	.then(data => {
		console.log(data);
	}).catch(err => {
		console.error(err.message);
	});

// *** 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
options.twitter.stream = function(err, data) {
	if (err) {console.error(err)};
	console.log(data.twitter.tweets);
};

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