twitter2return

twitter2return

Richard Wen
[e-mail]

• Documentation

Module for extracting Twitter data using option objects

Install

• Install Node.js
• Install twitter2return via npm
• Recommended: Install dotenv via npm

npm install --save twitter2return
npm install --save dotenv

For the latest developer version, see Developer Install.

Usage

It is recommended to use a .env file at the root of your project directory with the following contents:

• Obtain the keys below from https://apps.twitter.com/
• TWITTER_CONSUMER_KEY: Consumer key (API Key)
• TWITTER_CONSUMER_SECRET: Consumer secret (API secret)
• TWITTER_ACCESS_TOKEN_KEY: Access token
• TWITTER_ACCESS_TOKEN_SECRET: Access token secret

TWITTER_CONSUMER_KEY=***
TWITTER_CONSUMER_SECRET=***
TWITTER_ACCESS_TOKEN_KEY=***
TWITTER_ACCESS_TOKEN_SECRET=***

The .env file above can be loaded using dotenv:

require('dotenv').config();

See Documentation for more details.

REST API

• Load .env file variables
• Load twitter2return
• Create options object
• Optionally define Twitter API keys
• Search keyword twitter from GET search/tweets
• Apply a jsonata filter for statuses key only
• Execute twitter2return with the REST API options

require('dotenv').config();

var twitter2return = require('twitter2return');

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

// (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 API

• Load .env file variables
• Load twitter2return
• Create options object
• Optionally define Twitter API keys
• Track keyword twitter from POST statuses/filter
• Log the tweets when they are received
• Execute twitter2return with the Stream API options

require('dotenv').config();

var twitter2return = require('twitter2return');

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

// (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_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);
});

Contributions

• Reports for issues and suggestions can be made using the issue submission interface.
• Code contributions are submitted via pull requests

See CONTRIBUTING.md for more details.

Developer Notes

Developer Install

Install the latest developer version with npm from github:

npm install git+https://github.com/rrwen/twitter2return

Install from git cloned source:

• Ensure git is installed
• Clone into current path
• Install via npm

git clone https://github.com/rrwen/twitter2return
cd twitter2return
npm install

Tests

• Clone into current path git clone https://github.com/rrwen/twitter2return
• Enter into folder cd twitter2return
• Ensure devDependencies are installed and available
• Run tests with a .env file (see tests/README.md)
• Results are saved to tests/log with each file corresponding to a version tested

npm install
npm test

Documentation

Use documentationjs to generate html documentation in the docs folder:

npm run docs

See JSDoc style for formatting syntax.

Upload to Github

• Ensure git is installed
• Inside the twitter2return folder, add all files and commit changes
• Push to github

git add .
git commit -a -m "Generic update"
git push

Upload to npm

• Update the version in package.json
• Run tests and check for OK status (see tests/README.md)
• Generate documentation
• Login to npm
• Publish to npm

npm test
npm run docs
npm login
npm publish

Implementation

The module twitter2return uses the following npm packages for its implementation:

npm	Purpose
twitter	Connections to the Twitter API REST and Streaming Application Programming Interfaces (APIs)
jsonata	Query language to filter Twitter JSON data

twitter   <-- Extract Twitter data from API
    |
jsonata   <-- Filter Twitter JSON data