diff --git a/Implementing-a-Torznab-indexer.md b/Implementing-a-Torznab-indexer.md index 371f030..0ca20d0 100644 --- a/Implementing-a-Torznab-indexer.md +++ b/Implementing-a-Torznab-indexer.md @@ -11,6 +11,99 @@ It's also imperative to think about how to integrate this in your existing karma ##Differences with Newznab## +Torznab extends on Newznab on a couple of points to make it more useful. However, it is in principle backward compatible. + +###Torznab queries### + +Newznab defines the query params `q,rid,season,ep` for `t=tvsearch` and `q` for `t=search`, however not all sites support tvrage ids, and therefore would have to be queries with the q= param. +Torznab implementations should return the supported query params in their `t=caps` response. (more on `caps` later) +Implementations should also take care in returning appropriate responses when a query includes an unsupported newznab parameter, for example, if rid is not supported, return an empty result set. +This is to remain backward compatibility with clients that do not query the caps. + +Newznab does not define `tvdbid=` and `imdbid=`, but implementors are recommended to support these if possible. + +``` +t=tvsearch: + Newznab query params: q,rid,season,ep + Torznab query params: tvdbid +t=search: + Newznab query params: q +t=movie: + Newznab query params: q + Torznab query params: imdbid +``` + +Examples: +``` +?t=tvsearch&cat=..,..&rid=..&season=1&episode=1 +?t=tvsearch&cat=..,..&q=..&season=1&episode=1 + +?t=tvsearch&cat=..,..&rid=..&season=2016&ep=12/20 +?t=tvsearch&cat=..,..&q=..&season=2016&ep=12/20 + +?t=search&cat=..,..&q=Anime+Title+123 +?t=search&cat=..,..&q=Fantastic+Series+With+Episode+Title+For+Special +``` + +###Torznab caps endpoint### + +The mode `t=caps` is supposed to return the capabilities and categories of the newznab/torznab indexer. +Implementing this mode is mandatory. + +The caps response for torznab is mostly the same as newznab, except for a few points: + +The `searching` element is normally used to specify what kind of modes (`tvsearch`,`search`,`movie`) the api supports. But torznab adds an optional `supportedParams` attribute allowing the api to specify which query params are supported. +If the `supportedParams` attribute is not found, then it defaults to the original newznab params as specified earlier. + +Many torrent sites have their own categories starting at '1', it's recommended NOT to map these 1 to 1 on newznab categories but instead add 100000 to the number. +That way it falls in the site specific range and does not interfere with the original newznab categories. +The api should then alias all site-specific categories in one of the original newznab category. +For example, if you have category 10 as Blu-Ray 1080p TV, then releases in that category would use the torznab api cats 100010,5040,5000 (Site-specific, TV/HD, TV). +Any query that includes any of those numbers in the `cat=` parameter would return those releases as results. +Of course it's also allowed to omit the site-specific categories entirely, and map only on newznab categories. + +Example `t=caps` response: +``` + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + + +###Torznab results### First and foremost: Torznab indexers should return application/x-bittorrent as enclosure type: ```