= Introduction to OSDb =
[[PageOutline(2, XMLRPC API Methods)]]
[[PageOutline(1, Table of Contents)]]

We decided use [http://www.xmlrpc.com/ XMLRPC] (see [http://www.xmlrpc.com/spec spec] and [http://www.xmlrpc.com/directory/1568/implementations implementations]) as default API for [http://www.opensubtitles.org opensubtitles.org]. Our API supports many methods, so there should not be a problem code some nice applications.

[http://en.wikipedia.org/wiki/XML-RPC Wikipedia]:
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 developing tests do on: http://dev.opensubtitles.org/xml-rpc (currently offline, so do it on main server:)
 * Main server XMLRPC URL: http://www.opensubtitles.org/xml-rpc
 * Before developing let us know, we assign useragent to you, empty useragent will not work.
 * 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 is: [http://www.php.net/manual/en/function.gzcompress.php gzcompress]. For decompression is used [http://www.php.net/gzuncompress gzdecompress].

= XMLRPC methods =

== !ServerInfo ==
'''array !ServerInfo( )'''
This simple function returns basic server info, it could be used for ping or telling server info to client.

Example output:
{{{
subs_downloads : 66149885
movies_aka : 58111
users_loggedin : 30
users_online_program : 184
seconds : 0.007
users_max_alltime : 2163
xmlrpc_version : 0.1
movies_total : 34628
total_subtitles_languages : 50
application : OpenSuber v0.2
contact : admin@opensubtitles.org
last_update_strings : {'el': '2007-02-03 21:36:17', 'en': '2007-02-03 21:36:14', ... }
users_online_total : 1271
xmlrpc_url : http://www.opensubtitles.com/xml-rpc
users_registered : 421100
subs_subtitle_files : 558001
website_url : http://www.opensubtitles.com
}}}

'''Fields explanation:'''
All field are self-explained

----

== !LogIn ==
'''array !LogIn( $username, $password, $language, $useragent )'''
This will login user. This function should be called always when starting talking with server. It returns '''token''', which must be used in later communication. If user has no account, blank username and password should be OK. As language - use [http://en.wikipedia.org/wiki/List_of_ISO_639-2_codes ISO639] 2 letter code and later communication will be done in this language if applicable (error codes and so on). Note: when username and password is blank, status is 200 OK, because we want allow anonymous users too. Useragent cannot be empty string.

Example output:
{{{
   [token] => c8af602fe83c5404966c25da33d8bbaf
   [status] => 200 OK
   [seconds] => 0.338
}}}

'''Fields explanation:'''
 * token => this token string (session id) must be used in later communication
 * status => status code
 * seconds => how long time takes this process on server

----

== !LogOut ==
'''string !LogOut( $token )'''
This will logout user (ends session id). Good call this function is before ending (closing) clients program.

Example output:
{{{
    [status] => 200 OK
    [seconds] => 0.055
}}}

'''Fields explanation:'''
All field are self-explained

----

== !SearchSubtitles ==
'''array !SearchSubtitles( $token, array(array('sublanguageid' => $sublanguageid, 'moviehash' => $moviehash, 'moviebytesize' => $moviesize, ''imdbid => $imdbid'' ),array(...)))'''

This function returns information about found subtitles. It is designed making multiple search at once. Note - result is always grupped by !MovieHash, !MovieByteSize, !SubLanguageID, !IDSubMovieFile, sorted by seencount descending, max results is 250. When nothing is found, 'data' is empty. If sublanguageid is empty, or have value 'all' - it search in every sublanguage. Also, imdbid parameter is '''optional''', when used, it is not needed define moviehash and moviebytesize, so you can search subtitle database with imdbid only. Also remember you can not combine imdbid and moviehash searching in one request. Some data (!IDSubMovieFile, !MovieHash, !MovieByteSize, !MovieTimeMS) are missing in output when searching by imdbid.

Example output:
{{{
    [data] => Array
        (
            [0] => Array
                (
                    [IDSubMovieFile] => 739
                    [MovieHash] => 09a2c497663259cb
                    [MovieByteSize] => 733589504
                    [MovieTimeMS] => 0
                    [MovieFrames] => 0
                    [IDSubtitleFile] => 963
                    [SubFileName] => Night Watch (Nochnoj Dozor) (2004) [1 of 2].srt
                    [SubActualCD] => 1
                    [SubSize] => 30677
                    [SubHash] => 6c2bdbb308760205146cb2807dfc32f6
                    [IDSubtitle] => 771
                    [UserID] => 37047
                    [SubLanguageID] => eng
                    [SubFormat] => srt
                    [SubSumCD] => 2
                    [SubAuthorComment] => 
                    [SubAddDate] => 2005-05-23 07:47:04
                    [SubBad] => 0
                    [SubRating] => 0.0
                    [SubDownloadsCnt] => 315
                    [MovieReleaseName] => AxxO
                    [IDMovie] => 516
                    [IDMovieImdb] => 403358
                    [MovieName] => Nochnoy dozor
                    [MovieNameEng] => Night Watch
                    [MovieYear] => 2004
                    [MovieImdbRating] => 6.3
                    [UserNickName] => onefox
                    [ISO639] => en
                    [LanguageName] => English
                    [SubDownloadLink] => http://www.opensubtitles.org/download/file/963.gz
                    [ZipDownloadLink] => http://www.opensubtitles.org/en/download/sub/771
                )
            [1] => Array
                (
                    [IDSubMovieFile] => 740
                    [MovieHash] => 1dab7c63893d0d81
                    [MovieByteSize] => 733919232
                    [MovieTimeMS] => 0
                    [MovieFrames] => 0
                    [IDSubtitleFile] => 964
                    [SubFileName] => Night Watch (Nochnoj Dozor) (2004) [2 of 2].srt
                    [SubActualCD] => 2
                    [SubSize] => 39074
                    [SubHash] => 021d7bf5480f97d8e0a28f0b0f03b28d
                    [IDSubtitle] => 771
                    [UserID] => 37047
                    [SubLanguageID] => eng
                    [SubFormat] => srt
                    [SubSumCD] => 2
                    [SubAuthorComment] => 
                    [SubAddDate] => 2005-05-23 07:47:04
                    [SubBad] => 0
                    [SubRating] => 0.0
                    [SubDownloadsCnt] => 315
                    [MovieReleaseName] => Diamond
                    [IDMovie] => 516
                    [IDMovieImdb] => 403358
                    [MovieName] => Nochnoy dozor
                    [MovieNameEng] => Night Watch
                    [MovieYear] => 2004
                    [MovieImdbRating] => 6.3
                    [UserNickName] => onefox
                    [ISO639] => en
                    [LanguageName] => English
                    [SubDownloadLink] => http://www.opensubtitles.org/download/file/964.gz
                    [ZipDownloadLink] => http://www.opensubtitles.org/en/download/sub/771
                )
        )
    [seconds] => 2.378
}}}

'''Fields explanation:'''
All field are self-explained. Note: it returns array with two keys. In first key is array of arrays of found subtitles, in second key is number of seconds as usual.

'''NOTE''' The field '!MovieFrames' isn't being send from the server. Make this field optional or just remove it.

----

== !SearchToMail ==
'''array !SearchToMail( $token, array( $sublanguageid, $sublanguageid, ...), array( array( 'moviehash' => $moviehash, 'moviesize' => $moviesize), array( 'moviehash' => $moviehash, 'moviesize' => $moviesize), ...) )''''

This is possible only for logged-in users. Scenario: user have directory with movies, for which he cannot find subtitles. With this function he subscribe to possible results, when someone else will upload matching subtitles. Once a day (or week...based on users profile) will system send subtitle link by mail to user. *Note for developers*: if it is possible, send moviehashes and moviesizes only for first CD in set (for example movie on two CDs), because users will receive duplicated mails (one for first cd and one for second cd)

Example output:
{{{
    [status] => 200 OK
    [seconds] => 1.211
}}}

'''Fields explanation:'''
if no '''sublanguageid''' is given (first array is empty), it means system will try to find subtitles in all languages.

----

== !CheckSubHash ==
'''array !CheckSubHash( $token, array($subhash, $subhash, ...) )'''

This method returns !IDSubtitleFile, if Subtitle Hash exists in database. If not exists, it returns '0'.

Example output:
{{{
    [status] => 200 OK
    [data] => Array
        (
            [a9672c89bc3f5438f820f06bab708067] => 1
            [0ca1f1e42cfb58c1345e149f98ac3aec] => 3
            [11111111111111111111111111111111] => 0
        )
    [seconds] => 0.009
}}}

'''Fields explanation:'''
Array in data contains $subhash => $idsubtitlefile

----

== !CheckMovieHash ==
'''array !CheckMovieHash( $token, array($moviehash, $moviehash, ...) )'''

This method returns !MovieImdbID, !MovieName, !MovieYear, if available for each $moviehash.

Example output:
{{{
    [data] => Array
        (
            [dab462412773581c] => Array
                (
                    [MovieImdbID] => 133152
                    [MovieName] => Planet of the Apes
                    [MovieYear] => 2001
                )
            [ae34f157eefc093c] => Array
                (
                    [MovieImdbID] => 288477
                    [MovieName] => Ghost Ship
                    [MovieYear] => 2002
                )
            [abcdefg123211222] => Array
                (
                )
        )
    [seconds] => 0.046
}}}

'''Fields explanation:'''
Array in data contains $moviehash => array()

----

== !TryUploadSubtitles ==
'''array !TryUploadSubtitles( $token, array('cd1' => array('subhash' => $submd5hash, 'subfilename' => $subfilename, 'moviehash' => $moviehash, 'moviebytesize' => $moviesize, 'movietimems' => $movietimems, 'movieframes' => $movieframes, 'moviefps' => $moviefps, 'moviefilename' => $moviefilename), 'cd2' => array(...) ) )'''

This function needs to be called '''before''' !UploadSubtitles(), because it is possible subtitles already exists on server. It takes 2 parameters, second parameter is array of information for subtitles to be uploaded, minimum cd1 is required. Mandatory fields are: subhash (md5 of subtitles), subfilename, [wiki:HashSourceCodes moviehash], moviebytesize, moviefilename. It returns "alreadyindb" when subtitles already exists in database. When they do not exists, !SearchSubtitles() is called, and API is looking for existing subtitles based on !MovieHash/!MovieSize. If some results are found, information is returned in "data" key as !SearchSubtitles() return structure. This is good for uploading - user should have imdbid field already filled.


Example output when '''subtitles already exists''' in database:
{{{
    [status] => 200 OK
    [alreadyindb] => 1
    [data] => Array
        (
            [IDSubtitle] => 1
            [SubLanguageID] => eng
            [IDMovieImdb] => 103644
            [MovieName] => AlienÂł
            [MovieYear] => 1992
            [MoviefilenameWasAlreadyInDb] => 0
            [HashWasAlreadyInDb] => 1
        )
    [seconds] => 0.078
}}}

'''!MoviefilenameWasAlreadyInDb''' - if 0, it means new moviefilename was inserted to database. '''!HashWasAlreadyInDb''' - if 0, it means new !MovieHash was inserted to database.

Example output when '''subtitles are not''' in database:
{{{
(moviesize and moviehash exists in db, but not subhash, on client side should be filled !IDMovieImdb from this info)
    [status] => 200 OK
    [alreadyindb] => 0
    [data] => Array
        (
            [0] => Array
                (
                    [IDSubMovieFile] => 739
                    [MovieHash] => 09a2c497663259cb
                    [MovieByteSize] => 733589504
                    [MovieTimeMS] => 0
                    [MovieFrames] => 0
                    [IDSubtitleFile] => 963
                    [SubFileName] => Night Watch (Nochnoj Dozor) (2004) [1 of 2].srt
                    [SubActualCD] => 1
                    [SubSize] => 30677
                    [SubHash] => 6c2bdbb308760205146cb2807dfc32f6
                    [IDSubtitle] => 771
                    [UserID] => 37047
                    [SubLanguageID] => eng
                    [SubFormat] => srt
                    [SubSumCD] => 2
                    [SubAuthorComment] => 
                    [SubAddDate] => 2005-05-23 07:47:04
                    [SubBad] => 0
                    [SubRating] => 0.0
                    [SubDownloadsCnt] => 315
                    [IDMovie] => 516
                    [IDMovieImdb] => 403358
                    [MovieName] => Nochnoy dozor
                    [MovieNameEng] => Night Watch
                    [MovieYear] => 2004
                    [MovieImdbRating] => 6.3
                    [UserNickName] => onefox
                    [ISO639] => en
                    [LanguageName] => English
                    [SubDownloadLink] => http://www.opensubtitles.org/en/download/file/963.gz
                )
        )
    [seconds] => 0.132
}}}

'''Fields explanation:'''
All field are self-explained.

----

== !UploadSubtitles ==
'''array !UploadSubtitles( $token,array( 'baseinfo' => array ( 'idmovieimdb' => $idmovieimdb, 'moviereleasename' => $scene_releasename, 'movieaka' => $aka_in_subtitle_language, 'sublanguageid' => $sublanguageid, 'subauthorcomment' => $author_comment ), 'cd1' => array( 'subhash' => $md5subhash, 'subfilename' => $subfilename, 'moviehash' => $moviehash, 'moviebytesize' => $moviebytesize, 'movietimems' => $movietimems, 'moviefps' => $moviefps, 'movieframes' => $movieframes, 'moviefilename' => $moviefilename, 'subcontent' => $subtitlecontent ), 'cd2' => array (...) ) )'''

This function have to be called after !TryUploadSubtitles(). Many information are same, important part is '''subcontent'''. It should be gzip-ed (without header) and must be base64 encoded. 

Example output:
{{{
    [status] => 200 OK
    [data] => http://www.opensubtitles.org/subtitles/123456
    [seconds] => 1.171
}}}

'''Fields explanation:'''
data is absolute link to subtitles.
----

== !DetectLanguage ==

'''array !DetectLanguage( $token, array($text, $text, ...) )'''

Returns array of MD5 => ISO639-2 language codes, trying to detect language for given $text. Note: $text MUST be base64 encoded and should be gzipped (without header), for save some bandwidth and for better speed. MD5 is md5() of unpacked text, input text should be up to 4096 bytes long for good results - but you can send all contents of subtitles. [http://www.boxoffice.ch/pseudo/ PHP textcat]

Example output:
{{{
    [status] => 200 OK
    [data] => Array
       (
            [9e107d9d372bb6826bd81d3542a419d6] => eng
            [ffd93f16876049265fbaef4da268dd0e] => cze
            ...
       )
    [seconds] => 0.625
}}}

Fields explanation: All fields are self-explained. Note: if you get instead of 3 characters language some other languagename - please contact us with input/output text (for example scots) 

----

== !DownloadSubtitles ==
'''array !DownloadSubtitles( $token, array($IDSubtitleFile, $IDSubtitleFile,...) )'''

Returns BASE64 encoded gzipped !IDSubtitleFile(s). You need to BASE64 decode and ungzip 'data' to get its contents.

Example output:
{{{
    [status] => 200 OK
    [data] => Array
        (
            [0] => Array
                (
                    [idsubtitlefile] => 10
                    [data] => MQ0KMDA6MDA6MzgsMzAwIC0tPiAwMDowMDo0MSwwMDA...
                )
            [1] => Array
                (
                    [idsubtitlefile] => 20
                    [data] => MQ0KMDA6MDA6MjYsMjgzIC0tPiAwMD...
                )
    [seconds] => 0.397
}}}

'''Fields explanation:'''
All field are self-explained. 

----

== !ReportWrongMovieHash ==
'''array !ReportWrongMovieHash( $token, $IDSubMovieFile )'''

This method is needed to report bad hash, e.g. subtitles are right for this movie file, but they are de-synchornized - for other version/release. With this method number of reports is counted in db, and after some number, hash will be automatically deleted from database.

Example output:
{{{
    [status] => 200 OK
    [seconds] => 0.115
}}}

'''Fields explanation:'''
All field are self-explained. 


== !GetSubLanguages ==
'''array !GetSubLanguages( $language = 'en' )'''

Returns list of allowed subtitle languages, default is english language. Use [http://www.loc.gov/standards/iso639-2/php/code_list.php ISO639-1] (2 characters code)

Example output:
{{{
    [data] => Array
        (
            [0] => Array
                (
                    [SubLanguageID] => alb
                    [LanguageName] => Albanian
                    [ISO639] => sq
                )
            [1] => Array
                (
                    [SubLanguageID] => ara
                    [LanguageName] => Arabic
                    [ISO639] => ar
                )
            ...
    [seconds] => 0.043
}}}

'''Fields explanation:'''
data - array of enabled subtitle languages. !SubLanguageID - iso639-2 3 characters code of language. !LanguageName - translated language name. ISO639 - ISO639-1 2 characters code.

== !GetAvailableTranslations ==
'''array !GetAvailableTranslations( $token, $program )'''

Returns array of available translations for a program. In array you can find date of last created string and number of strings. Current supported programs are 'subdownloader' and 'oscar'

Example output:
{{{
    [status] => 200 OK
    [data] => Array
        (
            [en] => Array
                (
                    [LastCreated] => 2007-02-03 21:36:14
                    [StringsNo] => 438
                )
            [ar] => Array
                (
                    [LastCreated] => 2007-02-26 11:32:20
                    [StringsNo] => 438
                )
            ...
    [seconds] => 0.486
}}}
 
'''Fields explanation:'''
All field are self-explained. 

----

== !GetTranslation ==
'''array !GetTranslation( $token, $iso639, $format, $program )'''

Returns base64 encoded strings for language ($iso639) in some $format (mo, po, txt, xml). Use [http://www.loc.gov/standards/iso639-2/php/code_list.php ISO639-1] (2 characters code), $program should be 'subdownloader' or 'oscar'

Example output:
{{{
    [status] => 200 OK
    [data] => bXNnaWQgIiINCm1zZ3N0ciAiIg0KIlByb2plY3QtSWQtVmVyc2lvbjogT3BlblN1YnRp...
    [seconds] => 0.192
}}}
 
'''Fields explanation:'''
data - base64 encoded contents

== SearchMoviesOnIMDB ==
'''array SearchMoviesOnIMDB( $token, $query )'''

Returns array of movies, which was found on imdb.com, query is first fixed for some strings (deleted dvdrip and so on)

Example output for 'troy':
{{{
    [status] => 200 OK
    [data] => Array
        (
            [0] => Array
                (
                    [id] => 0332452
                    [title] => Troy (2004)
                )

            [1] => Array
                (
                    [id] => 0340477
                    [title] => Helen of Troy (2003) (TV)
                )
            ...
    [seconds] => 0.441
}}}
 
'''Fields explanation:'''
title - title of movie, id - imdbid


== GetIMDBMovieDetails ==
'''array GetIMDBMovieDetails( $token, $imdbid )'''

Returns array, info for $imdbid from [http://www.imdb.com www.imdb.com].

Example output for '0480011':
{{{
    [status] => 200 OK
    [data] => Array
       (
            [cast] => Array
                (
                    [_0000096] => Gillian Anderson
                    [_0245705] => Danny Dyer
                    ...
                )
            [rating] => 5.9
            [cover] => http://ia.imdb.com/media/imdb/01/I/48/24/52/10m.jpg
            [id] => 0480011
            [votes] => 919
            [title] => Straightheads
            [aka] => Array
                (
                    [0] => Closure (USA) (DVD title)
                )

            [year] => 2007            
            ...
       )
    [seconds] => 0.441
}}}
 
'''Fields explanation:'''
All fields are self-explained.


== !AutoUpdate ==
'''array !AutoUpdate ( $program_name )'''

This function returns latest version with info for $program_name

Example output:
{{{
    [version] => 1.2.3
    [url_windows] => http://forja.rediris.es/frs/download.php/123/subdownloader1.2.3.exe
    [url_linux] => http://forja.rediris.es/frs/download.php/124/SubDownloader1.2.3.src.zip
    [comments] => MultiUpload CDs supported(more than 2CDs)|Lots of bugs fixed
    [status] => 200 OK

If $program_name is invalid it returns:
    [status] => 408 Invalid parameters
}}}

'''Fields explanation:'''
All field are self-explained.

== !NoOperation ==
'''array !NoOperation( $token )'''

This function should be called each 15 minutes after last request to xmlrpc. It is used for not expiring current session. It also returns if current $token is registered.

Example output when token is registered:
{{{
    [status] => 200 OK
    [seconds] => 0.055
}}}
When it is not registered, in client should be called !LogIn() again. Example of response:
{{{
    [status] => 406 No session
    [seconds] => 0.061
}}}

'''Fields explanation:'''
All field are self-explained.

----

= Status codes =

'''Successful 2xx'''
 * 200 OK
 * 206 Partial content; message

'''Errors 4xx'''
 * 401 Unauthorized
 * 402 Subtitles has invalid format
 * 403 !SubHashes (content and sent subhash) are not same!
 * 404 Subtitles has invalid language!
 * 405 Not all mandatory parameters was specified
 * 406 No session
 * 407 Download limit reached
 * 408 Invalid parameters
 * 409 Method not found
 * 410 Other or unknown error
 * 411 Empty or invalid useragent
 * 412 %s has invalid format (reason)