Newzbin API:FileFind
(Redirected from Newzbin:FileFind)
Contents |
[edit] What is it?
FileFind is an interface to our Usenet index (as indicated by the name, the Files bit of it, NOT the Reports).
It is intended to be used by programs wishing to implement a transparent real-time Usenet search to it's users.
[edit] A Brief History of FileFind
FileFind is now into it's third incarnation. (You can skip this bit if you don't care.)
FileFind1 was initially written for and used by NBUFFNZB ("NewsBin Usenet FileFind for NZB"). It is now defunct and no longer available for new supply.
FileFind2 was an internal test for Newsbin to develop their Usenet Search in Newsbin 5. It is not available to the public, but remains available for Newsbin's private use.
FileFind3 is the current incarnation and incorporates most of FileFind2 with some updates and fixes to make the interface more like DirectNZB. This is the one this document describes, and what is currently available for public use.
[edit] Technical Specifications
FileFind3 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/filefind3/
There are many variables you can send to FileFind3. They are split into mandatory and optional variables:
[edit] Mandatory Variables
You must send all of these for FileFind3 to work.
- username - the username of the account to login with.
- password - the password of the account to login with.
- query - the string to search Usenet for.
[edit] Optional Variables
None of these are required.
[edit] category
Which category to do the search in. Optionally comma-separate multiple values.
Default: All categories, no restriction.
[edit] group
Which newsgroup to do the search in. Optionally comma-separate multiple values.
Default: All newsgroups, no restriction.
[edit] retention
How many days of Usenet to search back from the current time. Sensible values are currently 1 - 200. (Newzbin up to 200 days retention at the time of writing).
Default: 7 days.
[edit] bytesmin & bytesmax
The smallest/largest files to return, in Bytes.
Default: No size limitation.
[edit] authorid
For internal use only - you probably won't have any use for this. It restricts results to a given poster on Usenet, but the 'id' required is an internal Newzbin number. You can't search for a given poster string at the moment.
[edit] filetype
The Newzbin index determines (quite naively) which filetype some files are. It does this by very simply searching the subject for a predefined string. For example, if it finds .nzb" then it's set as an NZB. In practise it's fairly accurate, but don't rely on it as any malicious Usenet poster could easily circumvent it.
Valid file types are SFV, NFO, and NZB.
(let us know if you'd like more adding, but bear in mind it'll take time to populate our database with the new filetype information.)
Default: All file types.
[edit] offset & limit
Where to start returning results, and how many of them. For example, an offset of 1000 will skip the first 1000 results.
This is only useful if you are sorting the result-set specifically, and are allowing the user to "page through" the results.
There is a hardcoded maximum limit of 5000. Attempting to request more results than this will simply return up to a maximum of 5000.
Default: Offset 0 (ie, the beginning), limit of 500.
[edit] sortfield & sortorder
Which field to order the results by, and in which direction.
Possible values for sortfield are DATE, SUBJECT, and BYTES.
Possible values for sortorder are ASC and DESC.
Default: Sort by Date, Ascending.
[edit] List of Return Codes
Note that this differs from DirectNZB.
DirectNZB uses an arbitrary header to return the code; FileFind uses only the HTTP response code. It will be set to one of the following (the text in parentheses is the reason why it was set, and will not actually be in the response).
- 200 = OK
- 204 = No Content (there were no results to return)
- 402 = Payment Required (the account is not a premium account)
- 403 = Forbidden (incorrect authentication details)
- 500 = Internal Server Error (Newzbin broke)
[edit] Successful Response
The only successful response is a HTTP response of 200. A 204 indicates the request is valid, but nothing matched it.
Upon receiving code 200, you should read the body for file results. It's formatted much like an XOVER from a news server, but not quite the same format.
The first line of the result is of the format TOTAL=nnnn where nnnn is the number of results that would have been returned if you were not limited to 500 at a time. Using this, you can fetch more results later if desired by modifying your offset flag.
The fields are tab separated, and they are:
- FileID - an internal Newzbin identifier for the given file. A bit like an Article Number.
- Subject - subject of the file.
- Date - unix timestamp representation of when the file was posted to Usenet (see Technical Limitations)
- Bytes - size of file, in bytes (see Technical Limitations)
- Author - who posted the file to Usenet.
- Groups - comma-separated list of newsgroups the file is in.
[edit] Failed Responses
Error 402 indicates that the user/pass you supplied are not a Newzbin premium account. The account you are using must be Premium, since our Usenet index is only searchable by premium members (the same policy applies on the website). If you are having the user use their own account for searching, tell them they need to be a premium member of Newzbin. If you are using your own bulk reseller account, then we really should have topped up your account for you, shout at us.
Error 403 indicates the user/pass you supplied are not valid, or do not exist at all. Do not retry the same user/pass without having them fixed.
Error 500 is our fault, and means something internally has broken. If this persists, the Newzbin Administration should be notified. You should display in your application that search is unavailable.
For all failed responses, the body of the response currently contains a human-readable error message. This may or may not remain there. Don't rely on it.
[edit] Technical Limitations
This section describes shortcomings in the current incarnation of the interface; ie things we'd like to fix in the future if possible.
- In the list of file responses, the Date and Bytes fields are not completely accurate.
- The Date field is parsed from an XOVER from the first news-server we see the file on. We cannot guarantee it's accuracy.
- The Bytes field is also parsed from an XOVER from the first news-server we see the file on. This field varies from server-to-server as the Path: header changes. It should be accurate to a few kb, but not spot-on.
[edit] Updates to Service/this Document
[newest entries at the top]
- 20071005 Bugs fixed which prevented sortfield and sortorder being parsed correctly.
- 20070924 Default limit changed from 50 to 500. Noted the hardcoded 5000 max.
- 20070924 FileFind3 is now live. Minor corrections to querystring items.
- 20070514 Documentation started.