BORGET Sebastien

Pages

Home

Purpose of this document

This document, written by BORGET Sebastien, intends to specify a standard as regards RSS 2.0 feeds of BitTorrent (*) websites (trackers and listing sites). Currently, each webmaster has designed his own feed according to his willing, with good-sense of what users could be waiting for. Their RSS 2.0 feeds are valid, and useful to users, but the fact that each feed on every site is different leads to several issues:

misunderstanding and confusion:

when switching from one feed to another, the way information is presented about the torrents varies, which could lead users to confusion

difficulties for feeds reading softwares and scripts:

feed reading software have to develop modifications regarding to one feed, that might not work for another. A standard feed will make integration easier, and can open new possibilities: torrent indexing scripts working on rss feeds …

Also, defining a standard can offer new features to users:

more informations in the feed:

the white paper adds new elements to the feed, that are particular to BitTorrent and give more information details about a torrent: seeders, leechers, time completed, owner … These elements are still facultative to ensure backward compatibility with the current rss 2.0 feeds.

future applications:

maintaining an updated standard helps to guarantee compatibility with both existing and incoming applications of bittorrent.

(*) If you do not know what BitTorrent is, please refer to this document.

Header Specifications

This is what has to be put at the beginning of the feed, to declare it is a rss 2.0 feed.
In order to give a definition for the new elements we will introduce later in the Items part, we have to specify it inside a namespace url:

xmlns:bittorrent=”http://www.borget.info/bittorrent-rss/”

First remark, I have chosen the namespace name bittorrent, because it is self-explanatory.
Then, about this namespace URL. It should theorically not be changed, because this url resolves to this page, explaining how the feed works.

In case you would like to change this url, here are some recommandations to follow (to comply with the rss 2.0 extension specifications). Not following these rules will make your feed incompatible with the rss2.0 standards !

the URL has to end with either # or /
it doesn’t have to resolve to any document (but it’s good practice to have a document explaining more about the elements).

Now, this is what your header should be:

 <rss version="2.0"
     xmlns:bittorrent="http://www.borget.info/bittorrent-rss/" >
 .
 .
 .
 .
 .
 </rss>

Channel Specifications

Required Elements:

These elements are the minimum required for the channel element of the feed. Each one is given with a brief description; if you want a more complete description, please refer to the official rss 2.0 specification. It is strongly recommanded to put them in the following order, mostly to ease human reading but also for presentation matters:

title

Name of the site

link

URL of the site

description

Description of the site and/or the content of the feed

language

Language used in this feed

pubDate

The publication date for the content in the channel. All date-times in RSS conform to the Date and Time Specification of RFC 822, with the exception that the year may be expressed with two characters or four characters (four preferred).

<title>BORGET</title>
<link>http://www.borget.info</link>
<description>RSS feed for Borget.info website</description>
<language>en-us</language>
<pubDate>Sun, 23 Jul 2006 12:35:31 GMT</pubDate>

Optional Elements:

These elements are optional, but adding them to the channel element is highly recommanded for understanding purposes.

lastBuildDate

The last time the content of the channel changed. All date-times in RSS conform to the Date and Time Specification of RFC 822, with the exception that the year may be expressed with two characters or four characters (four preferred).

copyright

webMaster

Email address for the webmaster of the site

category

Specify the category (if any) of the content of this feed

generator

A string indicating the program used to generate the channel

ttl

ttl stands for time to live. It’s a number of minutes that indicates how long a channel can be cached before refreshing from the source.

<lastBuildDate>Mon, 24 Jul 2006 16:28:47 GMT</lastBuildDate>
<copyright>Copyright 2006, BORGET Sebastien</copyright>
<webMaster>webmaster(*AT*)borget.info</webMaster>
<category>All</category>
<generator>BORGET.info RSS Generator</generator>
<ttl>30</ttl>

A complete RSS channel example would be:

<channel>
	<title>BORGET</title>
	<link>http://www.borget.info</link>
	<description>RSS feed for Borget.info website</description>
	<language>en-us</language>
	<pubDate>Sun, 23 Jul 2006 12:35:31 GMT</pubDate>
	<lastBuildDate>Mon, 24 Jul 2006 16:28:47 GMT</lastBuildDate>
	<copyright>Copyright 2006, BORGET Sebastien</copyright>
	<webMaster>webmaster(removethis)@borget.info</webMaster>
	<category>All</category>
	<generator>BORGET.info RSS Generator</generator>
	<ttl>30</ttl>
	.
	.
	.
	.
</channel>

Item Specifications

Required Elements:

These elements are the minimum required for each item element of the feed. Each one is given with a brief description; if you want a more complete description, please refer to the official rss 2.0 specification. It is strongly recommanded to put them in the following order, mostly to ease human reading but also for presentation matters:

title

Name of the torrent file or Brief description of the torrent

description

Full description of the torrent

category

Category of the torrent

link

URL of the webpage where the torrent details are displayed

guid

Any URL related to the torrent content (example: developer’s website for a software)

pubDate

bittorrent:seeders

Number of seeders on the torrent

bittorrent:leechers

Number of leechers on the torrent

<title>Linux Operating System</title>
<description>
Latest version of this unix operating system,
with many new features included, like a 3D desktop...
The system is preloaded with dozen of games, applications ...
</description>
<category>Operating Systems</category>
<link>
http://www.linux.org/downloads/index.php?version=latest
</link>
<guid>
http://www.linux.org/
</guid>
<pubDate>Sun, 23 Jul 2006 12:35:31 GMT</pubDate>
<bittorrent:seeders>523</bittorrent:seeders>
<bittorrent:leechers>4892</bittorrent:leechers>

Optional Elements:

enclosure

URL of the attached .torrent file. It has three required attributes: url says where the enclosure is located, length says how big it is in bytes, and type says what its type is, a standard MIME type.

Example:

<enclosure
	url="http://www.borget.info/dl.php?id=70"
	length="2147483647" type="application/x-bittorrent" />

comments

URL to the page where comments about the torrent are shown

bittorrent:creator

Nickname of the torrent submitter

bittorrent:info_hash

The info_hash of the torrent, in hex string format (40 bytes long)

bittorrent:completed

Number of times a download was completed on the torrent

bittorrent:downloaded

Number of times the .torrent file was downloaded on the site

bittorrent:dht

DHT link of the torrent

bittorrent:magnet

MAGNET link of the torrent

<enclosure
url="http://www.linux.org/dl.php?id=70"
length="5237483647" type="application/x-bittorrent" />
<comments>http://www.linux.org/latest/comments.php</comments>
<bittorrent:creator>Mr WHO Areyou</bittorrent:creator>
<bittorrent:info_hash>
d1d5e5bc5001cc7847888603586803056e5e5370
</bittorrent:info_hash>
<bittorrent:completed>65432</bittorrent:completed>
<bittorrent:downloaded>432</bittorrent:completed>
<bittorrent:dht>
dht://D1D5E5BC5001CC7847888603586803056E5E5370.dht
</bittorrent:dht>
<bittorrent:magnet>
magnet:?xt=urn:btih:SG6NWXONGELSNYHGR5H7H3ODJNLTM4RF
</bittorrent:magnet>

A complete example for an item:

<item>
	<title>Linux Operating System</title>
	<description>
	Latest version of this unix operating system,
	with many new features included, like a 3D desktop...
	The system is preloaded with dozen of games, applications ...
	</description>
	<category>Operating Systems</category>
	<link>
	http://www.linux.org/downloads/index.php?version=latest
	</link>
	<guid>
	http://www.linux.org/
	</guid>
	<pubDate>Sun, 23 Jul 2006 12:35:31 GMT</pubDate>
	<bittorrent:seeders>523</bittorrent:seeders>
	<bittorrent:leechers>4892</bittorrent:leechers>
	<enclosure
	url="http://www.linux.org/dl.php?id=7"
	length="5237483647" type="application/x-bittorrent" />
	<comments>http://www.linux.org/latest/comments.php</comments>
	<bittorrent:creator>Mr WHO Areyou</bittorrent:creator>
	<bittorrent:info_hash>
	d1d5e5bc5001cc7847888603586803056e5e5370
	</bittorrent:info_hash>
	<bittorrent:completed>65432</bittorrent:completed>
	<bittorrent:downloaded>432</bittorrent:completed>
	<bittorrent:dht>
	dht://D1D5E5BC5001CC7847888603586803056E5E5370.dht
	</bittorrent:dht>
	<bittorrent:magnet>
	magnet:?xt=urn:btih:SG6NWXONGELSNYHGR5H7H3ODJNLTM4RF
	</bittorrent:magnet>
</item>

Sample Feed

This is a sample feed with various items mixing required and optional elements, so you can have an idea of what your final rss2.0 feed will look like on your site.

<rss version="2.0"
     xmlns:bittorrent="http://www.borget.info/bittorrent-rss/" >
<channel>
<title>BORGET</title>
<link>http://www.borget.info</link>
<description>RSS feed for Borget.info website
</description>
<language>en-us</language>
<pubDate>Sun, 23 Jul 2006 12:35:31 GMT</pubDate>
<copyright>Copyright 2006, BORGET Sebastien</copyright>
<webMaster>webmaster(removethis)@borget.info</webMaster>
<generator>BORGET.info RSS Generator</generator>
<ttl>30</ttl>

<item>
<title>Linux Operating System</title>
<description>
Latest version of this unix operating system,
with many new features included, like a 3D desktop...
The system is preloaded with dozen of games, applications ...
</description>
<category>Operating Systems</category>
<link>
http://www.linux.org/downloads/index.php?version=latest
</link>
<guid>
http://www.linux.org/
</guid>
<pubDate>Sun, 23 Jul 2006 12:35:31 GMT</pubDate>
<bittorrent:seeders>523</bittorrent:seeders>
<bittorrent:leechers>4892</bittorrent:leechers>
<bittorrent:downloaded>8932</bittorrent:completed>
<bittorrent:creator>Mr WHO Areyou</bittorrent:creator>
<bittorrent:info_hash>
d1d5e5bc5001cc7847888603586803056e5e5370
</bittorrent:info_hash>
<bittorrent:dht>
dht://D1D5E5BC5001CC7847888603586803056E5E5370.dht
</bittorrent:dht>
</item>

<item>
<title>>Open Source CMS</title>
<description>A great and easy to use CMS in php/mysql
</description>
<category>Softwares</category>
<link>
http://www.cms4you.com/downloads/details.php?id=70
</link>
<guid>
http://www.cms4you.com
</guid>
<pubDate>Sun, 23 Jul 2006 10:35:31 GMT</pubDate>
<bittorrent:seeders>53</bittorrent:seeders>
<bittorrent:leechers>492</bittorrent:leechers>
<enclosure
url="http://www.cms4you.com/dl.php?id=70"
length="1237483647" type="application/x-bittorrent" />
<bittorrent:completed>652</bittorrent:completed>
<bittorrent:dht>
dht://D2C5E5BC5001CC7847888603586803056E5E5370.dht
</bittorrent:dht>
<bittorrent:magnet>
magnet:?xt=urn:btih:SG6NWXONGELSNYHGR5H7H3ODJNLTM4RF
</bittorrent:magnet>
</item>

</channel>
</rss>

You can check here that this feed is validated by the W3C:

Note: the values inside this sample are totally fake, the info_hash and magnet links do not correspond at all ! This is just to show how it looks like.

Additions

Feel free to discuss and leave comments on these specifications. The discussion is open, and I think we should work together to define them, so a standard appears.
I have written the first rough, I hope it will help as a basis all webmasters willing to implement a RSS 2.0 feed on their website.

Do not also hesitate to get in touch with me using the contact form of this site !