1. Home
  2. Docs
  3. REST API
  4. API Reference
  5. RSS Feeds

RSS Feeds

These resources access elements of FeedBlitz’s RSS service.

Feeds Resource

Feeds Resource

Returns a list of active RSS feeds and summary data about the feed. If a feed ID is not specified, all the feeds for the account will be returned.

Resource path: /feeds/<feedid>

Methods:         GET

Example:         /feeds

Response XML:

<?xml version="1.0" encoding="UTF-8"?>
<feedblitzapi version="1.0" xmlns:xlink="http://www.w3.org/1999/xlink">
<rsp stat="ok">
<success code="0" msg="Authorized" />
</rsp>
<feeds>
	<feed>
		<id>1027><id>
		<title><![CDATA[FeedBlitz News]]></title>
		<uri>FeedBlitz</uri>
		<circulatiom>29234</circulation>
		<source>https://www.feedblitz.com/feed</source>
		<status>ok</status>
		<reason/>
	</feed>
</feeds>
  • The “reason” element will provide insight into any problems if the status is not “ok”
  • If the publisher has multiple RSS feeds, there will be multiple <feed>…</feed> elements.

/feeds/<feedid>

Provides summary data for the specified feedid.

/feeds/<feedid>/stats/<fromdate>/<todate>

Provides summary data (circulation, reach, views, clicks, downloads) for the specified feed.

The <feedid> resource is required.

<fromdate> and <todate> are optional. If not specified, the results returned will be for yesterday, US eastern time (feed circulations are calculated daily, so circulation is not accurate for today.)

Dates are always specified in YYYY-MM-DD. e.g. /feeds/1027/stats/2014-07-29

If only one date is specified, data is only returned for that day. If two dates are supplied, data is returned for the date range specified, inclusive.

Data returned is XML similar to:

<?xml version="1.0" encoding="UTF-8"?>
<feedblitzapi version="1.0" xmlns:xlink="http://www.w3.org/1999/xlink">
<rsp stat="ok">
<success code="0" msg="Authorized" />
</rsp>
<stats>
<day>
	<date>2014-07-29</date>
	<circulation>29324</circulation>
	<reach>2675</reach>
	<views>1234</views>
	<clicks>56</clicks>
	<downloads>0</downloads>
</day>
</stats>

If an element is missing, e.g. downloads for feeds which aren’t podcasts, its value may be assumed to be zero.

Since metrics are only calculated daily, there is no need to repeatedly call the API on an intraday basis. Call it once for the relevant day and then persist the results locally.

/feeds/<feedid>/items/<fromdate>/<todate>

This provides the same data as the “stats” API except shows metrics for an individual link (post link or link inside a post).  The same metrics are returned, and the same remarks about dates and frequency apply. The XML structure is slightly different, as follows:

<?xml version="1.0" encoding="UTF-8"?>
<feedblitzapi version="1.0" xmlns:xlink="http://www.w3.org/1999/xlink">
<rsp stat="ok">
<success code="0" msg="Authorized" />
</rsp>
<stats>
<day>
	<date>2014-07-29</date>
	<item>
		<title><![CDATA[Rewind the Week – Robot Edition]]></title>
		<url>http://www.feedblitz.com/feedblitz-rewind-the-week-robot-edition/</url>
		<reach>2675</reach>
		<views>1</views>
		<clicks>56</clicks>
		<downloads>0</downloads>
	</item>
</day>
</stats>

FeedBlitz only knows the titles of links contained in the RSS metadata. If a click is recorded on a link within a post, and FeedBlitz does not know its title, the <title> element above will replicate the URL of the clicked link.

/feeds/<feedid>/readers/<fromdate>/<todate>

Provides information about how a feed is consumed and by what reader. Same remarks about listid and dates apply here as to the stats and items resources.

FeedBlitz differentiates between four kinds of RSS feed consumers:

  1. Search engines, which do not count towards a feed’s circulation.
  2. RSS aggregator services, like feed.ly, which centrally access a feed on behalf of many subscribers.
  3. Individual RSS readers, typically installed by a user on their desktop, tablet etc.
  4. Browsers, where the consuming application isn’t a specialized RSS reader.

FeedBlitz extracts a “shorthand” identity for a visiting user agent. If that’s a known user agent, a longer user-friendly name will be presented. If not, just the short hand user agent element. FeedBlitz doesn’t persist entire user agent strings in its metrics database.

The returned XML looks something like this:

<?xml version="1.0" encoding="UTF-8"?>
<feedblitzapi version="1.0" xmlns:xlink="http://www.w3.org/1999/xlink">
<rsp stat="ok">
<success code="0" msg="Authorized" />
</rsp>
<readers>
<day>
	<date>2014-07-29</date>
	<reader>
		<useragent>feedfetcher</useragent>
		<name>Google Reader</name>
		<subscribers>274</subscribers>
		<type>RSS Service</type>
	</reader>
</day>
</readers>