Robust RSS Atom and RDF feed parsing using sax js
This module adds methods for RSS, Atom, and RDF feed parsing in node.js using Isaac Schlueter's sax parser.
npm install feedparser
The module now exports
as static functions. You no longer need to create a
FeedParser instance or use
the prototype methods. Due to confusion about how to implement those methods in
application code, using the prototype methods is now DEPRECATED.
As a major enhancement, Feedparser is now able to properly handle XML namespaces, including those in sadistic feeds that define a non-default namespace for the main feed elements.
var FeedParser = require'feedparser'parser =;parseron'article' console.log;parserparseStringstring;
var feedparser = require'feedparser';feedparserparseStringstringon'article' console.log;
string- the contents of the feed
filename- a local filename or remote url
The first argument can be either a url or a
request options object. The only
required option is uri, all others are optional. See
request for details
about what that
request options object might look like.
url- fully qualified uri or a parsed url object from url.parse()
readableStream- a Readable Stream
normalize - Set to
false to override Feedparser's default behavior,
which is to parse feeds into an object that contains the generic properties
patterned after (although not identical to) the RSS 2.0 format, regardless
of the feed's format.
addmeta - Set to
false to override Feedparser's default behavior, which
is to add the feed's
meta information to each
dateformat - Optionally set a specific format for parsing of the dates (e.g.
for different locales). The format is moment style.
feedurl - The url (string) of the feed. FeedParser is very good at
resolving relative urls in feeds. But some feeds use relative urls without
xml:base attribute any place in the feed. This is perfectly
valid, but if we are parsing the feed with the
parseStream method, we don't know know the feed's url before we start
parsing the feed and trying to resolve those relative urls. If we discover
the feed's url, we will go back and resolve the relative urls we've already
seen, but this takes a little time (not much). If you want to be sure we
never have to re-resolve relative urls (or if FeedParser is failing to
properly resolve relative urls), you should set
var feedparser = require'feedparser'fs = require'fs' // used in the examples below;
(For brevity in this pseudo-code, I'm not handling errors. But you need to handle errors in your code.)
console.log'Got article: %s' JSONstringifyarticle;// You can give a local file path to parseFile()feedparserparseFile'./feed'on'article' callback;// For libxml compatibility, you can also give a URL to parseFile()feedparserparseFile''on'article' callback;// Or, you can give that URL to parseUrl()feedparserparseUrl''on'article' callback;// But you should probably be using conditional GETs and passing the results to// parseString() or piping it right into the stream, if possiblevar request = require'request';var reqObj = 'uri': '''headers': 'If-Modified-Since' : <your cached 'lastModified' value>'If-None-Match' : <your cached 'etag' value>;// parseString()requestreqObjfeedparserparseStringbodyon'article' callback;;// Stream pipingrequestreqObjpipefeedparserstream;// Or you could try letting feedparser handle working with request (experimental)feedparserparseUrlreqObjon'response'// do something like save the HTTP headers for a future requeston'article' callback;// Using the stream interface with a file (or string)// A good alternative to parseFile() or parseString() when you have a large local filefeedparserparseStreamfscreateReadStream'./feed'on'article' callback;// OrfscreateReadStream'./feed'pipefeedparserstreamon'article' callback;
complete- called with
articleswhen parsing is complete
end- called with no parameters when parsing is complete or aborted (e.g., due to error)
error- called with
errorwhenever there is a an error of any kind (SAXEror, Feedparser error, request error, etc.)
meta- called with
metawhen it has been parsed
article- called with a single
articlewhen each article has been parsed
response- called with the HTTP
responseonly when a url has been fetched via parseUrl or parseFile
304- called with no parameters when when a url has been fetched with a conditional GET via parseUrl or parseFile and the remote server responds with '304 Not Modified'
When the feed is finished being parsed, if you provide a callback, it gets called with three parameters: error, meta, and articles.
if error console.errorerror;elseconsole.log'Feed info';console.log'%s - %s - %s' metatitle metalink metaxmlurl;console.log'Articles';articlesforEachconsole.log'%s - %s (%s)' articledate articletitle articlelink;;feedparserparseFile'./feed' callback;// To use the stream interface with a callback, you *MUST* use parseStream(), not pipingfeedparserparseStreamfscreateReadStream'./feed' callback;
Feedparser parses each feed into a
meta portion and one or more
Regardless of the format of the feed, the
meta and each
article contain a
uniform set of generic properties patterned after (although not identical to)
the RSS 2.0 format, as well as all of the properties originally contained in the
feed. So, for example, an Atom feed may have a
meta.description property, but
it will also have a
The purpose of the generic properties is to provide the user a uniform interface
for accessing a feed's information without needing to know the feed's format
(i.e., RSS versus Atom) or having to worry about handling the differences
between the formats. However, the original information is also there, in case
you need it. In addition, Feedparser supports some popular namespace extensions
(or portions of them), such as portions of the
pheedo extensions. So, for example, if a feed article contains either an
media:thumbnail, the url for that image will be contained in
All generic properties are "pre-initialized" to
null (or empty arrays or
objects for certain properties). This should save you from having to do a lot of
undefined, such as, for example, when you are using jade
In addition, all properties (and namespace prefixes) use only lowercase letters, regardless of how they were capitalized in the original feed. ("xmlUrl" and "pubDate" also are still used to provide backwards compatibility.) This decision places ease-of-use over purity -- hopefully, you will never need to think about whether you should camelCase "pubDate" ever again.
origlinkcontains the original link)
titleproperties pointing to the original source for an article; see the RSS Spec for an explanation of this element)
urlproperty and possibly
The following are the major contributors of
node-feedparser (in no specific
node-feedparser no longer shares any code with
node-easyrss, it was
the original inspiration and a starting point.
(The MIT License)
Copyright (c) 2011-2012 Dan MacTough <firstname.lastname@example.org>
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.