NewsCred Node.js API

A compact Node.js library to give you easy access to the NewsCred Platform API.

Installation

$ npm install newscred --save

Quick Start

Make sure you have your API key to hand. If you just want to have a play, you can get a free (rate-limited) developer key from NewsCred.

The first step to working with the NewsCred API, is to create a NewsCred Client using your API key. The client is the object that allows you to communicate directly with the NewsCred platform.

A great tip is to store the key in an .env file and then source that file within each environment:

$ touch .env
$ echo "export NEWSCRED_API_KEY=XXX_API_KEY_HERE_XXXX" > .env
$ source .env

Then you can pull in the key via process.env.

var newscred = require('node-newscred');

var apiKey = new newscred.ApiKey(process.env.NEWSCRED_API_KEY);
var client = new newscred.Client({ apiKey: apiKey });

Say we wanted to search the entire NewsCred platform for articles about 'china':

client.article.search('china', function(err, articles){
    var chinaArticles = chinaArticles.toJSON();
    // Process those articles...
});

Those China Articles should look something like this:

{ page: { size: 10, offset: 0, page: 1, items: 182, total: 19 },
  dataset: 
   [ { category: [Object],
       description: 'Chinas leader, Xi Jinping, appeared to...',
       title: 'In China, Blunt Talk to Reporters on Access',
       created_at: '2014-11-13 02:18:42',
       author_set: [Object],
       licensed: 'False',
       // ...
   } ]
}

We can also modify our request to include additional options.

var options = {
    offset:     15,
    get_topics: false,
    sources:    '1ce0362f2e764a95b0c7351c05a4eb19'
};
client.article.search('china', options, function(err, articles){
    var chinaArticles = chinaArticles.toJSON();
    // Process those articles...
});

Every option maps directly to the NewsCred Platform. For a full list of options please see the NewsCred Documentation.

Table of Contents

• Model
• Collection
• Promises
• API
  • Article
  • Story
  • Source
  • Category
  • Topic
  • Image
  • Video
  • Author
• API Shortcuts
• Paging
• Tests

Model

A model is a compact data attribute container. Any data object returned from the NewsCred platform is automatically converted into a model.

toJSON()

Return a shallow copy of the model's attributes for JSON stringification. This can be used for persistence, serialization, or for augmentation before being sent to the client.

Collection

Collections are sets of models. Any dataset returned from the NewsCred platform is automatically converted into a collection. Most collections are paged.

get(id)

Returns the first model with the matching id.

toArray()

Returns a flat 1D array of the collection's models.

each(callback())

Iterates through the collection, invoking the callback for each model.

toJSON()

Iterates through the collection, calling toJSON() on each model. Returns an Array.

Promises

node-newscred works with Node-style callbacks, but also implements promises with the Q library.

var q = require('q');

// Fetches images for 'china' articles.
client.article.search('china').then(function(articles){
    return q.all(articles.map(function(article){
        return article.images();
    }));
}).then(function(images){
    console.log(images);
});

API

Article (NewsCred Article)

client.article.get('guid', [options], callback)

Returns the article specified by the given GUID.

client.article.get('c0992a44a782ac65a4baf81cecfa8b4a', function(err, article){
    console.log(article.toJSON());
});

client.article.search('query', [options], callback)

Returns a list of articles according to the specified set of parameters.

client.article.search('obama', function(err, articles){
    console.log(articles.toJSON());
});

article.topics([options], callback)

Returns topics related to the article specified.

client.article.get('5f7b40c489bb8b20be1217cf99f49d07', function(err, article){
    article.topics(function(err, topics){
        console.log(topics.toJSON());
    });
});

article.images([options], callback)

Returns all full size, licensed images associated with the specified article.

client.article.get('0a30f6067b65b987f7db3e82dcf50014', function(err, article){
    article.images(function(err, images){
        console.log(images.toJSON());
    });
});

article.related([options], callback)

Returns articles related to the article specified.

client.article.get('5f7b40c489bb8b20be1217cf99f49d07', function(err, article){
    article.related(function(err, related){
        console.log(related.toJSON());
    });
});

Story (NewsCred Story)

client.story.search('query', [options], callback)

Returns the top stories related to the specified query.

client.story.search('apple', function(err, story){
    console.log(story.toJSON());
});

Source (NewsCred Source)

client.source.get('guid', [options], callback)

Returns the source represented by the specified GUID.

client.source.get('a5364a204a0422bdcf23acc6c5c88af8', function(err, source){
    console.log(source.toJSON());
});

source.search('query', [options], callback)

Search sources by name. Returns a list of sources objects.

client.source.search('guardian', function(err, searchq){
    console.log(searchq.toJSON());
});

source.articles([options], callback)

Returns a list of articles provided by the specified source.

client.source.get('a5364a204a0422bdcf23acc6c5c88af8', function(err, source){
    source.articles(function(err, articles){
        console.log(articles.toJSON());
    });
});

source.topics([options], callback)

Returns a list of topics related to the source.

client.source.get('a5364a204a0422bdcf23acc6c5c88af8', function(err, source){
    source.topics(function(err, topics){
        console.log(topics.toJSON());
    });
});

Category (NewsCred Category)

client.category.get('name', [options], callback)

Returns the source represented by the specified GUID.

client.category.get('europe', function(err, category){
    console.log(category.toJSON());
});

client.category.search('query', [options], callback)

Returns a list of categories according to the specified set of parameters.

client.category.search('tech', { autosuggest: true }, function(err, categories){
    console.log(categories.toJSON());
});

category.articles([options], callback)

Returns a list of articles within the category.

client.category.get('business', function(err, category){
    category.articles(function(err, articles){
        console.log(articles.toJSON());
    });
});

category.stories([options], callback)

Returns a list of top news stories within the category.

client.category.get('business', function(err, category){
    category.stories(function(err, stories){
        console.log(stories.toJSON());
    });
});

category.images([options], callback)

Returns images related to the category.

client.category.get('business', function(err, category){
    category.images(function(err, images){
        console.log(images.toJSON());
    });
});

category.topics([options], callback)

Returns a list of topics within the category.

client.category.get('business', function(err, category){
    category.topics(function(err, topics){
        console.log(topics.toJSON());
    });
});

category.sources([options], callback)

Gets a list of sources that write most frequently about the category.

client.category.get('business', function(err, category){
    category.sources(function(err, sources){
        console.log(sources.toJSON());
    });
});

Topic (NewsCred Topic)

client.topic.get('name', [options], callback)

Returns the topic represented by the specified GUID.

client.topic.get('1e3f343e71de57fe9cc70b90c07e196e', function(err, topic){
    console.log(topic.toJSON());
});

client.topic.search('name', [options], callback)

Search for a specific topic.

client.topic.search('Obama', function(err, topics){
    console.log(topics.toJSON());
});

client.topic.relatedSearch([options], callback)

Returns a list of topics related to a set of search criteria. Can be used to find "trending" topics, among other things.

var criteria = { from_date: '-1DAY', fields: 'topic.name' };
client.topic.relatedSearch(criteria, function(err, relatedTopics){
    console.log(relatedTopics.toJSON());
});

topic.articles([options], callback)

Returns a list of articles related to the topic.

client.topic.get('1e3f343e71de57fe9cc70b90c07e196e', function(err, topic){
    topic.articles({ sort: 'relevance' }, function(err, articles){
        console.log(articles.toJSON());
    });
});

topic.stories([options], callback)

Returns the top news stories for the topic.

client.topic.get('1e3f343e71de57fe9cc70b90c07e196e', function(err, topic){
    topic.stories(function(err, stories){
        console.log(stories.toJSON());
    });
});

topic.images([options], callback)

Returns images related to the topic.

client.topic.get('1e3f343e71de57fe9cc70b90c07e196e', function(err, topic){
    topic.images(function(err, images){
        console.log(images.toJSON());
    });
});

topic.sources([options], callback)

Returns a list of sources that cover the topic.

client.topic.get('1e3f343e71de57fe9cc70b90c07e196e', function(err, topic){
    topic.sources(function(err, sources){
        console.log(sources.toJSON());
    });
});

topic.videos([options], callback)

Returns a list of videos related to the topic.

client.topic.get('1e3f343e71de57fe9cc70b90c07e196e', function(err, topic){
    topic.videos(function(err, videos){
        console.log(videos.toJSON());
    });
});

topic.related([options], callback)

Returns a list of topics related to the topic.

client.topic.get('1e3f343e71de57fe9cc70b90c07e196e', function(err, topic){
    topic.related({ pagesize: 20 }, function(err, related){
        console.log(related.toJSON());
    });
});

client.topic.extract('extract', [options], callback)

Returns a list of topics extracted from the supplied query.

client.topic.extract('The+Obama+Inauguration+was+attended', function(err, topics){
    console.log(topics.toJSON());
});

topic.tweets([options], callback)

Returns a list of real-time tweets about the topic.

client.topic.get('1e3f343e71de57fe9cc70b90c07e196e', function(err, topic){
    topic.tweets(function(err, tweets){
        console.log(tweets.toJSON());
    });
});

Image (NewsCred Image)

client.image.get('name', [options], callback)

Returns the image represented by the specified GUID.

client.image.get('a1f286f1d30a5817d3e4fddbbf2ec0d5', function(err, image){
    console.log(image.toJSON());
});

client.image.search('name', [options], callback)

Search for a specific image.

client.image.search('obama', function(err, images){
    console.log(images.toJSON());
});

Video (NewsCred Video)

client.video.get('name', [options], callback)

Returns the video represented by the specified GUID.

client.video.get('66d25ebdc3d5de69465e0d6da11ebcee', function(err, video){
    console.log(video.toJSON());
});

client.video.search('name', [options], callback)

Search for a specific video.

client.video.search('technology', function(err, videos){
    console.log(videos.toJSON());
});

Author (NewsCred Author)

client.author.get('name', [options], callback)

Returns the author represented by the specified GUID.

client.author.get('aab86c756ac5b04ea325e6fd3f105ddc', function(err, author){
    console.log(author.toJSON());
});

author.articles([options], callback)

Search for articles written by the author.

client.author.get('aab86c756ac5b04ea325e6fd3f105ddc', function(err, author){
    author.articles(function(err, articles){
        console.log(articles.toJSON());
    });
});

author.topics([options], callback)

Search for topics written by the author.

client.author.get('aab86c756ac5b04ea325e6fd3f105ddc', function(err, author){
    author.topics(function(err, topics){
        console.log(topics.toJSON());
    });
});

API Shortcuts

If you already have the unique resource identifier and only need a particular bit of associated data, then you can use a shortcut, or top level query.

The 2 step process here:

client.article.get('5f7b40c489bb8b20be1217cf99f49d07', function(err, article){
    article.topics(function(err, topics){
        console.log(topics.toJSON());
    });
});

Can be converted into a single, more efficent query:

client.article.topics('5f7b40c489bb8b20be1217cf99f49d07', function(err, topics){
    console.log(topics.toJSON());
});

The general form is: client.resource.action('resource_guid', [options], callback)

The majority of api calls support this optimisation:

Resource | Call | Shortcut
----------------|-----------------------|-------------------------------------- Article | Topics | client.article.topics | Images | client.article.images | Related Articles | client.article.related Author | Articles | client.author.articles | Topics | client.author.topics Category | Articles | client.category.articles | Stories | client.category.stories | Images | client.category.images | Topics | client.category.topics | Sources | client.category.sources Source | Articles | client.source.articles | Topics | client.source.topics Topic | Articles | client.topic.articles | Stories | client.topic.stories | Images | client.topic.images | Sources | client.topic.sources | Videos | client.topic.videos | Tweets | client.topic.tweets

Paging

Each platform call that returns a dataset is converted into a pageable collection.

• size - The number of items per page.
• offset - NewsCred item offset / index.
• page - The page the dataset rests on.
• items - Total number of items available.
• total - Total number of pages available.

An example of a paged collection:

{
    page: { size: 10, offset: 0, page: 1, items: 182, total: 19 },
    dataset: [...]
}

Tests

To run the test suite, first install the dependancies, then run npm test:

$ npm install
$ npm test