= Introduction to OSDb = [[PageOutline(1-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. == Languages == The API is working with either 2 (ISO 639-1) or 3-letter (ISO 639-2) language codes depending on the implementation. To learn more, see the specifications and get language lists, visit: * [http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes List of ISO 639-1 2-letter codes on Wikipedia] * [http://en.wikipedia.org/wiki/List_of_ISO_639-2_codes List of ISO 639-2 3-letter codes on Wikipedia] You can also download [http://www.opensubtitles.org/addons/export_languages.php OS languages] table dump. You should use '''pb/pob''' for Portuguese (Brazil). == File handling == When sending files (download, upload, etc.) files are usually sent as first gzipped (without header) then base64-encoded contents. So when trying to get the contents you should first base64-decode, then gunzip it. gzip compression uses a function which adds no header to output. Here's a list of functions you can use: ||Programming language||Compress||Decompress||Base64 encode||Base64 decode|| ||PHP||[http://www.php.net/manual/en/function.gzcompress.php gzcompress]||[http://www.php.net/gzuncompress gzdecompress]||?||?|| {{{ #!html
TO-DO
}}} ---- = XML-RPC methods = Every method returns a XML-RPC ''struct'' data type. On [http://www.opensubtitles.org OpenSubtitles.org] most XML-RPC API server-side implementation most single-type variables in method output are of type ''string'' (even though you might expect ''int'' so beware) ---- == 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 !UploadSubtitles(string $token, struct('baseinfo' => struct('idmovieimdb' => string $idmovieimdb, 'moviereleasename' => string $scene_releasename, 'movieaka' => string $aka_in_subtitle_language, 'sublanguageid' => string $sublanguageid, 'subauthorcomment' => string $author_comment), 'cd1' => struct('subhash' => string $md5subhash, 'subfilename' => string $subfilename, 'moviehash' => string $moviehash, 'moviebytesize' => double $moviebytesize, 'movietimems' => int $movietimems, 'moviefps' => double $moviefps, 'movieframes' => int $movieframes, 'moviefilename' => string $moviefilename, 'subcontent' => string $subtitlecontent), 'cd2' => struct(...)))''' ---- == Movies == * [wiki:XmlRpcSearchMoviesOnIMDB SearchMoviesOnIMDB] - search for a movie (using movie title) '''struct SearchMoviesOnIMDB(string $token, string $query)''' * [wiki:XmlRpcGetIMDBMovieDetails GetIMDBMovieDetails] - get movie details for given IMDb ID '''struct GetIMDBMovieDetails(string $token, string $imdbid)''' * [wiki:XmlRpcInsertMovie InsertMovie] - insert a new movie '''struct !InsertMovie(string $token, struct('moviename' => string $moviename, 'movieyear' => string $movieyear) $movieinfo)''' ---- == Reporting and rating == * [wiki:XmlRpcServerInfo ServerInfo] - get basic server information and statistics '''struct !ServerInfo()''' * [wiki:XmlRpcReportMovieHash ReportMovieHash] - report wrong subtitle file <--> video file combination '''struct !ReportWrongMovieHash(string $token, string $IDSubMovieFile)''' * [wiki:XmlRpcSubtitlesVote SubtitlesVote] - rate subtitles '''struct !SubtitlesVote(string $token, struct('idsubtitle' => int $idsubtitle, 'score' => int $score) $vote)''' * [wiki:XmlRpcAddComment AddComment] - add comment to a subtitle '''struct !AddComment(string $token, struct('idsubtitle' => int $idsubtitle, 'comment' => string $comment, 'badsubtitle' => int $badsubtitle) $data)''' ---- == User interface == * [wiki:XmlRpcGetSubLanguages GetSubLanguages] - get supported subtitle languages '''struct !GetSubLanguages(string $language = 'en')''' * [wiki:XmlRpcDetectLanguage DetectLanguage] - detect language for given text '''struct !DetectLanguage(string $token, array($text, $text, ...) $data)''' * [wiki:XmlRpcGetAvailableTranslations GetAvailableTranslations] - get list of available translations for a client application '''struct !GetAvailableTranslations(string $token, string $program)''' * [wiki:XmlRpcGetTranslation GetTranslation] - get given language translation file for a client application '''struct !GetTranslation(string $token, string $iso639, string $format, string $program )''' * [wiki:XmlRpcAutoUpdate AutoUpdate] - check for latest version of a client application '''struct !AutoUpdate (string $program_name)''' ---- == Checking == * [wiki:XmlRpcCheckMovieHash CheckMovieHash] - check if video files are already stored in the database '''struct !CheckMovieHash(string $token, array($moviehash, $moviehash, ...) $hashes)''' * [wiki:XmlRpcCheckSubHash CheckSubHash] - check if given subtitle files are already stored in the database '''struct !CheckSubHash(string $token, array($subhash, $subhash, ...) $hashes)''' ---- = Credits = * 2ge - developer of OSDb XML-RPC server-side implementation * eduo - supplier of various example inputs/outputs * all other contributors