You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
819 lines
41 KiB
819 lines
41 KiB
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
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<caps>
|
|
<!-- server information -->
|
|
<server version="1.0" title="nZEDb" strapline="A great usenet indexer"
|
|
email="info@nZEDb.com" url="http://servername.com/" image="http://servername.com/theme/black/images/banner.jpg"/>
|
|
|
|
<!-- limit parameter range -->
|
|
<limits max="100" default="50"/>
|
|
|
|
<!-- the server NZB retention -->
|
|
<retention days="400"/>
|
|
|
|
<!-- registration available or not -->
|
|
<registration available="yes" open="yes" />
|
|
|
|
<!--
|
|
The search functions available at the server
|
|
The only currently defined search functions are SEARCH and TV-SEARCH.
|
|
Any conforming implementation should at least support the basic search.
|
|
Other search functions are optional.
|
|
-->
|
|
<searching>
|
|
<search available="yes" supportedParams="q,group"/>
|
|
<tv-search available="yes" supportedParams="q,rid,tvdbid,vid,traktid,tvmazeid,imdbid,tmdbid,season,ep"/>
|
|
<movie-search available="yes" supportedParams="q,imdbid"/>
|
|
<audio-search available="no" supportedParams=""/>
|
|
</searching>
|
|
|
|
<!-- supported categories -->
|
|
<categories>
|
|
<category id="1000" name="Console">
|
|
<subcat id="1010" name="NDS"/>
|
|
<subcat id="1020" name="PSP"/>
|
|
</category>
|
|
<category id="2000" name="Movies">
|
|
<subcat id="2010" name="Foreign"/>
|
|
</category>
|
|
|
|
<!-- site specific categories -->
|
|
<category id="1000001" name="MotoGP" description="Latest MotoGP stuff"/>
|
|
<category id="1000002" name="Fifa 2010" description="Fifa 2010 world cup">
|
|
<subcat id="1000003" name="Fifa 2010 HD" description="HD stuff"/>
|
|
<subcat id="1000004" name="Fifa 2010 SD" description="SD stuff"/>
|
|
</category>
|
|
<!-- etc.. -->
|
|
</categories>
|
|
</caps>
|
|
</xml>
|
|
|
|
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
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<register username="user123" password="pass123" apikey="abcabcd11234abc"/>
|
|
</register>
|
|
|
|
--> GET HTTP://servername.com/api?t=register&email=john.joe%40acme.com
|
|
<-- 200 OK
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<error code="103" description="Registration denied"/>
|
|
|
|
--> GET HTTP://servername.com/api?t=register&email=john.joe%40acme.com
|
|
<-- 200 OK
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<error code="104" description="No more registrations allowed"/>
|
|
|
|
--> GET HTTP://servername.com/api?t=register&email=john.joe%40acme.com
|
|
<-- 200 OK
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<error code="203" description="Function not available"/>
|
|
|
|
|
|
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
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<rss version="2.0">
|
|
|
|
<channel>
|
|
<title>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.XviD</title>
|
|
<guid isPermaLink="true">http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c</guid>
|
|
<link>http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9</link>
|
|
<comments>http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c#comments</comments>
|
|
<pubDate>Sun, 06 Jun 2010 17:29:23 +0100</pubDate>
|
|
<category>TV > XviD</category>
|
|
<description>Some TV show</description>
|
|
<enclosure url="http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9" length="154653309" type="application/x-nzb" />
|
|
|
|
<!-- Additional attributes -->
|
|
<newznab:attr name="category" value="2000"/>
|
|
<newznab:attr name="category" value="2030"/>
|
|
<newznab:attr name="size" value="4294967295"/>
|
|
</item>
|
|
</channel>
|
|
</rss>
|
|
|
|
|
|
// no items matched the search criteria
|
|
--> GET http://servername.com/api?t=search&apikey=xxxxx&q=linux%20image
|
|
<-- 200 OK
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<rss>
|
|
<channel>
|
|
<newznab:response offset="0" total="0"/>
|
|
</channel>
|
|
</rss>
|
|
|
|
// Query could not be completed because user credentials are broken
|
|
--> GET http://servername.com/api?t=search&apikey=xxxxx&q=linux%20image
|
|
<-- 200 OK
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<error code="100" description="Incorrect user credentials"/>
|
|
|
|
|
|
// Query could not be completed because it was malformed
|
|
--> GET http://servername.com/api?t=search&apikey=xxxxx&q=linux%20image
|
|
<-- 200 OK
|
|
<?xml version="1.0" encoding="UTF-8"/>
|
|
<error code="200" description="Missing parameter: key"/>
|
|
|
|
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
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<rss version="2.0">
|
|
<channel>
|
|
<title>example.com</title>
|
|
<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="1234"/>
|
|
|
|
<item>
|
|
<!-- Standard RSS 2.0 data -->
|
|
<title>Land.of.the.Lost.S03E02.Survival.Kit.iNTERNAL.DVDRip.XViD-SPRiNTER</title>
|
|
<guid isPermaLink="true">http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c</guid>
|
|
<link>http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9</link>
|
|
<comments>http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c#comments</comments>
|
|
<pubDate>Sun, 06 Jun 2010 17:29:23 +0100</pubDate>
|
|
<category>TV > XviD</category>
|
|
<description>Some TV show</description>
|
|
<enclosure url="http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9" length="154653309" type="application/x-nzb" />
|
|
|
|
<!-- Additional attributes -->
|
|
<newznab:attr name="category" value="5030"/>
|
|
<newznab:attr name="size" value="154653309"/>
|
|
<newznab:attr name="season" value="3"/>
|
|
<newznab:attr name="episode" value="2"/>
|
|
</item>
|
|
|
|
<item>
|
|
<!-- Standard RSS 2.0 data -->
|
|
<title>Lost.S03E01.720p.BluRay.DTS.x264.INTERNAL-hV</title>
|
|
<guid isPermaLink="true">http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c</guid>
|
|
<link>http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9</link>
|
|
<comments>http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c#comments</comments>
|
|
<pubDate>Sun, 06 Jun 2010 17:29:23 +0100</pubDate>
|
|
<category>TV > XviD</category>
|
|
<description>Some TV show</description>
|
|
<enclosure url="http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9" length="154653309" type="application/x-nzb" />
|
|
|
|
<!-- Additional attributes -->
|
|
<newznab:attr name="category" value="5000" />
|
|
<newznab:attr name="category" value="5030" />
|
|
<newznab:attr name="size" value="4294967295" />
|
|
<newznab:attr name="season" value="3"/>
|
|
<newznab:attr name="episode" value="1"/>
|
|
</item>
|
|
|
|
<!-- more items to follow -->
|
|
|
|
</channel>
|
|
</rss>
|
|
|
|
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
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<rss version="2.0">
|
|
<channel>
|
|
<title>example.com</title>
|
|
<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="1234"/>
|
|
|
|
<item>
|
|
<!-- Standard RSS 2.0 data -->
|
|
<title>Movie.Name.720p.BluRay.DTS.x264</title>
|
|
<guid isPermaLink="true">http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c</guid>
|
|
<link>http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9</link>
|
|
<comments>http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c#comments</comments>
|
|
<pubDate>Sun, 06 Jun 2010 17:29:23 +0100</pubDate>
|
|
<category>Movie > XviD</category>
|
|
<description>Some movie</description>
|
|
<enclosure url="http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9" length="154653309" type="application/x-nzb" />
|
|
|
|
<!-- Additional attributes -->
|
|
<newznab:attr name="category" value="2000" />
|
|
<newznab:attr name="category" value="2030" />
|
|
<newznab:attr name="size" value="4294967295" />
|
|
</item>
|
|
|
|
</channel>
|
|
</rss>
|
|
|
|
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
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<rss version="2.0">
|
|
<channel>
|
|
<item>
|
|
<!-- Standard RSS 2.0 Data -->
|
|
<title>A.Tv.Show.S06E05.DVDRIP.XviD</title>
|
|
<guid isPermaLink="true">http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c</guid>
|
|
<link>http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9</link>
|
|
<comments>http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c#comments</comments>
|
|
<pubDate>Sun, 06 Jun 2010 17:29:23 +0100</pubDate>
|
|
<category>TV > XviD</category>
|
|
<description>Some TV show</description>
|
|
<enclosure url="http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9" length="154653309" type="application/x-nzb" />
|
|
|
|
<!--
|
|
Additional attributes
|
|
Details function returns all possible attributes that are 1) known and 2) applicable
|
|
for the item requested.
|
|
-->
|
|
<newznab:attr name="category" value="2000" />
|
|
<newznab:attr name="category" value="2030" />
|
|
<newznab:attr name="size" value="4294967295" />
|
|
<newznab:attr name="files" value="107" />
|
|
<newznab:attr name="poster" value="example@4u.net (example)" />
|
|
<newznab:attr name="grabs" value="1" />
|
|
<newznab:attr name="comments" value="0" />
|
|
<newznab:attr name="usenetdate" value="Tue, 22 Jun 2010 06:54:22 +0100" />
|
|
<newznab:attr name="group" value="alt.binaries.movies.divx" />
|
|
|
|
</item>
|
|
</channel>
|
|
</rss>
|
|
|
|
// Query could not be completed because it was malformed
|
|
--> GET http://servername.com/api?t=details&apikey=xxxxx&guid=xxxxxxxxx
|
|
<-- 200 OK
|
|
<?xml version="1.0" encoding="UTF-8"/>
|
|
<error code="200" description="Missing parameter: key"/>
|
|
|
|
// Query could not be completed because no such item was available
|
|
--> GET http://servername.com/api?t=details&apikey=xxxxx&guid=xxxxxxxxx
|
|
<-- 200 OK
|
|
<?xml version="1.0" encoding="UTF-8"/>
|
|
<error code="300" description="No such GUID"/>
|
|
|
|
// Query could not be completed because user credentials are broken
|
|
--> GET http://servername.com/api?t=details&apikey=xxxxx&guid=xxxxxxxxx
|
|
<-- 200 OK
|
|
<?xml version="1.0" encoding="UTF-8"/>
|
|
<error code="100" description="Incorrect user credentials"/>
|
|
|
|
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
|
|
<?xml version="1.0" encoding="UTF-8"/>
|
|
<error code="200" description="Missing parameter: key"/>
|
|
|
|
// Query could not be completed because no such item was available
|
|
--> GET http://servername.com/api?t=info&r=xxxxx&id=xxxxxxxxx
|
|
<-- 200 OK
|
|
<?xml version="1.0" encoding="UTF-8"/>
|
|
<error code="300" description="No such GUID"/>
|
|
|
|
// Query could not be completed because user credentials are broken
|
|
--> GET http://servername.com/api?t=info&r=xxxxx&id=xxxxxxxxx
|
|
<-- 200 OK
|
|
<?xml version="1.0" encoding="UTF-8"/>
|
|
<error code="100" description="Incorrect user credentials"/>
|
|
|
|
|
|
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 <item> element.
|
|
|
|
<newznab:attr name="category" value="2000" />
|
|
<newznab:attr name="category" value="2030" />
|
|
<newznab:attr name="size" value="4294967295" />
|
|
|
|
|
|
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
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<error code="100" description="Incorrect user credentials"/>
|
|
|
|
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.
|
|
|