Newzbin API:DirectNZB
(Redirected from Newzbin:DirectNZB)
Contents |
[edit] What is it?
DirectNZB is an interface to NZB files that is intended to be used by automated NZB fetchers.
There are no pretty pages of HTML to wade through, simply a return code (and if successful, an NZB).
Currently, you can only fetch an NZB for one entire report per request. It is not possible to fetch an NZB for a file, or part of a report. A valid Newzbin premium account is required.
This document is intended for application authors/coders who wish to use the interface in their applications.
[edit] Technical Specifications
DirectNZB is implemented on Newzbin v3 (http://v3.newzbin.com) only - it is not available on the old "v2" site, at http://www.newzbin.com.
You access it by sending a standard application/x-www-form-urlencoded POST request to http://v3.newzbin.com/api/dnzb/
You must supply three POST variables. Two of them are always required, username and password, and the third must either be reportid or fileid, depending on what you want to get.
If you are familiar with Newzbin (if you're not, what are you doing here?) you will know that we have two significant sections; reports, and files. Reports are collections of files which our Editors have manually created. Files is a direct dump of all file data we've seen on Usenet.
Thus, the valid POST string combinations are:
- username=foo&password=bar&reportid=123
- username=foo&password=bar&fileid=123,124,125
Note that you can [optionally] supply more than one fileid, comma separated. This only applies to files, you can only get one report in one request.
The reply you get will contain two arbitrary headers; X-DNZB-RCode and X-DNZB-RText. Note that the HTTP Response code is generally set to 400 on error (with a couple of exceptions, see below). For a more detailed error, you should investigate the X-DNZB-RCode header.
It's strongly recommended that clients using this interface support HTTP content compression as described in RFC 2616 (see sections on Accept-Encoding and Content-Encoding headers); this will significantly reduce the wire traffic from a retrieved NZB.
[edit] X-DNZB-RCode
This is a numeric return code, which closely emulates what you'd expect to see in a HTTP Return Code, with a couple of additions. Note that this is *just* the numeric part, so is easily machine parseable.
[edit] X-DNZB-RText
This is a string return code which matches the RCode. You can display this to the user to tell them what's going on if the RCode indicates an error - or ignore it and make your own.
[edit] List of Return Codes
- 200 = OK, NZB content follows
- 400 = Bad Request, please supply all parameters
- (this generally means reportid or fileid is missing; missing user/pass gets you a 401)
- 401 = Unauthorised, check username/password?
- 402 = Payment Required, not Premium
- 404 = Not Found, data doesn't exist?
- (only working for reportids, see Technical Limitations)
- 450 = Try Later, wait <x> seconds for counter to reset
- (for an explanation of this, see DNZB Rate Limiting)
- 500 = Internal Server Error, please report to Administrator
- 503 = Service Unavailable, site is currently down
Full example:
- X-DNZB-RCode: 450
- X-DNZB-RText: Try Later, wait 22 seconds for counter to reset
[edit] Successful Response
A successful response will have a X-DNZB-RCode of 200 (to match HTTP OK) and the NZB will be sent in the body.
There will be no HTML or other content. You can use the entire body response as the NZB.
[edit] X-DNZB-Name
For a successful Report NZB request, the X-DNZB-Name header is also returned. This contains a mildly sanitised version of the report's title (by sanitised, we mean characters not in the valid range for HTTP headers have been removed; this basically means any ASCII character outside the 32-127 range). These characters are replaced with rough equivilents within the basic ASCII range where possible (e.g. é -> e), otherwise they're replaced with _.
You can use this to determine what to name the folder to store the decoded files in, or whatever. For example, you might see:
- X-DNZB-Name: Double Zero (2004)
In this case, an 'é' was replaced since it is not a valid HTTP header character.
[edit] X-DNZB-Category
Additionally for a successful Report NZB request, the X-DNZB-Category header is returned. This contains a single word which is the category of the Report you have requested; ie, Apps, Movies, TV.
for example:
- X-DNZB-Category: Movies
Neither X-DNZB-Name nor X-DNZB-Category are returned for File NZB requests.
[edit] Failed Responses
A failed response will have a X-DNZB-RCode as per the list above (it won't be 200), and for the time being, no body response. We may use the body response in future but at the moment we have no need for it. The HTTP Response code is generally set to 400, to indicate 'Bad Request', unless specifically noted otherwise here (for 500 and 503).
Error 400 indicates you have not supplied all required parameters. All three of username/password/reportid are required, and reportid must be numeric. Since a missing username/password will return an error 401, getting 400 usually means reportid is missing or not numeric.
Error 401 indicates either the user has entered incorrect/no account details, or their account has been suspended/etc. Do not retry requests without prompting the user to fix the problem.
Error 402 indicates the username/password combination is correct, but the account does not have any Premium Credit. A Topup is required to get any NZBs. Indicate to the user that the request will not work until they add some credit.
Error 404 indicates the data trying to be fetched does not exist or is not accessible to the user. Do not retry the request, it will not magically become available.
Error 450 indicates you should wait before retrying; see DNZB Rate Limiting.
Error 500 indicates that something bad happened while generating the NZB, and we are unable to return it to you. This is generally our fault, and means something is broken. You can notify the application user that Newzbin Administration should be informed if these are persistent. In this error code, the HTTP Response is also set to 500, to indicate our end is broken.
Error 503 indicates that Newzbin is down/undergoing maintenance. You can schedule a retry, but please be sensible with your retry interval; we suggest no more frequent than 5 minutes. In this error code, the HTTP Response is also set to 503, to indicate 'Service Unavailable' to all traditional HTTP clients.
[edit] Technical Limitations
This section describes shortcomings in the current incarnation of the interface; ie things we'd like to fix in the future but we're not sure how to do it yet.
- You can only ask for one reportid per request. This is unlikely to change for now.
- You can only ask for a reportid, or [some] fileids at once. We're not sure if we really want to change this, it will just complicate the interface. If anyone has an overwhelming desire to be able to request a reportid and some fileids in the same request, contact us.
[edit] DNZB Rate Limiting
NZBs fetched by this DirectNZB interface are limited to 5 NZBs per 60 seconds per IP. We use a rolling counter, so in order to get a code 200 (and thus an NZB) you must have fetched less than 5 NZBs in the previous 60 seconds. If you exceed this, you will get an RCode 450, and the RText will tell you how many seconds you have to wait before you can get an NZB again. This is currently the only restriction; there are no captchas, and no 350 NZB/week limit.
If your application gets an error 450, you should at the very least wait 60 seconds before trying again. You can reduce the delay by parsing the RText and extracting the number of seconds you have to wait. <x> is replaced by an integer from 1-60 indicating number of seconds to wait. The 's' at the end of 'seconds' is not removed when <x> is 1 (looks a bit odd but will make your matching regexp simpler if you're using one).
for example:
- X-DNZB-RText: Try Later, wait 22 seconds for counter to reset
IPs running an application which hammer the service trying to get NZBs will be banned from using the service. Coders, please have some respect for our servers and honour the time limits.
[edit] Updates to Service/this Document
[newest entries at the top]
- 20070527 DirectNZB URL has moved to http://v3.newzbin.com/api/dnzb/ - the old URL will remain active for compatibility.
- 20070112 404 is now returned correctly in all cases (it sometimes wasn't).
- 20070110 Added capability to request files from the interface, and updated bits of documentation to explain how.
- 20070105 Added X-DNZB-Category header, and explanation of.