signals-api

Signals Node JS API

Quick Start

Install Signals API

$ npm install signals-api

Get API Credential

1. Create an API key in the account info panel. The API key has the same user groups as the owner.
2. Download the API key.

Warning! It's your resposibility to protect the credential. A json with a complete credential will be pasted to your clipboard.

NodeJS has a easy way to load json.

module.exports={/*your credential here*/} // load json with require

If you want to use the command line, save the credential to .signalsrc under your working folder.

Create API instance

Save the credential to a json file and import it into your NodeJS code.

// import signals api
var Signals = require('signals-api').Signals;
// load your credential
var kAPPCredential = require('./appCredential');
// if region is undefined, then it is defaulted to en
var region = 'en'
var api = Signals(kAPPCredential,'en');
// do something with the api ...

Replace 'en' with 'zh' if you are using china node

Install Signals Command Line Tool

Command line tool is no longer included in the signals-api, use signals-cli instead

$ npm install -g signals-cli

Job Configuration

Job configuration tells Signals how to process the data. The most important part is the params which define the data type of each column in the csv file. You have to assign an array of column names to each index.

{
    "file_encoding": "utf-8", // encoding
    "params": {
 
        // map your header fields
 
            //Text Analysis
            "text_index": [ ... text columns ],	// multi value, put all your text fields in this array
 
            //Contributors
            "user_index": [ ... user id column ], // only support 1 user field now
            "user_image_index": [ ... user image src columns ], // 1 user image field, need to map "user_index" too
 
            // Geo Info, use related fields together, the more detailed fieilds you put in, the more accurate and efficient our engine will be
            "geo_index.unknown" : [ ... general address columns ],
 
            "geo_index.global": [ ... country name columns ]
            "geo_index.subglobal": [ ... state/provices name columns ]
            "geo_index.local": [ ... city columns ],		 
            "geo_index.sublocal": [ ... street columns ],
 
            "geo_index.postcode": [ ... postcode columns ],
 
            "geo_index.latitude": [ ... latitude columns ],
            "geo_index.longitude": [ ... longitude columns ],
 
            "geo_index.latitude_longitude": [ ... latitude_longitude columns, ex: "lat,lon" ],
            "geo_index.longitude_latitude": [ ... longitude_latitude columns, ex: "lon,lat" ],
 
 
            // Date info, the more detailed fieilds you put in, the more accurate and efficient our engine will be
            "date_index.unknown": [ ... general date columns ],
 
            "date_index.year": [ ... year columns ],
            "date_index.month": [ ... month columns ],
            "date_index.day": [ ... day of month columns ],
 
            "date_index.timestamp": [ ... epoch timestamp (UTC-0) in milliseconds columns ], // use timestamp for Excel files
 
        // general information
 
            "user_timezone": -4, // time zone offset, user current timezone
            "user_emails": [ ...array of emails that will be notified after analysis finished ],
 
 
 
                /* looking at specific languages, optional
             	if your documents are all in the same language
                    "run_language_detection":false,
                    "default_language"： "zh", // will increse accuracy and speed of your analysis
                else
                    "run_language_detection": true,
                    "filter_language": [... optional, only analysis on these languages, ex : 'en','zh','ja' ],
                */
 
        // customize engine
 
            "sentimentlists": [ ... array of your customized sentiment list, { "fid": 1234567, "version": 1} ],
            "stopdocslists": [ ... array of your customized junk and feedback list, { "fid": 1234567, "version": 1} ],
            "stopwordslists": [ ... array of your customized stop words list, { "fid": 1234567, "version": 1} ],
            "tokenslists": [ ... array of your customized chinese tokens list, { "fid": 1234567, "version": 1} ],
 
            "taxonomies": [ ... // tag your documents with selected taxonomy
            { "label": [... Optional, leave empty array, thi is an array of the labels in the taxonomy hierarcy,
                if you only want to tag a subtree of your taxonomy, input the path to your desired label ],
            "model" : { "fid": 123456789, "version": 1} ],
 
    },
    "meta": {
        "name": "API test small_lulu.csv 2016-6-24", // analysis name
        "source": "csv", // data format csv or xlsx
        "description": "Descrption of your analysis", // string
    }
}

Examples

List finished jobs

// import signals api
var Signals = require('signals-api');
// load your credential
var kAPPCredential = require('./appCredential');
var api = new Signals(kAPPCredential,'en');
// list all finished jobs
api.getJobStatus({
    pageIndex: 0,
    pageSize: 25,
    sortBy: 'time',
    sortOrder: -1,
    filter: {current:1,['status.code']:40}
}, function ( error, profiles, response) {
    if (profiles && profiles.items) {
        profiles.items.forEach(function (p) {
            var name = p.name;
            var fid = p.fid;
            var statusCode = p.status.code;
            var detail = p.status.detail;
            console.log({
                name: name,
                fid: fid,
                statusCode: statusCode,
                detail: detail
            });
        });
    }
});

List running jobs

// import signals api
var Signals = require('signals-api');
// load your credential
var kAPPCredential = require('./appCredential');
var api = new Signals(kAPPCredential,'en');
// list all finished jobs
api.getJobStatus({
    pageIndex: 0,
    pageSize: 25,
    sortBy: 'time',
    sortOrder: -1,
    filter: {['status.code']:{['$lt']:40}}
}, function ( error, profiles, response ) {
    if (profiles && profiles.items) {
        profiles.items.forEach(function (p) {
            var name = p.name;
            var fid = p.fid;
            var statusCode = p.status.code;
            var detail = p.status.detail;
            console.log({
                name: name,
                fid: fid,
                statusCode: statusCode,
                detail: detail
            });
        });
    }
});

Get a specific job

You need a job id to locate a specific job.
Job ids can be found in the response of creating a new job or the previous job status calls.

// import signals api
var Signals = require('signals-api');
// load your credential
var kAPPCredential = require('./appCredential');
var api = new Signals(kAPPCredential,'en');
signals.job(args.jobId,function( error, config, response ) {
    console.log(config);
});

Command Line

$ signals -job <job id>

Create a new job

You need a CSV data and a job configuration to create a job.
The job configuration tells Signals how to process the data in the csv and provides initial meta data for the job.
Check out more detailed job configuration/parameters that you can use in the "Job Configuration" section.

// import signals api
var Signals = require('signals-api');
// load your credential
var kAPPCredential = require('./appCredential');
var api = new Signals(kAPPCredential,'en');
// create a new job
var job = api.job();
job.config({
    "file_encoding": "utf-8",
    "params": {
        "text_index": ["text"],
        "user_index": [],
        "user_image_index": [],
        "date_index.unknown": ["date"],
        "user_timezone": -4,
        "geo_index.unknown": ["location"]
    },
    // "run_language_detection":true
    "meta": {
        "name": "API test small_lulu.csv 2016-6-24",
        "source": "csv"
    }
});
// upload data
var fs = require('fs');
job.uploadData(fs.createReadStream('../../samples/small_lulu.csv'), function ( error, body, response ) {
    console.log({ fid: job.fid() });
});

Command Line

$ signals submit -config <job configuration in json> -data <csv file>

Delete a job

// import signals api
var Signals = require('signals-api');
// load your credential
var kAPPCredential = require('./appCredential');
var api = new Signals(kAPPCredential,'en');
var jobId = '' /*job id*/;
api.deleteJob(jobId, function( error, body,response ) {
    if( response.success ) {
        console.log('Job deleted');
    }
});

Command Line

$ signals delete -job <job id>

Create a group

// import signals api
var Signals = require('signals-api');
// load your credential
var kAPPCredential = require('./appCredential');
var api = new Signals(kAPPCredential,'en');
api.createGroup( name, meta, function( error, body,response ) {
    if( response.success ) {
        console.log('group created');
        var groupId = body.payload._id;
        // do something with the id
    }
});

Delete a group

// import signals api
var Signals = require('signals-api');
// load your credential
var kAPPCredential = require('./appCredential');
var api = new Signals(kAPPCredential,'en');
var groupId = /* your group id */
api.deleteGroup( groupId, function( error, body,response ) {
    if( response.success ) {
        console.log('group deleted');
    }
});

Update a group

// import signals api
var Signals = require('signals-api');
// load your credential
var kAPPCredential = require('./appCredential');
var api = new Signals(kAPPCredential,'en');
var groupId = /* your group id */
api.updateGroup( groupId, { name: 'New Name', meta: { /* any meta field*/ } }, function( error, body,response ) {
    if( response.success ) {
        console.log('group updated');
    }
});

Get a group detail

// import signals api
var Signals = require('signals-api');
// load your credential
var kAPPCredential = require('./appCredential');
var api = new Signals(kAPPCredential,'en');
var groupId = /* your group id */
api.getGroup( groupId, function( error, body,response ) {
    if( response.success ) {
        var group = body.payload;
        /*do something with the detail*/
    }
});

Change access level for a user in the group

// import signals api
var Signals = require('signals-api');
// load your credential
var kAPPCredential = require('./appCredential');
var api = new Signals(kAPPCredential,'en');
var groupId = /* your group id */, userId = /*Your user id*/, acessLevel = /*1~4*/
api.changeUserAccess( groupId, userId, accessLevel, function( error, body,response ) {
    if( response.success ) {
        // access level changed	
    }
});

Share relational object with a user/group

// import signals api
var Signals = require('signals-api');
// load your credential
var kAPPCredential = require('./appCredential');
var api = new Signals(kAPPCredential,'en');
var fid = /* object fid */, type = /* relational object type dashboards,jobs,streams...	*/
var groupId = /* your group/user id */, acessLevel = /*1~4*/
api.shareWith( fid, type, groupId, accessLevel, function( error, body,response ) {
    if( response.success ) {
        // access level changed	
    }
});