= Introduction to OSDb =

[[PageOutline(2, Sections)]]

This page is aimed at developers who'd like to implement the OSDb protocol and functionality into their own applications.
Here'll you'll find the API specifications for all available functions along with structure definitions and useful hints.

Our API is based on [http://www.xmlrpc.com/ XML-RPC] so you might want to take a look at its
[http://www.xmlrpc.com/spec specifications] and [http://www.xmlrpc.com/directory/1568/implementations implementations].

Our API supports many methods so there should be no problem to code some nice client applications.

If you're missing any method feel free to contact us on the [http://forum.opensubtitles.org/viewforum.php?f=8 forum] to discuss possibilities.

[http://en.wikipedia.org/wiki/XML-RPC Short Wikipedia excerpt about XML-RPC]:
XML-RPC is a very simple protocol, defining only a handful of data types and commands
and the entire description can be printed on two pages of paper.
This is in stark contrast to most RPC systems, where the standards documents
often run into the hundreds of pages and require considerable software support in order to be used.


= Instructions =
 * [wiki:DevReadFirst Read this first]
 * All development testing should be pointed to: http://dev.opensubtitles.org/xml-rpc (currently offline, so use main server)
 * Main/Production server XML-RPC URL: http://www.opensubtitles.org/xml-rpc
 * Before developing let us know and we will assign/agree on useragent code for your application.
 * For languages codes, check [http://en.wikipedia.org/wiki/List_of_ISO_639-2_codes ISO639], use '''pb/pob''' for Portuguese (Brazil) - [http://www.opensubtitles.org/addons/export_languages.php Download OS languages table dump]
 * For gzip compression use function which adds no header to output, for PHP it's: [http://www.php.net/manual/en/function.gzcompress.php gzcompress]. For decompression use [http://www.php.net/gzuncompress gzdecompress].


= XML-RPC methods =

== Session handling ==
  * [wiki:XmlRpcLogIn LogIn] - login user and start session
      '''struct !LogIn(string $username, string $password, string $language, string $useragent)'''
  * [wiki:XmlRpcLogOut LogOut] - logout user and end session
      '''struct !LogOut(string $token)'''
  * [wiki:XmlRpcNoOperation NoOperation] - keep-alive user's session, verify token/session validity
      '''struct !NoOperation(string $token)'''


== Search and download ==
  * [wiki:XmlRpcSearchSubtitles SearchSubtitles] - search for subtitles using video hashes or IMDb ID
      '''struct !SearchSubtitles(string $token, array(struct('sublanguageid' => string $sublanguageid, 'moviehash' => string $moviehash, 'moviebytesize' => int $moviesize, 'imdbid' => string $imdbid ), struct(...)))'''
  * [wiki:XmlRpcSearchToMail SearchToMail] - search for subtitles, send results to user's e-mail address
      '''struct !SearchToMail(string $token, array($sublanguageid, $sublanguageid, ...) $sublangs, array(struct('moviehash' => string $moviehash, 'moviesize' => double $moviesize), ...))'''
  * [wiki:XmlRpcDownloadSubtitles DownloadSubtitles] - download given subtitle files
      '''struct !DownloadSubtitles(string $token, array($IDSubtitleFile, $IDSubtitleFile,...) $data)'''


== Upload ==
  * [wiki:XmlRpcTryUploadSubtitles TryUploadSubtitles] - check subtitles before uploading
      '''struct !TryUploadSubtitles(string $token, struct('cd1' => struct('subhash' => string $submd5hash, 'subfilename' => string $subfilename, 'moviehash' => string $moviehash, 'moviebytesize' => string double $moviesize, 'movietimems' => int $movietimems, 'movieframes' => int $movieframes, 'moviefps' => double $moviefps, 'moviefilename' => string $moviefilename) $subfile, 'cd2' => struct(...) $subfile) $subs)'''
  * [wiki:XmlRpcUploadSubtitles UploadSubtitles] - upload given subtitle
      '''struct !TryUploadSubtitles(string $token, struct('cd1' => struct('subhash' => string $submd5hash, 'subfilename' => string $subfilename, 'moviehash' => string $moviehash, 'moviebytesize' => string double $moviesize, 'movietimems' => int $movietimems, 'movieframes' => int $movieframes, 'moviefps' => double $moviefps, 'moviefilename' => string $moviefilename) $subfile, 'cd2' => struct(...) $subfile) $subs)'''


== Movies ==
  * [wiki:XmlRpcSearchMoviesOnIMDB SearchMoviesOnIMDB] -
  * [wiki:XmlRpcGetIMDBMovieDetails GetIMDBMovieDetails] - get movie details fro given IMDb ID
  * [wiki:XmlRpcInsertMovie InsertMovie] - insert a new movie


== Reporting and rating ==
  * [wiki:XmlRpcServerInfo ServerInfo] - get basic server information and statistics
  * [wiki:XmlRpcReportMovieHash ReportMovieHash] - report wrong
  * [wiki:XmlRpcSubtitlesVote SubtitlesVote] - rate subtitles


== User interface ==
  * [wiki:XmlRpcGetSubLanguages GetSubLanguages] - get support subtitle languages
  * [wiki:XmlRpcDetectLanguage DetectLanguage] - detect language for given text
  * [wiki:XmlRpcGetAvailableTranslations GetAvailableTranslations] - get list of available translations for a client application
  * [wiki:XmlRpcGetTranslation GetTranslation] - get given language translation file for a client application
  * [wiki:XmlRpcAutoUpdate AutoUpdate] - check for latest version of a client application


== Checking ==
  * [wiki:XmlRpcCheckMovieHash CheckMovieHash] -
  * [wiki:XmlRpcCheckSubHash CheckSubHash] -


= Credits =
  * 2ge - writer of OSDb XML-RPC server-side implementation
  * eduo - supplier of various example inputs/outputs
  * all other contributors