newznab Usenet Searching Web API
v0.5
2015-10-24
Authors:
ensi ensisoft@gmail.com
newznab http://newznab.com/
nZEDb https://github.com/nZEDb/nZEDb
1. Introduction
2. Functions
2.1 CAPS
2.2 REGISTER
2.3 SEARCH
2.4 TV-SEARCH
2.5 MOVIE-SEARCH
2.6 DETAILS
3. Predefined Categories
4. Predefined Attributes
4.1 List of Attributes
4.2 Attribute example
5. nZEDb Error Codes
5.1 Error code example
6 Changelog
1. Introduction
This document describes the newznab/nZEDb Usenet Searching Web API. The API is designed to be implemented
by Usenet indexing sites, i.e. sites that index Usenet newsgroups through some means, typically
by downloading and inspecting the NNTP headers. The API is aimed for NZB aware client applications
to allow them to perform Usenet searches against nZEDb servers and receive NZB information in order
to facilitate direct downloading from Usenet without having to download any NNTP headers.
This document does not describe the actual implementation of either the client or the server but just
describes the HTTP(S) interface and request/response sequences.
Intended readers are server and client implementers.
1.1 Notation
This document uses the following notations:
Parameters: "t=c" denotes a required HTTP query parameter. [o=json | o=xml] denotes optional
parameters with possible values.
2. Functions
All functions are executed as HTTP(S) requests over TCP. All parameters are to be passed
as query parameters unless otherwise indicated. All returned XML/JSON data is UTF-8 encoded
unless otherwise specified. All query parameters should be UTF-8 and URL encoded, i.e.
query-param = URL-ENCODE(UTF8-ENCODE(param=value)).
The functions are divided into two categories. Functions specific to searching and retrieving of items
and the their information such as SEARCH and TV-SEARCH and functions that are for site/user account
management such as CAPS and REGISTER.
Any conforming implementation should support the CAPS and SEARCH functions. Other functions are optional
and if not supported will return the "203 Function Not Available" when invoked.
2.1 CAPS
Description:
CAPS function is used to query the server for supported features and the protocol version and other
meta data relevant to the implementation. This function does not require the client to provide any
login information but can be executed out of "login session".
Important fields of the returned data:
server/version The version of the protocol implemented by the server. All implementations should be backwards compatible.
limits The limit and defaults to the number of search results returned.
retention Server retention (how many days NZB information is stored before being purged).
category Defines a searchable category which might have any number of subcategories.
category/id Unique category ID, can be either one of the standard category IDs or a site specific ID.
category/name Any descriptive name for the category. Can be site/language specific.
category/description A description of the contents of the category.
category/subcat A subcategory.
category/subcat/id/ Unique category ID, can be either one of the standard category IDs or a site specific ID.
category/subcat/name Any descriptive name for the category. Can be site/language specific.
category/subcat/description A description of the contents of the category.
HTTP Method:
GET
HTTP Response:
200 OK
Parameters:
t=caps Caps function, must always be "caps".
Optional parameters:
o=xxx Output format, either "JSON" or "XML. Default is "XML".
Examples:
--> GET http://servername.com/api?t=caps
<-- 200 OK
2.2 REGISTER
Description:
REGISTER function is used for automatically creating and registering user account.
This is an optional function and may or may not be available at a site. It is also possible
that function is available but currently registrations at the site are closed.
The only prerequisite for registering an account is a valid email address and any server policies.
It is at the server administration discretion to allow or deny registrations based on
for example the validity of the email address or the the current client host address.
On successful registration a valid username, password and api key are returned to the caller
On error an appropriate error code is returned.
HTTP Method:
GET
HTTP Response:
200 OK
Parameters:
t=register Register function, must always be "register"
email=xxx A valid email address to be used for registration. (URL/UTF-8 encoded).
Examples:
--> GET HTTP://servername.com/api?t=register&email=john.joe%40acme.com
<-- 200 OK
--> GET HTTP://servername.com/api?t=register&email=john.joe%40acme.com
<-- 200 OK
--> GET HTTP://servername.com/api?t=register&email=john.joe%40acme.com
<-- 200 OK
--> GET HTTP://servername.com/api?t=register&email=john.joe%40acme.com
<-- 200 OK
2.3 SEARCH
Description:
SEARCH function searches the index for items matching the search criteria. On successful
search the response contains a list of found items. Even if search matched nothing an empty
response set is created and returned. This function requires passing the user credentials.
Searches that include categories that are not supported by the server are still executed
but the non-supported categories are simply skipped. This basically treats such a search
simply as a "no match" but allows the same query to be ran simultaneously against several
servers.
The list of search categories specifies a logical OR condition. I.e. an item matching the
search input in any of the specified categories is considered a match and is returned. E.g.
a search searching for "linux" in "computer" and "ebook" categories searches for matching
items in "computer" and "ebook" but does not search for example the "movies" category.
Items found in either group are then combined into a single result set. If the input string
for search is empty all items (within the server/query limits) are returned for the
matching categories.
When performing the query the categories to be searched are concatenated into a single
query parameter by , (comma). For example "cat=200,300,400", which is then URL encoded.
The returned XML data stream is RSS 2.0 compliant and also contains additional information
in the extra namespace.
Response-offset field identifies the current subset of all the matches that are being
transmitted in the response. In other words, if a search for "disco" finds more matches
than the server is capable of transmitting in a single response, the response needs to be
split into several responses. Then it is the clients responsibility to repeat the same
query with same parameters but specify an increased offset in order to return the next
set of results.
If offset query parameter is not used response data contains items between 0 offset - limit.
If offset query parameter is out of bounds an empty result set is returned.
Important fields of the returned data (RSS):
title Title of the found item.
guid A globally unique (GUID) item identifier.
pubdate The publishing date in RSS date object as specified by RFC822/2822. (not the Usenet date)
category The category the NZB belongs to. (This is human readable for RSS. More precise category is found in additional data)
enclosure The NZB url
HTTP Method:
GET
HTTP Response:
200 OK
Parameters:
t=search Search function, must always be "search"
apikey=xxxx User's key as provided by the service provider.
Optional parameters:
q=xxxx Search input (URL/UTF-8 encoded). Case insensitive.
limit=123 Upper limit for the number of items to be returned.
cat=xxx List of categories to search delimited by ","
o=xxx Output format, either "JSON" or "XML". Default is "XML".
extended=1 Return extended information in the search results. (See DETAILS).
del=1 Delete the item from a users cart on download.
maxage=123 Only return results which were posted to usenet in the last x days.
offset=50 The 0 based query offset defining which part of the response we want.
Examples:
--> GET http://servername.com/api?t=search&apikey=xxxxx&q=a%20tv%20show
<-- 200 OK
example.com</tile>
<description>example.com API results</description>
<!--
More RSS content
-->
<!-- offset is the current offset of the response total is the total number of items found by the query -->
<newznab:response offset="0" total="2344"/>
<item>
<!-- Standard RSS 2.0 Data -->
<title>A.Tv.Show.S06E05.DVDRIP.XviDhttp://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c
http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9
http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c#commentsSun, 06 Jun 2010 17:29:23 +0100TV > XviDSome TV show
// no items matched the search criteria
--> GET http://servername.com/api?t=search&apikey=xxxxx&q=linux%20image
<-- 200 OK
// Query could not be completed because user credentials are broken
--> GET http://servername.com/api?t=search&apikey=xxxxx&q=linux%20image
<-- 200 OK
// Query could not be completed because it was malformed
--> GET http://servername.com/api?t=search&apikey=xxxxx&q=linux%20image
<-- 200 OK
2.4 TV-SEARCH
Description:
TV-SEARCH function searches the index in the TV category for items matching the search criteria.
The criteria includes query string and in addition information about season and episode.
On successful search the response contains a list of items that matched the query. Even if the
search matched nothing an empty but valid response is created and returned. This function
requires passing the user credentials.
It is important to note, that all parameters are treated as AND operations execept for rid, tvdbid,
traktid, tvmazeid, imdbid, and tmdbid. Supplying any combination (some, none, all) of these values will
return results applicable for each value respective to the other AND parameters.
The returned XML data stream is RSS 2.0 compliant and also contains additional information
in the extra namespace and optionally TV specific information
HTTP Method:
GET
HTTP Response:
200 OK
Parameters:
t=tvsearch TV-Search function, must always be "tvsearch".
apikey=xxx User's key as provided by the service provider.
Optional parameters:
limit=123 Upper limit for the number of items to be returned, e.g. 123.
rid=xxxx TVRage id of the item being queried.
tvdbid=xxxx TVDB id of the item being queried.
traktid=xxxx TraktTV id of the item being queried.
tvmazeid=xxxx TVMaze id of the item being queried.
imdbid=xxxx IMDB id of the item being queried.
tmdbid=xxxx TMDB id of the item being queried.
cat=xxx List of categories to search delimited by ","
season=xxxx Season string, e.g S13 or 13 for the item being queried. Can also be YYYY for Daily Show.
q=xxxx Search input (URL/UTF-8 encoded). Case insensitive.
ep=xxx Episode string, e.g E13 or 13 for the item being queried. Can also be MM/DD for Daily Show.
o=xml Output format, either "JSON" or "XML". Default is "XML".
extended=1 Return extended information in the search results
del=1 Delete the item from a users cart on download.
maxage=123 Only return results which were posted to usenet in the last x days.
offset=50 The 0 based query offset defining which part of the response we want.
Examples:
--> GET http://servername.com/api?t=tvsearch&apikey=xxxq=lost&season=S03
<-- 200 OK
example.comexample.com API resultsLand.of.the.Lost.S03E02.Survival.Kit.iNTERNAL.DVDRip.XViD-SPRiNTERhttp://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c
http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9
http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c#commentsSun, 06 Jun 2010 17:29:23 +0100TV > XviDSome TV showLost.S03E01.720p.BluRay.DTS.x264.INTERNAL-hVhttp://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c
http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9
http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c#commentsSun, 06 Jun 2010 17:29:23 +0100TV > XviDSome TV show
2.5 MOVIE-SEARCH
Description:
MOVIE-SEARCH function searches the index for items matching an IMDB id or search query.
On successful search the response contains a list of items that matched the query. Even if the
search matched nothing an empty but valid response is created and returned. This function
requires passing the user credentials.
The returned XML data stream is RSS 2.0 compliant and also contains additional information
in the extra namespace and optionally movie specific information.
HTTP Method:
GET
HTTP Response:
200 OK
Parameters:
t=movie Movie-Search function, must always be "movie".
apikey=xxx User's key as provided by the service provider.
Optional parameters:
limit=123 Upper limit for the number of items to be returned, e.g. 123.
imdbid=xxxx IMDB id of the item being queried e.g. 0058935.
cat=xxx List of categories to search delimited by ","
q=xxxx Search input (URL/UTF-8 encoded). Case insensitive.
o=xml Output format, either "JSON" or "XML". Default is "XML".
extended=1 Return extended information in the search results
del=1 Delete the item from a users cart on download.
maxage=123 Only return results which were posted to usenet in the last x days.
offset=50 The 0 based query offset defining which part of the response we want.
Examples:
--> GET http://servername.com/api?t=movie&apikey=xxx&imdbid=0058935
<-- 200 OK
example.comexample.com API resultsMovie.Name.720p.BluRay.DTS.x264http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c
http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9
http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c#commentsSun, 06 Jun 2010 17:29:23 +0100Movie > XviDSome movie
2.6 DETAILS
Description:
DETAILS function returns all information for a particular Usenet (NZB) item. The response
contains the generic RSS part + full extra information + full type/category specific information.
HTTP Method:
GET
HTTP Response:
200 OK
Parameters:
t=details Details function, must always be "details".
guid=xxxx The GUID of the item being queried.
apikey=xxxx User's key as provided by the service provider.
Optional parameters:
o=xxx Output format, either "JSON" or "XML". Default is "XML".
del=1 Delete the item from a users cart on download.
Example:
--> GET http://servername.com/api?t=details&apikey=xxxxx&guid=xxxxxxxxx
<-- 200 OK
A.Tv.Show.S06E05.DVDRIP.XviDhttp://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c
http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9
http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c#commentsSun, 06 Jun 2010 17:29:23 +0100TV > XviDSome TV show
// Query could not be completed because it was malformed
--> GET http://servername.com/api?t=details&apikey=xxxxx&guid=xxxxxxxxx
<-- 200 OK
// Query could not be completed because no such item was available
--> GET http://servername.com/api?t=details&apikey=xxxxx&guid=xxxxxxxxx
<-- 200 OK
// Query could not be completed because user credentials are broken
--> GET http://servername.com/api?t=details&apikey=xxxxx&guid=xxxxxxxxx
<-- 200 OK
2.7 INFO
Description:
INFO function returns the contents of the release info in text format. It can also return the contents as an nfo
file with extra parameters.
HTTP Method:
GET
HTTP Response:
200 OK
Parameters:
t=info Info function. Can be info, nfo, or n.
guid=xxxx The GUID of the item being queried.
apikey=xxxx User's key as provided by the service provider.
Optional parameters:
o=xxx Output format, can be "file" or "text". Default is "text".
Example:
--> GET http://servername.com/api?t=info&r=xxxxx&id=xxxxxxxxx
<-- 200 OK
<-- Contents of NFO blob with nl2br OR octet-stream of NFO blob
// Query could not be completed because it was malformed
--> GET http://servername.com/api?t=info&r=xxxxx&id=xxxxxxxxx
<-- 200 OK
// Query could not be completed because no such item was available
--> GET http://servername.com/api?t=info&r=xxxxx&id=xxxxxxxxx
<-- 200 OK
// Query could not be completed because user credentials are broken
--> GET http://servername.com/api?t=info&r=xxxxx&id=xxxxxxxxx
<-- 200 OK
3. Predefined Categories
In order to facilitate operation that does not rely on a particular natural language, e.g. english
a set of predefined category IDs have been defined. It is possible to define custom categories
in the custom category range. Each category is given a range for a set of subcategories. It is possible
for an item to belong to several categories at the same time.
Category Range Category Name Comments
0000-0999 Other
1000-1999 Console
2000-2999 Movies
3000-3999 Audio
4000-4999 PC
5000-5999 TV
6000-6999 XXX
7000-7999 Books
8000-99999 Reserved Reserved for future expansion
100000- Custom Site specific category range. Defined in CAPS
Categories Category Name
0000 Other All of Other
0010 Other/Misc Anything that could not get categorized
0020 Other/Hashed Anything with a hashed name
1000 Console All of console
1010 Console/NDS Nintendo DS
1020 Console/PSP Sony Playstation Portable
1030 Console/Wii Nintendo Wii
1040 Console/Xbox Microsoft XBox
1050 Console/Xbox 360 Microsoft XBox 360
1060 Console/Wiiware/VC Wii homebrew
1070 Console/XBOX 360 DLC Microsoft XBox 360 Downloadable Content
1080 Console/PS3 Playstation 3
1999 Console/Other Misc Console
1110 Console/3DS Nintendo 3DS
1120 Console/PS Vita Playstation Vita
1130 Console/WiiU Nintento Wii U
1140 Console/Xbox One Xbox One
1180 Console/PS4 Playstation 4
2000 Movies All of movies
2010 Movies/Foreign Non english movies
2020 Movies/Other Misc movies
2030 Movies/SD Standard definition movies
2040 Movies/HD High definition movies (720p+)
2050 Movies/3D 3D movies
2060 Movies/BluRay Full BR movies
2070 Movies/DVD Full DVD movies
2080 Movies/WEBDL WEB-DL movies
3000 Audio All of audio
3010 Audio/MP3 Mp3 music
3020 Audio/Video Music videos
3030 Audio/Audiobook Books in audio format
3040 Audio/Lossless Lossless music
3999 Audio/Other Misc music
3060 Audio/Foreign Non english music.
4000 PC All of PC
4010 PC/0day Apps and games not released in ISO.
4020 PC/ISO CD-ROM images/DVD Images
4030 PC/Mac OS X apps and games
4040 PC/Phone-Other Misc mobile phone software
4050 PC/Games PC Games
4060 PC/Phone-IOS IOS apps
4070 PC/Phone-Android Android apps
5000 TV All of TV
5010 TV/WEB-DL WEB-DL TV
5020 TV/FOREIGN FOREIGN TV
5030 TV/SD SD TV
5040 TV/HD HD TV
5999 TV/OTHER Other TV Content
5060 TV/Sport Sports
5070 TV/Anime Anime
5080 TV/Documentary Documentaries
6000 XXX All of XXX
6010 XXX/DVD Full DVD's
6020 XXX/WMV WMV rips
6030 XXX/XviD dvdrips
6040 XXX/x264 HD Porn
6999 XXX/Other Misc Porn
6060 XXX/Imageset Sets of porn images
6070 XXX/Packs Packs of multiple porn videos
7000 Books All of Books
7010 Books/Magazines Magazines
7020 Books/Ebook Ebooks
7030 Books/Comics Comics Ebooks
7040 Books/Technical Technical books
7060 Books/Foreign Non english books
7999 Books/Unknown Misc books
100000+ Custom Specific to a site
4. PREDEFINED ATTRIBUTES
A set of known attributes for items in different categories has been defined.
Its possible that not all attributes are available at all times. Therefore a
client application should not rely on any particular attributes being in the
returned data but should take this list as an optional extra information.
However attributes marked with * are always available.
Additionally, not all attributes are applicable to all items. The category
information can be used to check which attributes area available for which
category items.
All attributes are defined using XML namespace syntax.
e.g. xmlns:newznab="http://www.newznab.com/DTD/2010/feeds/attributes/"
4.1 List of Attributes
Attribute Category Description Example value
size * ALL Size in bytes "252322"
category * ALL Item's category "5004"
files ALL Number of files "4"
poster ALL NNTP Poster "yenc@power-post"
group ALL NNTP Group(s) "a.b.warez, a.b.teevee"
team ALL Team doing the release "DiAMOND"
grabs ALL Number of times item downloaded "1"
password ALL Whether the archive is passworded "0" no, "1" rar pass, "2" contains inner archive
comments ALL Number of comments "2"
usenetdate ALL Date posted to usenet "Tue, 22 Jun 2010 06:54:22 +0100"
info ALL Info (.nfo) file URL "http://somesite/api?t=info&id=xxx"
year ALL Release year "2009"
prematch ALL Has valid PreDB match "0" no "1" yes
season TV Numeric season "1"
episode TV Numeric episode within the season "1"
videos_id TV, Movies, Anime Local Video ID "1"
tv_episodes_id TV Local TV Episode ID "1"
tvdbid TV TVDB ID. (www.thetvdb.com) "153021"
traktid TV TraktTV ID. (www.trakt.tv) "1393"
rageid TV TVRage ID. (www.tvrage.com) "25056"
tvrageid TV TVRage ID. (www.tvrage.com) "25056"
tvmazeid TV TVMaze ID. (www.tvmaze.com) "73"
imdbid TV IMDB ID for show. (www.imdb.com) "tt1520211"
tmdbid TV TMDB ID for show. (www.themoviedb.com) "1402"
title TV TV Show Title. (www.tvrage.com) "Duck and Cover"
firstaired TV TV Show Air date. (www.tvrage.com) "Tue, 22 Jun 2010 06:54:22 +0100"
anidbid Anime AniDB.net ID. (www.anidb.net) "10445"
video TV, Movies Video codec "x264"
audio TV, Movies, Audio Audio codec "AC3 2.0 @ 384 kbs"
resolution TV, Movies Video resolution "1280x716 1.78:1"
framerate TV, Movies Video fps "23.976 fps"
language TV, Movies, Audio Natural languages "English"
subs TV, Movies Subtitles "English, Spanish"
imdb TV, Movies IMDb ID (www.imdb.com) "0104409"
genre TV, Movies Genre "Horror"
4.2 Attribute Example
Example attribute declarations within element.
5. nZEDb Error Codes
Under normal circumstances i.e. when the HTTP request/response sequence is successfully completed
nZEDb implementations always respond with HTTP 200 OK. However this does not mean that the
query was semantically correct. It simply means that the HTTP part of the sequence was successful.
One then must check the actual response body/data to see if the request was completed
without errors.
In case of a nZEDb error the response contains an error code and an a description of the error.
The error codes have been defined into different ranges. 100-199 Account/user credentials specific
error codes, 200-299 API call specific error codes, 300-399 content specific error codes and finally
900-999 Other error codes.
Error code Description
100 Incorrect user credentials
101 Account suspended
102 Insufficient privileges/not authorised
103 Registration denied
104 Registrations are closed
105 Invalid registration (Email Address Taken)
106 Invalid registration (Email Address Bad Format)
107 Registration Failed (Data error)
200 Missing parameter
201 Incorrect parameter
202 No such function. (Function not defined in this specification).
203 Function not available. (Optional function is not implemented).
300 No such item.
500 Request limit reached
501 Download limit reached
900 Unknown error
5.1 Error code example
// Query could not be completed because user credentials are broken
--> GET http://servername.com/api?t=details&apikey=xxxxx&guid=xxxxxxxxx
<-- 200 OK
6 Changelog
2015-10-24 ruhllatio
Add new attribute returns.
Update supported tv-search methods.
Add audio-search capability and make it unavailable with no params.
2015-05-23 kevinlekiller
Fix spelling issues.
Fix indentation issues.
Add missing categories.
Add missing error codes.