XML-RPC and JSON-RPC in NZBGet

Contents

About XML-RPC and JSON-RPC in NZBGet
Description of methods
    pause
    resume
    shutdown
    version
    rate
    status
    log
    listfiles
    listgroups
    postqueue
    editqueue
    append
Examples

About XML-RPC and JSON-RPC in NZBGet

From the version 0.4.0 NZBGet has supported XML-RPC and JSON-RPC. It allows to control the server from other applications. Many programming languages have libraries, which make the usage of XML-RPC and JSON-RPC very simple. The implementations of both protocols in NZBGet are equal: all methods are identical. You may choose the protocol, which is better supported by your programming language.

The RPC server uses HTTP authentication with username "nzbget" and the password from server's configuration file. The URL would be something like:
for XML-RPC: http://nzbget:yourpassword@localhost:6789/xmlrpc
for JSON-RPC: http://nzbget:yourpassword@localhost:6789/jsonrpc

Security warning: HTTP authentication is not secure. Although the password is encoded using Base64 it is no encrypted.

This document describes the methods available in NZBGet-server.

Features and limitations

• Multicalls are supported for XML-RPC and not supported for JSON-RPC.
• Introspection is not supported.
• Only positional parameters are supported in JSON-RPC. Named parameters are not supported.

Method "pause"

Signature:
bool pause()

Pause server.
This method is equivalent for command "nzbget -P".

Return value:
Always "True".

Method "resume"

Signature:
bool resume()

Resume (previously paused) server.
This method is equivalent for command "nzbget -U".

Return value:
Always "True".

Method "shutdown"

Signature:
bool shutdown()

Shutdown server.
This method is equivalent for command "nzbget -Q".

Return value:
Always "True".

Method "version"

Signature:
string version()

Request the version-string of server.
This method is equivalent for command "nzbget -V".

Return value:
Version string.

Method "rate"

Signature:
bool rate(int Limit)

Set download speed limit.
This method is equivalent for command "nzbget -R <Limit>".

Parameters:
Limit - new download speed limit in KBytes/second. Value "0" disables speed throttling.

Return value:
"True" on success or "False" on failure.

Method "status"

Signature:
struct status()

Request for current status (summary) information.
Parts of informations returned by this method can be printed by command "nzbget -L".

Return value:
This method returns a structure with following fields:

Method "log"

Signature:
array log(int IDFrom, int NumberOfEntries)

Request for screen-log.
This method is similar to command "nzbget -G <NumberOfEntries>" but returns more information and can return lines from the specified log-ID.
This method returns entries from server's screenlog-buffer. The size of this buffer is limited and can be set via option "LogBufferSize" in server's configuration file. Which messages should be saved to screenlog and which should be saved to log-file can be set via server's options InfoTarget, WarningTarget, ErrorTarget and DebugTarget in server's configuration file.

Parameters:
IDFrom - The first ID to be returned.
NumberOfEntries - Number of entries, which should be returned.

NOTE: only one parameter - either IDFrom or NumberOfEntries - can be specified. The other parameter must be "0".

TIP: If your application stores log-entries between subsequential calls to method log(), the usage of parameter IDFrom is recommended, since it reduces the amount of transferred data.

Return value:
This method returns an array of structures with following fields:

NOTE: if there are no entries for requested criteria, an empty array is returned.

Method "listfiles"

Signature:
struct[] listfiles(int IDFrom, int IDTo)

Request for file's list.
This method is similar to command "nzbget -L", but returns much more data for every file and does not return summary information (which can be requested via method "status").

Parameters:
IDFrom - The first ID of file range to be returned. To return all files set this parameter to 0;
IDTo - The first ID of file range to be returned.

Return value:
This method returns an array of structures with following fields:

NOTE: it is very unlikely to see a file larger than 2 GB in newsgroups. Large files are always posten in parts (mostly as rar-archives with part-size not greather than 100 MB). Therefore it is almoust safe to ignore fields FileSizeHi and RemainingSizeHi if your programming language does not support 64-bit integers.

Method "listgroups"

Signature:
struct[] listgroups()

Request for groups' list.
This method returns summary information for each file group. A group is a collection of files from one nzb-file.

Return value:
This method returns an array of structures with following fields:

Method "postqueue"

Signature:
struct[] postqueue(int NumberOfLogEntries)

Request for list of items in post-processor-queue.

Parameters:
NumberOfLogEntries - Number of log-entries, saved from post-process-script, which should be returned for the top (currently processing item in post-processor-queue).

Return value:
This method returns an array of structures with following fields:

NOTE: postprocessor executes only one job at a time - the first (top) job in post-queue. Fields ProgressLabel, FileProgress, StageProgress, TotalTimeSec, StageTimeSec and Log have meaning only for that job.

Method "editqueue"

Signature:
bool editqueue(string Command, int Offset, int[] IDs)

Pause/unpause/move/delete files or groups.
This method is equivalent for command "nzbget -E <args>".

Parameters:
Command - one of the following commands:

Command	Description
FileMoveOffset	Move files to Offset relative to the current position in queue.
FileMoveTop	Move files to top of queue.
FileMoveBottom	Move files to bottom of queue.
FilePause	Pause files.
FileResume	Resume (unpause) files.
FileDelete	Delete files.
FilePauseAllPars	Pause only pars (does not affect other files).
FilePauseExtraPars	Pause only pars, except main par-file (does not affect other files).
GroupMoveOffset	Move groups to Offset relative to the current position in queue.
GroupMoveTop	Move groups to top of queue.
GroupMoveBottom	Move groups to bottom of queue.
GroupPause	Pause groups.
GroupResume	Resume (unpause) groups.
GroupDelete	Delete groups.
GroupPauseAllPars	Pause only pars (does not affect other files).
GroupPauseExtraPars	Pause only pars, except main par-file (does not affect other files).

Offset - offset for commands FileMoveOffset and GroupMoveOffset. For all other commands must be "0".

IDs - array of file-ids (as integers). File-commands need ID of file. For group-command ID of any file in this group can be used, for example filed FirstID or LastID of group-structure (the using of LatsID is preferred, because the file with first ID has more chances to be completed and deleted from queue before edit-command is received by the server).

Return value:
"True" on success or "False" on failure.

Method "append"

Signature:
bool append(string NZBFilename, bool AddToTop, string Content)

Add nzb-file to download queue.
This method is equivalent for command "nzbget -A [T] <filename>".

Parameters:
NZBFilename - name of nzb-file. Server uses the name to build destination directory. This name can contain fullpath or only filename.

AddToTop - "True" if the file should be added to the top of the download queue or "False" if to the end.

Content - Content of nzb-file encoded with Base64.

Return value:
"True" on success or "False" on failure.

Examples

The most comprehensive example on using XML-RPC and JSON-RPC with NZBGet would be NZBGetWeb - web-interface for NZBGet, written in PHP. Look in download section for source code.

Two following examples show how to interact with NZBGet from Python using XML-RPC.

Adding file to download queue

C:\>C:\Programme\Python25\python.exe
Python 2.5.1 (r251:54863, Apr 18 2007, 08:51:08) [MSC v.1310 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> from xmlrpclib import ServerProxy
>>> server = ServerProxy('http://nzbget:tegbzn6789@localhost:6789/xmlrpc')
>>> filename="C:\\ubuntu-7.10.nzb"
>>> in_file = open(filename, "r")
>>> nzbcontent = in_file.read()
>>> in_file.close()
>>> from base64 import standard_b64encode
>>> nzbcontent64=standard_b64encode(nzbcontent)
>>> server.append(filename, False, nzbcontent64)
True
>>>

Obtaining log from server

C:\>C:\Programme\Python25\python.exe
Python 2.5.1 (r251:54863, Apr 18 2007, 08:51:08) [MSC v.1310 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> from xmlrpclib import ServerProxy
>>> server = ServerProxy('http://nzbget:tegbzn6789@localhost:6789/xmlrpc')
>>> server.log(1, 0)
[{'Text': 'nzbget server-mode', 'Kind': 'INFO', 'ID': 1, 'Time': 1202409509}, 
{'Text': 'Downloading ubuntu-7.10\ubuntu-7.10-desktop-i386.part04.rar [1/131]', 
'Kind': 'INFO', 'ID': 2, 'Time': 1202409509}, 
{'Text': 'Downloading ubuntu-7.10\ubuntu-7.10-desktop-i386.part04.rar [2/131]', 
'Kind': 'INFO', 'ID': 3, 'Time': 1202409509}, 
{'Text': 'Downloading ubuntu-7.10\ubuntu-7.10-desktop-i386.part04.rar [3/131]', 
'Kind': 'INFO', 'ID': 4, 'Time': 1202409509}, 
{'Text': 'Downloading ubuntu-7.10\ubuntu-7.10-desktop-i386.part04.rar [4/131]', 
'Kind': 'INFO', 'ID': 5, 'Time': 1202409509}, 
{'Text': 'Pausing download', 'Kind': 'INFO', 'ID': 6, 'Time': 1202409513}]
>>>

Last updated: 8 Apr. 2008 Copyright © 2007-2008 - Andrei Prygounkov - all rights reserved