Original URL: http://www.theregister.co.uk/2007/09/07/rss_atom_feeds/

Retrieving RSS/Atom Feeds with the Google AJAX Feed API

Using feeds to manage online news.

By Deepak Vohra

Posted in Developer, 7th September 2007 14:54 GMT

Keeping up to date with updates to different news websites can be a major burden – which can be ameliorated with an RSS feed. With an RSS feed, the updates are pushed to you as they become available.

RSS is a collection of web feed formats, specified in XML and used to provide frequently updated digital content to users. The first version of RSS, RSS 0.9, was created by Netscape in 1999 but the “RSS” acronym has different interpretations for different subsequent standards: for RSS 2.0, Really Simple Syndication; for RSS 0.91 and RSS 1.0, Rich Site Summary; for RSS 0.9 and RSS 1.0, RDF Site Summary.

An RSS feed may be read using a feed reader such as Google Reader or RssReader. It may also be read using a Feed API and Google provides the Google AJAX Feed API to receive any RSS feed.

An RSS Feed may be displayed in JSON Result Format, XML Result Format, or combined JSON/XML Result Format. JSON (JavaScript Object Notation) is a data interchange format used to transmit structured data and is based on the following data structures:

  1. Object-Collection of key-value pairs, separated by a comma, and enclosed in { }.
  2. Array-Ordered sequence of values, separated by a comma and enclosed in [ ].

By default, the Ajax Feed API returns the feed in JSON format.

Because of the incompatibilities between the various versions of RSS and the limitations of RSS, a new syndication specification, Atom, was introduced in 2003. Atom is not a strict superset of RSS - for a comparison between RSS 2.0 and Atom 1.0 see here. An Atom feed has 3 main advantages over the original RSS feed:

We shall use standard Atom feeds in this article. It’s also worth noting that Microsoft has introduced the Simple Sharing Extensions (SSE), which “extend” the Atom 1.0 and RSS 2.0 specifications to provide item sharing between cross-subscribed feeds. However, note that an extended standard is no longer really a standard, although this one appears to be using, rather than re-inventing, the underlying RSS/Atom specs.

Overview of Google Ajax Feed API

The Google Ajax Feed API generates a result document, whose structure is different from either an RSS 2.0 or the Atom 1.0 feed. For example, it may contain elements such as "contentSnippet" and "publishedDate". Neither Atom 1.0 nor RSS 2.0 has these elements. The "contentSnippet" element corresponds to the snippet version of the <content> or <summary> element in Atom 1.0 and <description> element in RSS 2.0. The "publishedDate" element corresponds to the <published> element in Atom and the <pubDate> element in RSS 2.0. The Google Feed API uses its own set of result elements to generate a uniform result format for an Atom 1.0 feed and an RSS 2.0 feed, which each have some elements different. A Google Ajax Feed is represented by the google.feeds.Feed class.

The Feed class methods do not have a return type. The Feed class methods are presented in the following table:

Method Description
load(callbackFunction) Downloads the feed from the Google server. The callbackFunction is invoked when the download is complete. The callbackFunction is invoked with a argument that represents the result of the feed.
setNumEntries(num) Sets the number of feed entries. Default value is 4.
setResultFormat(format) Sets the result format. One of the following values may be specified: google.feeds.Feed.JSON_FORMAT (the default), google.feeds.Feed.XML_FORMAT, or google.feeds.Feed.MIXED_FORMAT.

The root element of the feed result is <root>. If the loading generates an error the root element has an <error> sub-element. The <error> element has sub-elements <code> and <message>. The <code> element specifies the error code and the <message> element specifies the description of the error.

If the result format is JSON_FORMAT or MIXED_FORMAT the <root> element has a sub-element called <feed>. If the result format is XML_FORMAT or MIXED_FORMAT the root element has an element called <xmlDocument> . The xmlDocument element contains the XML document for the feed.

For JSON result format the <feed> element has the sub-elements described in the following table:

Sub-Element Description
title Specifies the feed title.
link Specifies the URL of the HTML version of the feed.
description Specifies the feed description.
author Specifies the feed author.
entries[] One or more entries may be present. Each entry has the following sub-elements: title-The entry title.link-URL of the HTML version of the entry.content- Specifies content of the entry including HTML tags. contentSnippet-A snippet version of the content. publishedDate-Date of publication.categories[]-One or more category String tags.

For google.feeds.Feed.MIXED_FORMAT result format, both the feed and xmlDocument sub-elements are present in the root element. An additional sub-element called xmlNode is present for each entry for MIXED_FORMAT. The xmlNode sub-element is a pointer to the XML element in the XML document in the xmlElement element.

The google.feeds.FeedControl class is used to download and display multiple feeds. The FeedControl methods are described in the following table:

Method Description
addFeed(url, label) Adds the feed specified by the url to the FeedControl.
draw(element, opt_options?) Loads the feeds and displays the feeds. The element argument specifies the DOM node that contains the resulting entries. The optional opt_options specifies the control options as a JSON object to display the results. The object has a single property called drawMode, which has the value google.feeds.FeedControl.DRAW_MODE_TABBED or google.feeds.FeedControl.DRAW_MODE_LINEAR (default).
setNumEntries(num) Specifies the number of entries for each feed. Default value is 4.
setLinkTarget(linkTarget) Specifies the link target to display the HTML for an entry. The following values may be specified:google.feeds.LINK_TARGET_BLANK google.feeds.LINK_TARGET_SELF (default)google.feeds.LINK_TARGET_TOP google.feeds.LINK_TARGET_PARENT

The Google Ajax Feed API provides a global method google.feeds.getElementsByTagNameNS(node, ns, localName), which returns a NodeList of elements of the specified local name and namespace URI.

Preliminary Setup

We want to develop a JavaScript application to download and display RSS/Atom feeds with the Google Ajax API. First, we need to register a web application URL with the Google AJAX Feed API to download and display Atom feeds.

We shall create the JavaScript application in JDeveloper. Download and install JDeveloper 10.1.3.2. To create a JDeveloper application select File>New and subsequently select General>Application in the New Gallery Click on OK. Specify an Application Name and click on OK. Specify a Project Name and click on OK. A new application and project are added to the Applications-Navigator.

Add a HTML page to the JDeveloper project by selecting the project node and selecting File>New and subsequently selecting Web Tier>HTML>HTML Page. An HTML page is added as shown in Figure 1.

Shows the JDeveloper Application.

We need to register the URL for the HTML page with the Google Ajax Feed API. Right-click on the HTML page and select Run. Obtain the URL, which is http://142.179.34.223:8990/GoogleRSS-GoogleRSS-context-root. Sign up for the Google AJAX Feed API using the URL http://code.google.com/apis/ajaxfeeds/signup.html as shown in Figure 2. Click on the Generate API Key button to generate the API key (you’ll need to be logged in to your Google user account to generate this).

Shows the generation of a Google Feed API key

Receiving an Atom Feed

In this section, we’ll generate a JavaScript application to download and display an Atom feed for Reg Developer. First, obtain the URL for the Atom feed from the Reg Developer Feeds page.The URL for the Atom Feed “Reg Developer” is http://www.regdeveloper.co.uk/headlines.atom. To access a Feed with the Google AJAX Feed API we need to add the following <script> element to the JavaScript application GoogleRSS.html:

 <script type="text/javascript"
          src="http://www.google.com/jsapi?key=ABQIAAAAItAEL-H-
GuOHsDfD7MxmlhSpY8xpRlVNOvpHrXTaq4lZbJurjRQMBL0DtsRGauRDjwp6d-
ST2IgadQ"></script> 

The previous <script> tag loads the google.load function that is needed on order to load individual Google APIs. First, download version 1 of the feeds API:

 google.load("feeds", "1");

Then create a JavaScript function initialize and specify the function to be invoked when the Google Feed API has loaded:

 google.setOnLoadCallback(initialize); 

Next, create a Feed class object to download a feed. Specify the URL for the Reg Developer Feed, to create the Feed class object:

 var feed = new google.feeds.Feed("http://www.regdeveloper.co.uk/headlines.atom");

Now, load the Atom feed using the load(callbackFunction) method of the Feed class:

 feed.load(function(result) {        });

Next, add a <div> element to the <body> element of the JavaScript application to display the Atom feed results:

 <body><div id="feed"></div></body> 

Then, in the callback function obtain the <div> element using the getElementById method:

 var container = document.getElementById("feed");

Now, iterate over the feed results:

 for (var i = 0; i < result.feed.entries.length; i++) {       }

Then, obtain each of the feed entries, create a <div> element for each of the feed entries and add the entry title to the <div> element for each of the feed entry:

 var entry = result.feed.entries[i];           
 var div = document.createElement("div");            div.appendChild(document.createTextNode(entry.title)); 

And finally, add the <div> element for each of the entries to the container <div> element:

 container.appendChild(div); 

The JavaScript application GoogleRSS.html is available in the Resources zip file.

To display the Atom Feed entries’ titles, right-click on the GoogleRSS.html HTML page and select Run - see Figure 3:

Shows the JavaScript Applicationgeneration running.

The entries’ titles in the Atom feed are displayed – see Figure 4:

Shows the resulting Atom feed.

The previous Atom Feed application only displays the titles of the entries in the Atom feed. Next, we shall display additional JSON properties such as “title”, “link”, “publishedDate” and “contentSnippet” from the Atom Feed.

You now iterate over the entries to obtain each of the entries in the Atom Feed. Specify the attributes to be displayed:

 var attributes = ["title", "link", "publishedDate", "contentSnippet"];

Then, create a <div> element for each of the attributes and add the <div> elements to the container <div> element:

 for (var j = 0; j < attributes.length; j++) {
        var div = document.createElement("div");
        div.appendChild(document.createTextNode(entry[attributes[j]]));
        container.appendChild(div);
      }

The JavaScript application, GoogleRSS-JSON.html, to display the JSON properties from the Atom Feed is available in the Resources zip file.

Run the GoogleRSS-JSON.html application. The Atom Feed entries’ titles, links, publication date, and content snippet are displayed – see Figure 5:

Shows the Atom feed with JSON Properties.

Next, we shall display multiple feeds using the FeedControl class. We’ll display the “Reg Developer” Atom feed and the “Editors Blog” Atom feed. As in the JavaScript application, to display a single feed specify a <script> tag for the Google Feed APIs. Add a <div> element to the JavaScript application to display the Atom Feeds:

 <body><div id="feedControl">Loading</div></body> 

Load version 1 of the Feed API. Invoke a callback function initialize after the Google Feed API has loaded. In the callback function create a FeedControl object:

 var feedControl = new google.feeds.FeedControl();

Specify the Atom Feeds to be loaded by the FeedControl:

 feedControl.addFeed("http://www.regdeveloper.co.uk/headlines.atom", "Reg Developer");
feedControl.addFeed("http://www.regdeveloper.co.uk/editors_blog/headlines.atom", 
"Editors Blog");

Load the Atom Feeds and display the Atom Feeds using the draw method:

 feedControl.draw(document.getElementById("feedControl"));

The JavaScript application, GoogleRSS-MultipleFeeds.html, to load multiple Atom Feeds is available in the Resources zip file. Now run the JavaScript application, and multiple Atom feeds are displayed – see Figure 6:

Shows multiple feeds.

You should now have successfully received an Atom feed. As it happens, the applications in this article may be used with either an Atom 1.0 feed or an RSS 2.0 feed (we’ve used Atom 1.0). However, the url for RSS 2.0 would be different: instead of http://www.regdeveloper.co.uk/headlines.atom, it would be http://www.regdeveloper.co.uk/headlines.rss. ®