A JavaScript based library that allows easy access to IBM Watson features utilizing Twitter data. IBM Watson has some of the most advanced linguistic analytics tools available today. Twitter is one of the world's most popular text-based communication platforms. Leverage the power of both with minimal effort through personify.js.

The current version implements:

  • Watson User Modeling service, which extracts cognitive and social characteristics, including Big Five, Values, and Needs, from communications data provided.
  • Watson Machine Translation service, which converts text input in one language into a desired language for the end user. Translation is available for English, Brazilian Portuguese, Spanish, French and Arabic.
  • Twitter REST API.
  • Twitter Streaming API.

This project is hosted on GitHub. You can report bugs and discuss features on the GitHub issues page. Personify.js is available for use under the MIT software license.



Installing

npm install personify --save


Usage

Requiring Personify.js

var Personify = require('personify');


Configuration

For every service you use through Watson, IBM will provide you with a separate set of OAuth credentials. See below to find out where to get these credentials.

var config = {

  // example credentials for Watson Machine Translation service
      translateConfig : {
          service_url:          '...',
          service_username:     '...',
          service_password:     '...'
      },


  // example credentials for Watson User Modeling service

      personalityConfig : {
          service_url:          '...',
          service_username:     '...',
          service_password:     '...'
      },


  // example credentials for Twitter API

      twitterConfig : {
          consumer_key:         '...',
          consumer_secret:      '...',
          access_token:         '...',
          access_token_secret:  '...'
      }
  };


Instantiation

Instantiate a new Personify object and pass in OAuth credentials:

var P = new Personify(config);


Methods

userPersonify

Use Watson to discover personality traits, values and needs for a Twitter user; '@' can be used before a username but is not required (e.g., '@userName').

var params1 = {
                screen_name: 'userName'
                count: 100
              };


  P.userPersonify( params1 , function (data, err) {
      console.log(data, err);
  });


homePersonify

Watson provides a personality assessment of the combined input of tweets in a user's home timeline. Includes tweets from friends and accounts the user is following, and their retweets.

var params2 = {
                 count: 100, 
                exclude_tweets: true
              };


  P.homePersonify( params2, function (data, err) {
      console.log(data, err);
  });


searchPersonify

Search Twitter with a (required) keyword. Accepts all of Twitter's optional search parameters and a few additional ones we've created for your convenience.

var params3 = { 
                q: '#JavaScript', 
                geoCode: 'San Francisco'
              };


  P.searchPersonify( params3 , function (data, err) {
    console.log(data, err);
  });


searchTranslate

Grab a number of Tweets in a specified language and get back both the original text and its translation in another destination language. Most of the search parameters available here are the same as those in our searchTweet method.

var params4 = { 
                q: 'JavaScript', 
                fromLanguage: 'ar', // Translate from Arabic
                toLanguage: 'en',   // to English
                outputType: 'text'  // Choose from text, json or XML
              };


  P.searchTranslate( params4 , function (data, err) {
      console.log(data, err);
  });


userTranslate

Input a Twitter handle and get back their tweets translated

var params5 = {
                screen_name: 'userName',
                fromLanguage: 'en',
                toLanguage: 'fr',
                outputType: 'json'
              };


  P.userTranslate( params5, function(data, err){
      console.log(data, err);
  });


homeTranslate

Get tweets from your home timeline and have them translated into another language

var params6 = {
                count: 150,
                fromLanguage: 'en',
                toLanguage: 'fr',
                outputType: 'json'
              };


  P.homeTranslate( params6, function(data, err){
      console.log(data, err);
  });


streamTranslate

Find tweets talkng about the LHC using Twitter's Streaming API and translate them into another language

var params7 = {
                track: 'Large Hadron Collider'
                fromLanguage: 'en',
                toLanguage: 'fr',
                outputType: 'text'
              };


  P.streamTranslate( params7, function(data, err){
      console.log(data, err);
  });


Personify API


var P = new Personify( config )

Instantiate a new Personify object and pass in a config.

config - Type: Object

At least one set of OAuth credentials from both Twitter and IBM Bluemix are required to use the services personify.js leverages for you.

userPersonify

P.userPersonify( params, callback )

var params = { screen_name: 'userName' }

params - Type: Object

userName -Type: String

params with screen_name is required. userName represents a Twitter handle. Optionally you can include an '@' before userName.

See here for more information on optional parameters.


homePersonify

P.homePersonify( [params], callback )

[params] - Type: Object

Key-value pairs inside of [params] are optional, but at least an empty object literal is required.

See here for more information on optional parameters.


searchPersonify

P.searchPersonify( { q: 'input', [params] }, callback )

input Type: String

The 'q' key and its associated value, which is a string, are required. input can be any word you may use to search in Twitter's internal search engine. Any additional search parameters are optional.

See here for more information on optional parameters.


searchTranslate

P.searchTranslate( params , callback )
var params = { 
               q: input,
               fromLanguage: 'en',
               toLanguage: 'fr',
               outputType: 'json'
              };

params - Type: Object input - Type: String or Number or Array

Language key:

  • 'ar' = Arabic
  • 'en' = English
  • 'es' = Spanish
  • 'fr' = French
  • 'pt' = Brazilian Portuguese

Output Types:

  • 'text'
  • 'JSON'
  • 'XML'

All keys shown in params are required. See here for more information on optional parameters.


userTranslate

P.userTranslate( params , callback )
var params = { 
               screen_name: input,
               fromLanguage: 'en',
               toLanguage: 'fr',
               outputType: 'json'
              };

params - Type: Object

Please see Language key and Output Types under searchTranslate method in API.

See here for more information on optional parameters.


homeTranslate

P.homeTranslate( params , callback )
var params = { 
               fromLanguage: 'en',
               toLanguage: 'fr',
               outputType: 'json'
              };

count : val

val - Type: Number val defaults to 20 and has a max of 200.

All keys in params are required. Optionally you can specify a count key. This limits the number of Tweets for the search.

See here for more information on optional parameters.


streamTranslate

P.streamTranslate( params , callback )
var params = { 
               track: input,
               fromLanguage: 'en',
               toLanguage: 'fr',
               outputType: 'json'
              };

All keys in params are required for streaming. Please see Language key and Output Type options under searchTranslate method in API.

Additionally, optional search parameters that can be added to params:

  • locations : boundingBox
  • stop : time

boundingBox - Type: Array boundingBox coordinates can be found here.

boundingBox example: var sanFrancisco = [ '-122.75', '36.8', '-121.75', '37.8' ];

time - Type: Number time is the number of miliseconds after the stream starts that you want the stream to stop.

See here for more information on optional parameters.


callback

Type: Function

function (data, err)
  • callback takes two parameters, data and error, in that order.
  • callback is required for all methods.


OAuth Credentials

Go here to create a Twitter app and get OAuth credentials (if you haven't already):

https://dev.twitter.com/apps/new

In order to use IBM Watson, you need to:

  • Register for an IBM Bluemix account
  • Create an App
  • Add User Modeling and/ or Machine Translation service(s)
  • From there, IBM will provide your credentials



Tests

To make the tests pass you will need to fill out the file: config.js inside the tests folder.

To run the tests:

npm test


Contributing

To contribute to this project, please take a look at the guidelines on GitHub.



Development Team



Example Applications

Our PersonifyApp grabs tweets based on a keyword search and geolocation parameters and returns a Big Five assessment based on those tweets. It then compares that local result to the US in general. A company for example, might be interested to know about the collective Big Five traits of people who are talking about their products, services or brand.

Release History

  • 1.0.3 Cleaned up code, added geoList file, and updated README.md
  • 1.0.2 Personify logo added
  • 1.0.1 README.md updated
  • 1.0.0 Initial release