All content and services are licenced under a Attribution-NonCommercial-ShareAlike Creative Commons Licence (see our Terms of Service).

> Using NewsIsFree's API

For using NewsIsFree's API you need to be a registered user and have a personal application key. For getting your personal application key, please, contact us. For using clipPost and unclipPost functions you need to have a Premium Account.

All the API functions may return API response structure with corresponding response code and response message. This structure is always returned on errors. Some of the functions return this structure with successfull code (it is mentioned in function description).


<?
//response structure on success
array('response_code'=>'200',
      'resonse_message'=>'OK');

//response structure on authorization error
array('response_code'=>'403',
      'resonse_message'=>'Not Authorized');
?>

Status response code definitions:

2xx - successfull;
3xx - redirection;
4xx - client errors;
5xx - server errors.

API function list:
- createUser(application_key, login, password, createdLogin, createdPassword, email, deflang, username)
  Creates a new user with basic service on this site which is free. You need to be a registered user to create new users. New account also entitles you to 30 days free evaluation of our Premium Portal Service and Premium Export Services. After that period, if you don't want to sign up for the Premium Services (separate registration), the premium features will be simply disabled.
- getPages(application_key, login, password)
  Returns the user's page list.
- createPage(application_key, login, password, name)
  Creates a page, returning the identifier for the newly created page. The page name must be unique within the user page lists. If not, this method will throw a client fault.
- getOrCreatePage(application_key, login, password, name)
  Operates like createPage(), but if the specified page exists, it will return the id of that page.
- deletePage(application_key, login, password, id)
  Deletes the page indicated by id. Any subscriptions in the page will be removed.
- movePage(application_key, login, password, id, newId)
  Moves the page indicated by id under the page indicated by newId.
- renamePage(application_key, login, password, id, name)
  Changes the name of the page indicated by id to the value given in the newName parameter.
- showCategories(application_key, login, password)
  List of all news categories.
- getSourceList(application_key, login, password, page)
  Returns an OPML outline string for the user's source list for the named page, with a count of unread items in each source's outline.
- addSource(application_key, login, password, siteId, page)
  This call adds a source to the given page ID.
- deleteSource(application_key, login, password, siteId, page)
  Deletes the source identified in the argument from the currently authenticated user's source list.
- moveSource(application_key, login, password, siteId, fromPage, toPage)
  Moves a source to a specific page from another page.
- mergeSources(application_key, login, password, page, opmlDocument)
  Merges a source list with the user's current source list. Duplicate sources will not be duplicated; however, duplicates are determined solely by URI equivalence of the xmlurl attributes of individual elements and will not determine that, for example, two different URIs resolve to the same content.
- replaceSources(application_key, login, password, page, opmlDocument)
  Replaces a user's source list with the source list given by the opmlDocument parameter.
- getUpdates(application_key, login, password, since)
  Gets a list of source IDs that have updated since the specified date and server current timestamp for proper synchronization.
- getNews(application_key, login, password, siteId, unreadOnly)
  This method returns an RSS document for the given source.
- getSourceContent(application_key, login, password, siteId)
  This method returns an RSS document for the given source. This method returns the same content as GetNews, but without user read states.
- markRead(application_key, login, password, siteId, read)
  Sets all the posts in the specified source to be read or unread, based on a parameter.
- markSourcesRead(application_key, login, password, siteId)
  Sets all the posts in the specified source to be read.
- getFeedInfoSummaryFromXmlUrl(application_key, login, password, xmlurls)
  Returns a list of sourceInfoSummary structures, one for each of the submitted urls.
- setState(application_key, login, password, readItems, unreadItems)
  Sets a user's read/unread state for a set of posts (sources).
- getItems(application_key, login, password, itemIds)
  Creates an ad-hoc RSS feed from a list of items IDs. The posts specified must be current in the source.
- searchSources(application_key, login, password, search, lang, category)
  Search sources in the current category.
- directSearch(application_key, login, password, search, params)
  Search the news, depending on given parameters. The analog of newsisfree advanced search
- clipPost(application_key, login, password, itemId)
  Clips the specified item Id to the specified user clippings. You need to have a Premium Account.
- unClipPost(application_key, login, password, itemId)
  Removes the specified item Id from the authenticated user's clippings. You need to have a Premium Account.

This site uses the PHP implementation of SOAP server with WSDL definitions. So for getting access to NIF API you need to create a SOAP client. Below there are examples of SOAP client, using php5 standard SOAP library, PEAR SOAP and nusoap libraries:


<?
//php5 client
$client = new SoapClient("http://newsisfree.com/nifapi.wsdl",array("trace" => 1, "exceptions" => 0));
$result = $client->some_API_func($param1, $param2,....,$paramn);

//pear soap client
require_once('SOAP/Client.php');
$client = new SOAP_Client('http://newsisfree.com/nifapi.wsdl');
$param = array();
$param = array('param1'=>'param1','param2'=>'param2',.....,'paramn'=>'paramn');
$result = $client->call('some_API_func', $param);

// nusoap client
require_once('nusoap.php');
$client = new nusoapclient('http://newsisfree.com/nifapi.wsdl', true);
$param = array();
$param = array('param1'=>'param1','param2'=>'param2',.....,'paramn'=>'paramn');
$data = $client->call('some_API_func', $param);
?>

> directSearch(login, password, search, params)

This method searches the news, depending on given parameters. The analog of newsisfree advanced search.

application_key (string) - application key;
login (string) - user login;
password (string) - user password;
search (string) - search string;
params (string) - hash array of additional search parameters (very important to use 'params' array values order as shown below);
- as_language - language code (e.g. en,fr,it)
- numitems - number of items to search (max 100)
- source_id - source id
- as_sourcename - source name
- as_category - category id
- as_author - author name
- as_topics - topics
- as_date_from - from date (YYYY/MM/DD)
- as_date_to - to date (YYYY/MM/DD)
- as_pop_from - from popularity (0
- as_exact - exact match
- as_synonym - use synonyms
- as_relevance - by relevance
- as_intitle - only in titles

This method returns a hash array with found items. The named items are:

"query": search query
"page": search query
"numitems": number of items to return (max 100)
"relevance": by relevance
"intitle": only in titles
"exact": exact match
"synonym": use synonyms
"shortdesc": short description
"from": from number
"to": to number
"time": time
"hits_total": number of items at all
"rate_from": rating from
"rate_to": rating to
"items": array of found items
- "id": id of the news/item
- "title": item headline
- "date": date
- "link": link from which the item was taken
- "desc": news/item description
- "author": item author
- "popularity": item popularity
- "source": name of the source
- "sourceid": id of the source
- "sourcetitle": name of the source