Documentation

Introduction

At Superfeedr, we strongly believe that open protocols make the web better. For this reason, most of our API calls are directly inspired by open protocols.

Publisher

The PubSubHubbubb hubs that Superfeedr hosts are compliant with the core spec. In order to enable the hub as a publisher, you need to perform 2 actions : discovery and ping.

Discovery

Discovery is aimed at informing your current (and future) feed subscribers (who poll your feed) that they can get content your Superfeedr hosted hub. It's as easy as adding the following to your feeds:

• For RSS

<?xml version="1.0"?>
<rss>
 <channel>
  <title>...</title>
  <description>...</description>
  <link>...</link>

  <!-- PubSubHubbub Discovery -->
  <link rel="hub"  href="http://<your-hub-name>.superfeedr.com/" xmlns="http://www.w3.org/2005/Atom" />
  <link rel="self" href="<your-feed-url>" xmlns="http://www.w3.org/2005/Atom" />
  <!-- End Of PubSubHubbub Discovery -->
  ...
 </channel>
</rss>

• For Atom

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
 <title>...</title>
 <link href="..." rel="self" type="application/atom+xml"/>

 <!-- PubSubHubbub Discovery -->
 <link rel="hub" href="http://<your-hub-name>.superfeedr.com/" />
 <!-- End Of PubSubHubbub Discovery -->

 <updated>...</updated>
 <id>...</id>
 ...
</feed>

Ping (New Content Notification)

The next step is to ping us whenever you update the content of a feed. This will allow us to fetch this specific feed, identify what is new vs what is old in it and finally push the updates to the subscribers to this feed.

• Send an POST request to http://<your-hub>.superfeedr.com, with the following params :
  • hub.mode : publish
  • hub.url : the url of the feed that was updated
• If somebody subscribed to your feed, then, we will fetch it. You should see a request from Superfeedr in your logs.

At Superfeedr, we wanted to make it simple for you to implement the PubSubHubbub protocol, so if you have implemented any type of ping, please get in touch, as we're probably able to receive these too. For example, our XML-RPC endpoint is here.

Subscriber

Introduction

Superfeedr is a tool which will push you content to which you can subscribe online. Our historical use case is to allow you to subscribe to RSS or Atom feeds and get that content pushed to you in realtime, but you can obviously subscribe to any HTTP resource accessible via a GET request. For example, you can subscribe to JSON document, VCards, or even HTML pages.

If you have any question about this documentation or if you still need help with the Superfeedr, please join our Google Group, read our Frequently Asked Questions. We also strongly suggest the use of our dashboard (you must be logged in) to debug the real-time notification.

Color Code

Outbound (requests) traffic have a grey background.

Inbound (responses + notifications) traffic have a green background.

Notifications

Knowing when you will receive notifications from Superfeedr is a key aspect when building your application. Please read that section carefuly.

For feeds

We map each entry in a feed with a unique identifier (the id element in our schema). Hence, we will send you a notification for each new unique identifier that we can detect, whatever the rest of the entry is. This means that we won't use the title, or the links or even a signature of the entries's content to detect update. We believe the behavior we chose is compliant with the both the RSS and Atom specifications. When we are not able to find a unique id, we will generate one, using complex rules that vary from feed to feed.

Updates in an entry are by default not propagated because we chose to avoid numerous false positives. There is an exception to that: we will send you a notification for an update in a feed if both the entry contains a valid updated element, and that update is very recent (less than 3 minutes). In practice that means that we will mostly propagate updates for feeds for which we received a ping by the publisher.

Detecting updates in arbitrary resources is much easier. We do compute a signature (hash) for the full resource. If that signature is different between 2 fetches, then, we will consider that the content was updated and we will perform a notification of its full value.

What API to choose?

Superfeedr offers 2 different API : XMPP PubSub and HTTP PubSubHubbub. They have both purposes for which they've been created and, based on your goals using Superfeedr, you might want to select one or another. Here is a small chart that will help you choose the most appropriate in your case. (In this chart, the 'I' represent the endpoint that will receive the notifications).

XMPP PubSub

You can connect your jabber client (or component) to superfeedr by using the JID login-@superfeedr.com and your superfeedr password. You can also specify another JID in your settings.

The XMPP API is based on the XEP-0060 syntax. Additional data has been included within a superfeedr-specific namespace.

Subscribing to a Resource

• iq[@from] : should match the bare jid you entered in your settings.
• iq[@id] : random string (enables you to match the superfeedr response with your query).
• subscribe[@node] : use the url of the resource (feed) you want to monitor.
• subscribe[@jid] : should be equal to the @[from] or, if you have chose an external component jid, should have the same domain. JID resources will be ignored.
• subscribe[@format] : This must belong to the Superfeedr namespace (http://superfeedr.com/xmpp-pubsub-ext). You can specify the format of the payload in notifications, if the item is a feed. Currently, we support atom (default) and json. See schema below for more details. In the context of arbitrary content (not feeds), the content will be kept in its original format.

<iq type="set" from="you@superfeedr.com" to="firehoser.superfeedr.com" id="sub1">
 <pubsub xmlns="http://jabber.org/protocol/pubsub" xmlns:superfeedr="http://superfeedr.com/xmpp-pubsub-ext">
  <subscribe node="http://domain.tld/feed1.xml" jid="you@superfeedr.com"/>
  <subscribe node="http://domain.tld/feed2.xml" jid="you@superfeedr.com"/>
  <subscribe node="http://domain.tld/feed3.xml" jid="you@superfeedr.com"/>
  <subscribe node="http://domain.tld/path/to/resource" jid="you@superfeedr.com" superfeedr:format="atom" />
 </pubsub>
</iq>

You can add up to 20 resources in your subscription query, as long as they have all the same subscribe[@jid]. If you need to subscribe with multiple jids, we suggest that you send multiple subscription queries.

The server acknowledges the subscription(s) and sends the status information for each resource.

<iq type="result" to="you@superfeedr.com/home" from="firehoser.superfeedr.com" id="sub1">
 <pubsub xmlns="http://jabber.org/protocol/pubsub">
  <subscription jid="you@superfeedr.com" subscription="subscribed" node="http://domain.tld/path/to/resource">
   <status xmlns="http://superfeedr.com/xmpp-pubsub-ext">
    <http code="200">9718 bytes fetched in 1.462708s : 2 new entries.</http>
    <next_fetch>2009-05-10T11:19:38-07:00</next_fetch>
   </status>
  </subscription>
  <subscription jid="you@superfeedr.com" subscription="subscribed" node="http://domain.tld/path/to/resource2">
   <status xmlns="http://superfeedr.com/xmpp-pubsub-ext">
    <http code="200">9718 bytes fetched in 1.462708s : 2 new entries.</http>
    <next_fetch>2009-05-10T11:19:38-07:00</next_fetch>
   </status>
  </subscription>
  <subscription jid="you@superfeedr.com" subscription="subscribed" node="http://domain.tld/path/to/resource3">
   <status xmlns="http://superfeedr.com/xmpp-pubsub-ext">
    <http code="200">9718 bytes fetched in 1.462708s : 2 new entries.</http>
    <next_fetch>2009-05-10T11:19:38-07:00</next_fetch>
   </status>
  </subscription>
 </pubsub>
</iq>

In other cases, you will receive an iq with type="error", please check that your subscription query abide by the constraints explained above.

Removing a Resource

• iq[@from] : should match the bare jid you entered in your settings.
• iq[@id] : random string (enables you to match the superfeedr response with your query).
• unsubscribe[@node] : use the url of the resource you want to stop monitoring.
• unsubscribe[@jid] : use your 'bare' jid .

<iq type="set" from="you@superfeedr.com/home" to="firehoser.superfeedr.com" id="unsub1">
 <pubsub xmlns="http://jabber.org/protocol/pubsub">
  <unsubscribe node="http://domain.tld/feed1.xml" jid="you@superfeedr.com"/>
  <unsubscribe node="http://domain.tld/feed2.xml" jid="you@superfeedr.com"/>
  <unsubscribe node="http://domain.tld/feed3.xml" jid="you@superfeedr.com" />
 </pubsub>
</iq>

You can remove up to 20 resources in your unsubscription query.

The server acknowledges the unsubscription.

<iq type="result" from="firehoser.superfeedr.com" to="you@superfeedr.com/home" id="unsub1" />

Listing Resources

• iq[@from] : should match the bare jid you entered in your settings.
• subscriptions[@page] : page number (subscriptions will be sent by batches of 20).
• subscribe[@jid] : use your 'bare' jid .

<iq type="get" from="you@superfeedr.com/home" to="firehoser.superfeedr.com" id="subman1">
 <pubsub xmlns="http://jabber.org/protocol/pubsub" xmlns:superfeedr="http://superfeedr.com/xmpp-pubsub-ext">
  <subscriptions jid="you@superfeedr.com" superfeedr:page="3"/>
 </pubsub>
</iq>

The server sends the list of resources to which you're subscribed for the page requested, as well as the status information for each of them.

<iq type="result"  to="you@superfeedr.com/home" id="subman1" from="firehoser.superfeedr.com">
 <pubsub xmlns="http://jabber.org/protocol/pubsub"  xmlns:superfeedr="http://superfeedr.com/xmpp-pubsub-ext" >
  <subscriptions superfeedr:page="3">
   <subscription node="http://domain.tld/path/to/resource" subscription="subscribed" jid="you@superfeedr.com" >
    <status xmlns="http://superfeedr.com/xmpp-pubsub-ext">
     <http code="200">9718 bytes fetched in 1.462708s : 2 new entries.</http>
     <next_fetch>2009-05-10T11:19:38-07:00</next_fetch>
    </status>
   </subscription>
   <subscription node="http://domain2.tld/path/to/another/resource" subscription="subscribed" jid="you@superfeedr.com" >
    <status xmlns="http://superfeedr.com/xmpp-pubsub-ext">
     <http code="200">9718 bytes fetched in 1.462708s.</http>
     <next_fetch>2009-05-10T11:19:38-07:00</next_fetch>
    </status>
   </subscription>
  </subscriptions>
 </pubsub>
</iq>

Notifications

Once you're following a resource, your xmpp client must be connected at all times ant new content. You will miss messages if your client is offline for too long.

We will send you a notification when we consider the resource as updated. For feeds, it's when a new entry has been added to the feed itself. We will then send only this new entry (or all the new entries at once). For arbitrary content, we compute a signature of the content when you first subscribe; later, when this signature changes, we will notify you with the whole resource. We use a CRC32 algorithm to compute these signatures and chances of collision (false positive) are extremely low.

Please see the schema information for details on the status, as well as the feed and entry informations.

<message from="firehoser.superfeedr.com" to="you@superfeedr.com">
 <event xmlns="http://jabber.org/protocol/pubsub#event">
  <status feed="http://domain.tld/feed.xml" xmlns="http://superfeedr.com/xmpp-pubsub-ext">
   <http code="200">9718 bytes fetched in 1.462708s : 2 new entries.</http>
   <next_fetch>2009-05-10T11:19:38-07:00</next_fetch>
   <title>Lorem Ipsum</title>
  </status>
  <items node="http://domain.tld/feed.xml">
   <item >
    <entry xmlns="http://www.w3.org/2005/Atom">
     <title>Soliloquy</title>
     <summary>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.</summary>
     <link rel="alternate" type="text/html" href="http://superfeedr.com/entries/12345789"/>
     <id>tag:domain.tld,2009:Soliloquy-32397</id>
     <published>2010-04-05T11:04:21Z</published>
    </entry>
   </item>
   <item>
    <entry xmlns="http://www.w3.org/2005/Atom">
     <title>Finibus Bonorum et Malorum</title>
     <summary>Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt.</summary>
     <link rel="alternate" type="text/html" href="http://superfeedr.com/entries/12345788"/>
     <id>tag:domain.tld,2009:Finibus-32398</id>
     <published>2010-04-06T08:54:02Z</published>
    </entry>
   </item>
  </items>
 </event>
</message>

Resource Retrieval

It is possible to retrieve the current data and status information of a resource to which you previously subscribed. You need to allow for a few seconds upon subscription to retrieve the content of newly subscribed resources. Note that each of these request will cost you one credit, as this data is pushed to you upon notification. Please avoid polling us as much as you can.

• iq[@from] : should match the bare jid you entered in your settings.
• iq[@id] : random string (enables you to match the superfeedr response with your query).
• iems[@node] : use the url of the resource you want to retrieve (must be URL-escaped).

<iq type="get" from="you@superfeedr.com/home" to="firehoser.superfeedr.com" id="items1">
 <pubsub xmlns="http://jabber.org/protocol/pubsub">
  <items node="http://domain.tld/path/to/resource" />
 </pubsub>
</iq>

The server sends back the current status of the resource, as well as the last entries (or full content) that we stored for this resource (if applicable). Please see the schema information for details on the status.

<iq from="firehoser.superfeedr.com" type="result" to="you@superfeedr.com/home" id="items1" >
 <pubsub xmlns="http://jabber.org/protocol/pubsub">
  <status xmlns="http://superfeedr.com/xmpp-pubsub-ext">
   <http code="304" >Content not modified</http>
   <next_fetch>2010-08-18T06:52:25+00:00</next_fetch>
   <period>43200</period>
   <last_fetch>2010-08-17T18:52:25+00:00</last_fetch>
   <last_parse>2010-08-17T07:48:17+00:00</last_parse>
   <last_maintenance_at>2010-08-17T07:48:07+00:00</last_maintenance_at>
  </status>
  <item>
   <entry xmlns="http://www.w3.org/2005/Atom">
    <title>Finibus Bonorum et Malorum</title>
    <summary>Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt.</summary>
    <link rel="alternate" type="text/html" href="http://superfeedr.com/entries/12345788"/>
    <id>tag:domain.tld,2009:Finibus-32398</id>
    <published>2010-04-06T08:54:02Z</published>
   </entry>
  </item>
   ...
 </pubsub>
</iq>

API Wrappers

XMPP can be scary. For those of you who don't want to mess with that, we have various wrappers (including Ruby, Perl, Python, Javascript/Node.js, Java and PHP) for the XMPP API. You can find them on our Github page. If you need one in another language, please contact us. Also, remember that these wrappers have been created by the community. Feel free to contribute to help improve them.

PubSubHubbub

Superfeedr is a PubSubHubbub hub; our hub is located at http://superfeedr.com/hubbub. We implement the Core Specification. The biggest advantage of using our PubSubHubbub API is that you can re-use your "subscriber" code with any other hub. You can also use any library that supports and implements PubSubHubbub.

Implementation

Our hub supports HTTP Basic Authentication, you need to authenticate your HTTP requests.

You should use https:// and hub.secret for complete security. (Learn more).

Please read the Subscriber Best Practices and do not hesitate to use tools like curl for debugging. You may also use our PubSubHubbub Console .

Subscriptions

The syntax for subscribe and unsubscribe is identical.

Please refer to the Core Specification for Subscription. If you use your Superfeedr subscriber credentials, we will not perform the verification of intent, unless of course you provide a 'hub.verify' param, as per the spec.

You can also specify the format in which you want the content pushed to you, if this content is a feed. For this, provide a HTTP header like this : Accept: application/json, we will then convert any notification to JSON. By default, we will send Atom. See schema below for more details in the schemas.

If the content to which you subscribed is arbitrary (not feed), the payload will be preserved.

Here is a short step by step:

• Send an POST request to http://superfeedr.com/hubbub, with HTTP Basic Authentication and the following params :
  • hub.mode : subscribe or unsubscribe
  • hub.callback : http://domain.tld/your/callback
  • hub.topic : http//feed.you.want.to/subscribe/to
  • hub.verify : [OPTIONAL] By default, if you use your Superfeedr susbcriber credentials, we will not verify your intent. However, if you provide either sync or async, we will proceed to the verification of intent.

Notifications

One of the benefits of Superfeedr's hub is that you will benefit from our standard schema mapping (for feeds only). Based on the Accept header provided upon subscription, we will push you Atom or JSON.

In case of failure, our server will retry 3 times to notify your endpoint. If after this they all failed, the notification will be dropped. You will later have to use the retrieval feature to get the content that you missed.

Additionally, we recommand that you check the HTTP headers upon notifications, as they include valuable information:

• X-Superfeedr-Credits: your credit balance. It should always decrease by 1 between 2 notifications. If it doesn't, it means you missed a notification.
• X-PubSubHubbub-Callback: your callback url.
• X-PubSubHubbub-Topic: the topic to which you subscribed. Very useful to easily unsubscribe if you haven't kept track of that subscription.
• X-Superfeedr-PubSubHubbub-Expire: expiration for you subscription.
• Content-Type: very useful to see how to parse the body.
• X-Superfeedr-Retried: If this header is present, it means we had trouble notification you on previous attempts. You should make sure your app doesn't encounter health issues.

Feed Retrieval

It is possible to retrieve the current data and status information of a resource that Superfeedr is managing on your behalf. Note that each of these request will cost you one credit, as this data is pushed to you upon notification. Please avoid polling us as much as you can.

• Send an GET request to http://superfeedr.com/hubbub, with HTTP Basic Authentication and the following params :
  • hub.mode : retrieve
  • hub.topic : http//feed.you.want.to/retrieve (make sure it's url escaped!)
• The response will be the current status of the feed, please see our schema information for more details. It will also include the last 10 entries that Superfeedr (if applicable) stored from that feed (or the last 10 versions of the resource). If the resource is not currently being managed by superfeedr, the server will return a 404.

Subscription status

The PubSubHubbub API is idem-potent, which means that when you perform a subscription request (or unsubscribe), the response tells you the state. However, if you want to query for the state of a subscription, you can use our status call.

• Send an GET request to http://superfeedr.com/hubbub, with HTTP Basic Authentication and the following params :
  • hub.mode : status
  • hub.topic : http//feed.you.want.to/retrieve
  • hub.callback : http://domain.tld/your/callback
• The response will always be empty, however the HTTP status tells you whether such a subscription was found with 302 or not found with 404.

Schema

Whatever the original format (RSS, Atom, or any other namespace) is, the notification that we will send to feed subscribers will use standard ATOM. We will match as much as we can into this format. The overall goal here is to make it easy for the subscriber to consume a consistent schema.

Status Schema

Warning: This section only applies to subscriptions to resources which are feeds. If the resource is arbitrary (including HTML, JSON, YAML, VCard... etc), the content will be preserved.

Upon notifications, when subscribing (XMPP only), or when retrieving a resource's content from Superfeedr, you'll see that it may include the following information. This data is useful for you to know the current status of a resource. Please note that some items my be missing at some point, either because we haven't processed the feed yet, or because they wouldn't be accurate.

• status[@feed] : contains the URL of the resource.
• http[@code] : last HTTP status code, please see Status Code Definitions.
• http : the content of that tag is a more explicit log message for your information.
• next_fetch : the resource will be fetched at most before this time.
• period : the polling frequency in seconds for this resource (at least 60 seconds for feeds and at least 300 seconds for arbitrary content).
• last_fetch : the last time at which we fetched the resource.
• last_parse : the last time at which we parsed the resource. It happens that we fetch a resource and do not parse it as its content hasn't been modified.
• last_maintenance_at : Each resource inside Superfeedr has a maintenance cycle that we use to detect stale resource, or related resource. We normally run maintenance at most every 24hour for each resource, but this is a low priority task, so it may go beyond this.
• entries_count_since_last_maintenance (provided only upon notification) : The number of updates in the resource since we last ran the maintenance script. This is a very good indicator of the verboseness of a resource. You may want to remove resources that are too verbose.
• title (provided only upon notification, for feeds only) : the feed title.
• publisher (provided only upon retrieve, for feeds only) : set to true if Superfeedr hosts a hub for this feed.

<status feed="http://domain.tld/feed.xml" xmlns="http://superfeedr.com/xmpp-pubsub-ext">
 <http code="200">9718 bytes fetched in 1.462708s : 2 new entries.</http>
 <next_fetch>2010-05-10T11:19:38-07:00</next_fetch>
 <period>900</period>
 <last_fetch>2010-05-10T11:19:38-07:00</last_fetch>
 <last_parse>2010-05-10T11:17:19-07:00</last_parse>
 <last_maintenance_at>2010-05-10T09:45:08-07:00</last_maintenance_at>
 <entries_count_since_last_maintenance>5</entries_count_since_last_maintenance>
 <tilte>Lorem Ipsum</tilte>
</status>

Entry Schema (feeds only)

Notification entries will have the following form. It is standard ATOM. Here are the fields that you will see in the notification. Please note that an entry might not have all of them.

At the entry level, you may see a stripped attribute, belonging to the Superfeedr namespace. If set to true, it indicates that the content or summary of this entry was bigger than 1MB and that we stripped it.

Here are the components used to build the entries. Please note that they may use specific namespaces.

Link

• link[@href] : the url related to the parent node
• link[@rel] (optional) : the type of relation to that parent node (alternate, reply... etc)
• link[@type] (optional) : MimeType of the link destination (tex/html by default)
• link[@title] (optional) : the link title.

<link href="http://domain.tld/entries/12345" rel="alternate" type="text/html" title="The sky is Blue" />
<link href="http://domain.tld/entries/12345/comments.xml" rel="replies" type="application/atom+xml" title="Comments on The sky is Blue" />

Category

• category[@term] (optional, multiple) : a keyword related to the entry... (tag, category or topic)

<category term="tag" />
<category term="category" />

Point

• entry[@point] (optional, multiple) : geolocation data. Contains a georss latitude and longitude related to the story. It's either extracted from the story or extrapolated from the content.

<point xmlns="http://www.georss.org/georss">47.597553 -122.15925</point>

Author

• author(optional, multiple).
  • name : the author's name (or nickname)
  • email (optional) : the author's email address
  • uri (optional) : the author's URI
  • object-type (optional, multiple) : the object type, defined in the ActivityStreams spec
  • link (optional, multiple) : links (see above). They can include links to the author's profile, to the user's avatar...

<author>
 <name>John Doe</name>
 <email>john@superfeedr.com</email>
 <uri>http://twitter.com/superfeedr</uri>
 <as:object-type>http://activitystrea.ms/schema/1.0/person</as:object-type>
 <link type="image/png" title="John Doe" href="http://domain.tld/john.png" rel="image"/>
</author>

Object

• objectActivityStreams (optional, multiple).
  • object-type (required, multiple) : the object type, defined in the ActivityStreams spec
  • id (optional) : the unique identifier of the object
  • title (optional) : the title of the object
  • published (optional) : the publication date (iso8601) of the object.
  • updated (optional) : the updated date (iso8601) of the object.
  • content (optional) : the content of the object.
  • author (optional, multiple) : author information (see above).
  • category (optional, multiple) : categories (see above).
  • link (optional, multiple) : links (see above).

<as:object-type>http://gowalla.com/schema/1.0/spot</as:object-type>
<as:object-type>http://activitystrea.ms/schema/1.0/place</as:object-type>
<id>object-id</id>
<title>Title of the Object</title>
<published>2010-04-20T15:00:40+02:00</published>
<updated>2010-04-21T14:00:40+02:00</updated>
<content>hello world</content>
<author>
 <name>Second</name>
 <uri>http://domain.tld/second</uri>
 <email>second@domain.tld</email>
</author>
<link type="text/html" title="" href="http://domain.tld/object/2" rel="alternate"/>
<link type="text/html" title="" href="http://domain.tld/object/2" rel="alternate"/>

Verb

• verb(optional, multiple) : defined in the ActivityStreams spec.

http://activitystrea.ms/schema/1.0/post

Entries

Entries may include all the above elements. They also contain specific nodes, listed below.

• entry[@xml:lang] : The language of the entry. It's either extracted or computed from the content (the longer the content, the more relevant).
• entry[@title] : The title of the entry.
• entry[@id] : the Unique ID of the entry. If the original entry doesn't have an ID.
• entry[@published] : The publication date (iso8601) of the entry.
• entry[@updated] : The last updated date (iso8601) of the entry.
• entry[@content] : The content of the entry. Check the type attribute to determine the mime-type.
• entry[@summary] (optional, unique) : The summary of the entry. Check the type attribute to determine the mime-type
• entry[@source] (optional, unique) : The source of the entry. It includes all the available feed level elements, such as the feed title, the feed links, the feed's author(s)... etc. It's extremely useful for track feeds.

<entry xmlns="http://www.w3.org/2005/Atom" xmlns:geo="http://www.georss.org/georss" xmlns:as="http://activitystrea.ms/spec/1.0/" xml:lang="en">
 <id>domain.tld:09/05/03-1</id>
 <published>2010-04-21T14:00:40+02:00</published>
 <updated>2010-04-21T14:00:40+02:00</updated>
 <title>Entry published on hour ago</title>
 <content type="text">Entry published on hour ago when it was shinny outside, but now it's raining</content>
 <summary type="text">Entry published on hour ago...</summary>
 <geo:point>47.597553 -122.15925</geo:point>
 <link type="text/html" title="" href="http://domain.tld/entry/1" rel="alternate"/>
 <link type="application/atom+xml" title="" href="http://domain.tld/entry/1.xml" rel="replies"/>
 <link type="image/png" title="A beautiful picture that illustrates the entry" href="http://domain.tld/entry/image_.png" rel="picture"/>
 <category term="Things"/>
 <category term="Picture"/>
 <author>
  <name>First</name>
  <uri>http://domain.tld/first</uri>
  <email>first@domain.tld</email>
  <id>id-first</id>
  <title>First</title>
  <as:object-type>http://activitystrea.ms/schema/1.0/person</as:object-type>
  <as:object-type>http://activitystrea.ms/schema/1.0/dude</as:object-type>
  <link type="image/png" title="A beautiful picture that illustrates the author" href="http://domain.tld/first.png" rel="picture"/>
  <link type="text/html" title="The profile page of the author" href="http://domain.tld/first/profile" rel="alternate"/>
 </author>
 <author>
  <name>Second</name>
  <uri>http://domain.tld/second</uri>
  <email>second@domain.tld</email>
 </author>
 <as:verb>http://activitystrea.ms/schema/1.0/post</as:verb>
 <as:verb>http://activitystrea.ms/schema/1.0/publish</as:verb>
 <as:object>
  <as:object-type>http://gowalla.com/schema/1.0/spot</as:object-type>
  <as:object-type>http://activitystrea.ms/schema/1.0/place</as:object-type>
  <id>object-id</id>
  <title>Title of the Object</title>
  <published>2010-04-20T15:00:40+02:00</published>
  <updated>2010-04-21T14:00:40+02:00</updated>
  <content>hello world</content>
  <author>
   <name>Second</name>
   <uri>http://domain.tld/second</uri>
   <email>second@domain.tld</email>
  </author>
  <link type="text/html" title="" href="http://domain.tld/object/2" rel="alternate"/>
  <link type="text/html" title="" href="http://domain.tld/object/2" rel="alternate"/>
 </as:object>
 <source>
  <id>feed-id</id>
  <title>feed-title<title>
  <updated>2010-04-21T14:00:40+02:00</updated>
  <link href="http://domain.tld/entries/12345" rel="alternate" type="text/html" title="The sky is Blue" />
  <link href="http://domain.tld/entries/12345/comments.xml" rel="replies" type="application/atom+xml" title="Comments on The sky is Blue" />
</source>
</entry>

JSON normalization (feeds only)

Superfeedr offers the ability to subscribe to Atom and RSS feeds, but receive notifications (both via XMPP and PubSubHubbub) in JSON. It's a mapping of our

{
 "status": {
   "entriesCountSinceLastMaintenance": 24,
   "lastParse": 1290793065,
   "period": "600",
   "lastMaintenanceAt": 1290778665,
   "feed": "http://domain.tld/feed.xml",
   "lastFetch": 1290796665,
   "code": 200,
   "title": "A wonderful feed",
   "nextFetch": 1290803865,
   "http": "Awesome we got the feed right"
  },
  "items": [
   {
    "geo": {
     "type": "point",
     "coordinates": [
      47.597553,
      -122.15925
     ]
    },
    "standardLinks": {
     "picture": [
      {
       "type": "image/png",
       "href": "http://domain.tld/entry/image_.png",
       "title": "A beautiful picture that illustrates the entry"
      }
     ],
     "replies": [
      {
       "type": "text/html",
       "href": "http://domain.tld/entry/1.xml",
       "title": ""
      }
     ]
    },
    "permalinkUrl": "http://domain.tld/entry/1",
    "verb": "publish",
    "content": "Entry published on hour ago when it was shinny outside, but now it's raining",
    "published": 1271851240,
    "actor": {
     "displayName": "First",
     "image": {
      "url": "http://domain.tld/first.png"
     },
     "permalinkUrl": "http://domain.tld/first/profile",
     "id": "id-first",
     "objectType": "dude",
     "title": "First"
    },
    "categories": [
     "Things",
     "Picture"
    ],
    "id": "domain.tld:09/05/03-1",
    "object": {
     "permalinkUrl": "http://domain.tld/object/2",
     "content": "hello world",
     "published": 1271768440,
     "actor": {
      "displayName": "Second",
      "permalinkUrl": "http://domain.tld/second"
     },
     "id": "object-id",
     "updated": 1271851240,
     "title": "Title of the Object",
     "objectType": "place"
    },
    "title": "Entry published on hour ago",
    "updated": 1271851240,
    "source": {
      "id": "http://blog.superfeedr.com/",
      "title": "Superfeedr Blog",
      "updated": 1245776753,
      "permalinkUrl": "http://blog.superfeedr.com/",
    }
   },
   {
    "permalinkUrl": "http://www.macrumors.com/2009/05/06/adwhirl-free-ad-supported-iphone-apps-can-very-lucrative/",
    "published": 1241616887,
    "content": "Mobile advertising company AdWhirl issued a report (PDF) that details the success of some of the top ad-supported iPhone apps. AdWhirl serves 250 million ad impressions monthly to over 10% of the top 50 Apps in the App Store.br /\n   br /\n   br /\n   ...",
    "id": "http://www.macrumors.com/2009/05/06/adwhirl-free-ad-supported-iphone-apps-can-very-lucrative/",
    "title": "AdWhirl: Free Ad-Supported iPhone Apps Can Be Very Lucrative"
   }
  ],
  "subtitle": "This is certainly a wonderful feed that you need to read!",
  "standardLinks": {
   "canonical": [
    {
     "type": "application/atom+xml",
     "href": "http://feed.domain.tld/main.xml",
     "title": null
    }
   ],
   "self": [
    {
     "type": "application/atom+xml",
     "href": "http://domain.tld/feed.xml",
     "title": null
    }
   ]
  },
  "id": "http://domain.tld/feed.xml",
  "title": "A wonderful feed",
  "updated": 1290800265
 }