REST API

⌘K
  2. Home
  4. Docs
  6. REST API
  8. API Reference
  10. 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, POST, DELETE

Example:         /feeds

Get – Fetch data about the feed, access statistics, and resync it

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>
		<uri>feedblitz</uri>
		<circulation>3332</circulation>
		<source>http://www.feedblitz.com/feed/</source>
		<uid/>
		<pwd/>
		<status>ok</status>
		<failcount>0</failcount>
		<description/>
		<created>2012-04-30 00:00:00</created>
		<lastmodified>2019-06-06 23:17:53</lastmodified>
		<lastpolled>2019-08-28 16:50:46</lastpolled>
		<etag/>
		<hash>5cf8d04311d2a227f7b7f2811b27b319</hash>
	</feed>
</feeds>
  • The “reason” element will provide insight into any problems if the status is not “ok” and the “failcount” element shows how many consecutive fetches have failed.
  • The “uid” and “pwd” elements tell you the authentication credentials FeedBlitz is using to access the source.
  • The “description” overrides the description from the source feed. If the description is blank, it means that the source feed’s description is served untouched by FeedBlitz.
  • The status field is usually ok, failed, deleted or migrate. The deleted status indicates that the feed will return a 404 when fetched. A migrate status indicates a 30x status will be returned.
  • Timestamps
    • created: when this feed was first instantiated at FeedBlitz
    • lastmodified: when FeedBlitz detected a change in the underlying source feed or its configuration that caused FeedBlitz’s version of the feed to change.
    • lastpolled: the last time FeedBlitz checked the source feed. For feeds without PubSubHubbub hubs this may occur frequently, every 5 minutes or so, however FeedBlitz backs off over time if no changes are detected. For feeds with hubs, the source is polled less often as a backstop in case the hub fails to inform FeedBlitz of a change.
  • etag: This is the etag, if any, provided by the remote source feed.
  • hash: This is the etag that FeedBlitz will serve. FeedBlitz always serves RSS feeds with an etag so efficient clients can use If-None-Match to minimize bandwidth and performance requirements.
  • If the publisher has multiple RSS feeds, there will be multiple <feed>…</feed> elements.

Filtering all feeds results

You can add a status parameter to the API URL, enabling you to focus on classes of feed based on status. For example, adding “&status=fail” to the URL for /feeds will get you all the feeds in your account where the source is not providing good RSS feed XML. Valid status codes are ok, fail, migrate and deleted. If the status parameter is not specified, all your feeds are returned.

Per-feed resources

/feeds/<feedid>

Provides summary data for the specified feedid.

/feeds/<feedid>/resync

Forces FeedBlitz to fetch the underlying source completely (i.e. without sending an If-None-Match header), and then clear its internal caches so that future requests of the FeedBlitz feed will get the freshest data within 30s.

Feed reporting, metrics and analytics resources

/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>

Post – Change an RSS Feed’s Setup

Post XML to /feeds/<feedid> to change aspects of the feed’s configuration. You must POST to one of your feedids, and the XML you send must also include the feedid in the <id> element. This is shown in the following example, which sets a feed’s user ID and password (i.e. the authentication credentials used when fetching the feed from the underlying source URL).

<feedblitzapi version="1.0">
	<feed>
		<id>20203</id>
		<uid>It's Me</uid>
		<pwd>sekret</pwd>
	</feed>
</feedblitzapi>

IMPORTANT: If your POST is successful, FeedBlitz will perform a resync operation automatically for the feedid. There is no need for API users to call /feeds/<feedid>/resync after a successful POST – FeedBlitz has already done that by the time the call returns.

The following elements may be set:

ElementComment
titleSet the title of the feed. Overrides the source feed’s title, if any.
uriThe URI of the feed. The URI is checked for uniqueness within the FeedBlitz feed URI space. If you change the URI for an existing feed, FeedBlitz will NOT attempt to redirect requests for the old URI, which will 404 unless you create a new one to replace it.
sourceThe source URL for this feed. If you change it, you may trigger mailings from FeedBlitz’s RSS-powered Express and ASAP automated email campaigns, which use the URLs and GUIDs of the underlying feed to determine if any new content exists. Such email campaigns restrict themselves to posts 24 hours old or newer, so if the most recent post in the new content is older than 24 hours, no FeedBlitz mailings will take place.
descriptionOverride the source feed’s description with this copy. If blank, the source feed’s own description is passed through.
statusValid values are:

“ok” – lower case, no quotes – which allows a feed to be accessed by subscribers, and tells FeedBlitz to monitor the source for changes;
“paused” – Suspends FeedBlitz’s polling, but serves the feed as-is when requested.
uidThe user ID to send to the source feed using HTTP Basic Authentication. If you POST with an empty uid element (as <uid></uid> or <uid/>) it clears the stored user name.
pwdHTTP Basic Authentication password to send the remote host. Setting an empty value clears the password from the FeedBlitz database.

Delete – Remove a feed

Sending a DELETE to /feeds/<feedid> has the following effects:

  • Deletes all the metrics and usage data
  • Makes the URI available to other users
  • Returns a 404 for requests, until another feed is provisioned at FeedBlitz with that URI – which starts the feed afresh.

IMPORTANT: Using DELETE involves permanent, irreversible, physical data loss and should be used with caution.