webhose.io client for Node.js

A simple way to access the webhose.io <https://webhose.io> API from your Node.js code

API Key

To make use of the webhose.io API, you need to obtain a token that would be used on every request. To obtain an API key, create an account at https://webhose.io/auth/signup, and then go into https://webhose.io/dashboard to see your token.

Installing

$ npm install webhose-nodejs

Quick Start

The module depends on two Node environment variables:

$ WEBHOSE_TOKEN=[your_token] WEBHOSE_URI=https://webhose.io/search

WEBHOSE_URI has been included so you can dynamically set the value for multi-environment and integration testing support.

Once these environment variables have been set, executing a query is as easy as this:

var webhose = require('webhose-nodejs'); var q = '(iphone OR ipad) -android'; var options = { format: 'json', language: 'english', site_type: 'news', exclude: 'yahoo.com', size: 5 }; webhose.search(q, options, function(err, res) { if(err) console.log(err); console.log(res.status); // HTTP status code console.log(res.msg); // Status message console.log(res.data); // Webhose response body });

Search Method Documentation

Query Argument

required, string

For now, the q argument simply accepts a string that must be formatted according to the Webhose.io API requirements.

Options Argument

optional, object

The following options can be passed into the search method to narrow/filter the search. Some options support enum values to help narrow down the scope of those options. The Webhose client includes an enums object you can access statically. Here's an example using the format option:

var webhose = require('webhose-nodejs'); var enums = webhose.enums; var options = { format: enums.format.json };

Similarly, the exclude option can use another attached object, Post , in order to specify which thread properties to exclude.

var Post = webhose.Post; var options = { exclude: { site: 'yahoo.com' } };

Option Value Type Acceptable Values Example format string json, xml enums.format.json... language string any, english, spanish enums.language.any... site_type string any, news, blogs, discussions enums.language.any... site string N/A author string N/A exclude object key: Any property of Post.thread, value: {site: 'yahoo.com'} size int Any integer greater than zero 10 thread.country string N/A thread.url string N/A thread.section_title string N/A thread.title string N/A person string N/A organization string N/A location string N/A spam_score float Any float between 0 and 1 N/A is_first boolean true, false N/A

Callback

The callback expects error and response arguments. If there is an error, res will be null and vice-versa. In either case, the data will be wrapped with a result object.

Examples:

Success

{ status : 200 , msg : ' Success ' , data : ' {"posts": [{"thread": {"url": "http:// ... }}]} ' }

Error

{ status : 401 , msg : ' Some Webhose error ' , data : null }

The res.data property will be the raw response body passed directly through from Webhose, in order to provide flexibility. The response will default to JSON, but if you specify options: {format: 'xml'} for example, the response will come back from Webhose as XML.

Exception Handling

To enable a cohesive exception handling flow, surround your calls to the search() method with a try/catch block. There is an errors object attached to Webhose that you can use if necessary to trap specific exceptions.

try { webhose.search('query', options, function(err, res) { // do stuff... } } catch (ex) { switch (ex) { case webhose.errors.SearchArgumentException: console.log(ex); break; } }

Hack the Module

Contribute

Please feel free to contribute to webhose-nodejs. Simply fork and submit any changes as a Pull Request.

Test

There is a unit/integration test suite included in the module. You can run it using the preconfigured NPM test script (Mocha), or configure your own IDE to run the tests with Mocha. Remember to set the WEBHOSE environment variables first.

$ WEBHOSE_TOKEN=[your_token] WEBHOSE_URI=https://webhose.io/search npm test

Continuous Integration