NZB Search Interface

From Newsbin

Contents 1 Usenet Indexing Service Query Interface 1.1 Status 1.2 Introduction 1.3 Overview 1.4 POST Variables 1.5 Status strings 1.6 Notes 1.7 Examples

Usenet Indexing Service Query Interface

A Proposed Standard for Programmatic Queries of a Usenet Indexing Service

Status

Date	Description
January 31, 2006	Initial Draft
February 2, 2006	First Review - Add error responses and HTTP sample responses
February 6, 2006	Second Review - Modifications to make more generic

Introduction

The Usenet Community has embraced the NZB Message ID File Format as the defacto standard for storing Usenet Post Information that can be used to retrieve posts from any News Server that has the post. Most Usenet Indexing Services now deliver search results in this format and many newsreaders use the format to download posts without needing to first download headers from the server. This interface is intended for use by newsreader or other Usenet utility developers to provide a search interface from within their program that will perform a query of a Usenet Indexing Service and retrieve the results for further processing.

Overview

The proposed interface intiates a query via an HTTP POST to a URL specified by the Usenet Indexing Service. A number of variables are sent in the POST, including authentication information if required. The response is a standard HTTP response with the search results returned in a gzipped NZB file or defined error codes if there is a failure. A streaming response is preferred so search progress can be shown but a standard file transfer is acceptable.

1. Accept an HTTP POST at http://www.indexingsite.com/nzbsearch/newsbin.php (or URL of your choice)
2. Accept parameters defined below
3. Return status header string (X-NZB-Status) as defined below
4. Return a gzipped NZB file in the response body

POST Variables

Name	Type	Size	Default	Description
username	String	1-30 Chars	None	Username for accessing Indexing Service.
password	String	1-30 Chars	None	Password for accessing Indexing Service
query	String	2-256 Chars	None	Search string
days	Integer	1-99	20	Number of days of results to return.
limit	Integer	10-1000	500	Max number of matches to return.
group	String	1-256 Chars	None	Specific newsgroup to search
category	String	1-30 Chars	None	Specific Category to search

Status strings

1. BAD_PARAMETERS : The required parameters were not in the POST or they have bad data.
2. AUTH_FAILED : The username or the password was wrong or the account doesn't exist.
3. BAD_QUERY : The query had no results or there was a server problem in executing the search.
4. ACCOUNT_LOCKED : The user account is not paid or has been disabled for some reason.
5. OK : Successful search, the content is a GZipped NZB file.

Notes

1. Required fields are username, password, and query. If they don't exist or are blank, an error should be returned.
2. Other fields that are not required should use the default values listed.
3. All variables should be url encoded.
4. Status string should be in X-NZBSearch-Status.

Examples

POST /nzbsearch/newsbin.php HTTP/1.0
Host: www.indexintsite.com
Content-Type: application/x-www-form-urlencoded

username=Test&password=test&query=angelina&days=7&limit=150&group=alt.binaries.pictures.celebrities

Response:

HTTP/1.1 200 OK
Date: Thu, 02 Feb 2006 18:57:56 GMT
Server: Apache
X-NZBSearch-Status: OK
Vary: Accept-Encoding
Connection: close
Content-Type: text/html; charset=ISO-8859-1
Content-Length: 47429
Content-Transfer-Encoding: gzip
Content-Type: application/octet-stream

<gzipped NZB file>

Error Response:

HTTP/1.1 200 OK
Date: Thu, 02 Feb 2006 18:57:56 GMT
Server: Apache
X-NZBSearch-Status: AUTH_FAILED
Vary: Accept-Encoding, User-Agent
Connection: close
Content-Type: text/html; charset=ISO-8859-1