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 = ; var apiKey = processenvNEWSCRED_API_KEY;var client = apiKey: apiKey ;
Say we wanted to search the entire NewsCred platform for articles about 'china':
clientarticle;
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';clientarticle;
Every option maps directly to the NewsCred Platform. For a full list of options please see the NewsCred Documentation.
Table of Contents
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 = ; // Fetches images for 'china' articles.clientarticle;
API
NewsCred Article)
Article (client.article.get('guid', [options], callback)
Returns the article specified by the given GUID.
clientarticle;
client.article.search('query', [options], callback)
Returns a list of articles according to the specified set of parameters.
clientarticle;
article.topics([options], callback)
Returns topics related to the article specified.
clientarticle;
article.images([options], callback)
Returns all full size, licensed images associated with the specified article.
clientarticle;
article.related([options], callback)
Returns articles related to the article specified.
clientarticle;
NewsCred Story)
Story (client.story.search('query', [options], callback)
Returns the top stories related to the specified query.
clientstory;
NewsCred Source)
Source (client.source.get('guid', [options], callback)
Returns the source represented by the specified GUID.
clientsource;
source.search('query', [options], callback)
Search sources by name. Returns a list of sources objects.
clientsource;
source.articles([options], callback)
Returns a list of articles provided by the specified source.
clientsource;
source.topics([options], callback)
Returns a list of topics related to the source.
clientsource;
NewsCred Category)
Category (client.category.get('name', [options], callback)
Returns the source represented by the specified GUID.
clientcategory;
client.category.search('query', [options], callback)
Returns a list of categories according to the specified set of parameters.
clientcategory;
category.articles([options], callback)
Returns a list of articles within the category.
clientcategory;
category.stories([options], callback)
Returns a list of top news stories within the category.
clientcategory;
category.images([options], callback)
Returns images related to the category.
clientcategory;
category.topics([options], callback)
Returns a list of topics within the category.
clientcategory;
category.sources([options], callback)
Gets a list of sources that write most frequently about the category.
clientcategory;
NewsCred Topic)
Topic (client.topic.get('name', [options], callback)
Returns the topic represented by the specified GUID.
clienttopic;
client.topic.search('name', [options], callback)
Search for a specific topic.
clienttopic;
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' ;clienttopic;
topic.articles([options], callback)
Returns a list of articles related to the topic.
clienttopic;
topic.stories([options], callback)
Returns the top news stories for the topic.
clienttopic;
topic.images([options], callback)
Returns images related to the topic.
clienttopic;
topic.sources([options], callback)
Returns a list of sources that cover the topic.
clienttopic;
topic.videos([options], callback)
Returns a list of videos related to the topic.
clienttopic;
topic.related([options], callback)
Returns a list of topics related to the topic.
clienttopic;
client.topic.extract('extract', [options], callback)
Returns a list of topics extracted from the supplied query.
clienttopic;
topic.tweets([options], callback)
Returns a list of real-time tweets about the topic.
clienttopic;
NewsCred Image)
Image (client.image.get('name', [options], callback)
Returns the image represented by the specified GUID.
clientimage;
client.image.search('name', [options], callback)
Search for a specific image.
clientimage;
NewsCred Video)
Video (client.video.get('name', [options], callback)
Returns the video represented by the specified GUID.
clientvideo;
client.video.search('name', [options], callback)
Search for a specific video.
clientvideo;
NewsCred Author)
Author (client.author.get('name', [options], callback)
Returns the author represented by the specified GUID.
clientauthor;
author.articles([options], callback)
Search for articles written by the author.
clientauthor;
author.topics([options], callback)
Search for topics written by the author.
clientauthor;
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:
clientarticle;
Can be converted into a single, more efficent query:
clientarticle;
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