wiki:XMLRPC

Version 35 (modified by os, 14 years ago) (diff)

--

Introduction to OSDb

We decided use XMLRPC (see spec and implementations) as default API for opensubtitles.org. Our API supports many methods, so there should not be a problem code some nice applications.

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

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 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. For $useragent use your registered useragent, also provide version number - we need tracking version numbers of your program.

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, query => 'movie name' ),array(...)))

Returns information about found subtitles. It is designed making multiple search at once. When nothing is found, 'data' is empty. If sublanguageid is empty, or have value 'all' - it search in every sublanguage, you can set it to multiple languages (e.g. eng,dut,cze).

If you define moviehash and moviebytesize, then imdbid and query in same array are ignored. If you define imdbid, then moviehash, moviebytesize and query is ignored. If you define query, then moviehash, moviebytesize and imdbid is ignored. Pseudocode:

if(defined($moviehash) and defined($moviebytesize)) {
  // search by $moviehash and $moviebytesize
} elseif (defined($imdbid)) {
  // search by $imdbid
} elseif (defined($query)) {
  // fulltext search by $query
} else {
  // empty result
}
  • Some data (IDSubMovieFile, MovieHash, MovieByteSize, MovieTimeMS) are set to 0, when searching by imdbid or query
  • Max results is set to 500 found items in total
  • For perfect matches use moviehash/moviebytesize searching, for movie matches use imdbid searching, if you can not use any of them, use fulltext search
  • If used this method in movie player and subtitles are found using imdbid or query, should be nice to implement Automatic Uploading, so we get back movie hash of matching movie
  • MatchedBy can be: moviehash, imdbid, fulltext (so you know from where results comes from)

Example output:

    [data] => Array
        (
            [0] => Array
                (
                    [MatchedBy] => moviehash
                    [IDSubMovieFile] => 82181
                    [MovieHash] => 09a2c497663259cb
                    [MovieByteSize] => 733589504
                    [MovieTimeMS] => 3165000
                    [IDSubtitleFile] => 1951690121
                    [SubFileName] => Night.Watch.2004.CD1.DVDRiP.XViD-FiCO.srt
                    [SubActualCD] => 1
                    [SubSize] => 27287
                    [SubHash] => fe106fe2368799bdc73271bb24ac6df7
                    [IDSubtitle] => 3144301
                    [UserID] => 367123
                    [SubLanguageID] => dut
                    [SubFormat] => srt
                    [SubSumCD] => 1
                    [SubAuthorComment] => 
                    [SubAddDate] => 2007-08-31 22:18:20
                    [SubBad] => 0
                    [SubRating] => 0.0
                    [SubDownloadsCnt] => 253
                    [MovieReleaseName] => Night Watch
                    [IDMovie] => 516
                    [IDMovieImdb] => 403358
                    [MovieName] => Nochnoy dozor
                    [MovieNameEng] => Night Watch
                    [MovieYear] => 2004
                    [MovieImdbRating] => 0.0
                    [UserNickName] => gyoom
                    [ISO639] => nl
                    [LanguageName] => Dutch
                    [SubComments] => 0
                    [SubDownloadLink] => http://www.opensubtitles.org/en/download/file/1951690121.gz
                    [ZipDownloadLink] => http://www.opensubtitles.org/en/download/sub/3144301
                    [SubtitlesLink] => http://www.opensubtitles.net/en/subtitles/3144301/nochnoy-dozor-nl
                )

            [1] => Array
                (
                    [MatchedBy] => moviehash
                    [IDSubMovieFile] => 82182
                    [MovieHash] => 09a2c497663259cb
                    [MovieByteSize] => 733589504
                    [MovieTimeMS] => 3165000
                    [IDSubtitleFile] => 1951690122
                    [SubFileName] => Night.Watch.2004.CD1.DVDRiP.XViD-FiCO.srt
                    [SubActualCD] => 1
                    [SubSize] => 27287
                    [SubHash] => fe106fe2368799bdc73271bb24ac6df7
                    [IDSubtitle] => 3144302
                    [UserID] => 367123
                    [SubLanguageID] => dut
                    [SubFormat] => srt
                    [SubSumCD] => 2
                    [SubAuthorComment] => 
                    [SubAddDate] => 2007-08-31 22:23:39
                    [SubBad] => 0
                    [SubRating] => 0.0
                    [SubDownloadsCnt] => 89
                    [MovieReleaseName] => Night Watch
                    [IDMovie] => 516
                    [IDMovieImdb] => 403358
                    [MovieName] => Nochnoy dozor
                    [MovieNameEng] => Night Watch
                    [MovieYear] => 2004
                    [MovieImdbRating] => 0.0
                    [UserNickName] => gyoom
                    [ISO639] => nl
                    [LanguageName] => Dutch
                    [SubComments] => 0
                    [SubDownloadLink] => http://www.opensubtitles.org/en/download/file/1951690122.gz
                    [ZipDownloadLink] => http://www.opensubtitles.org/en/download/sub/3144302
                    [SubtitlesLink] => http://www.opensubtitles.net/en/subtitles/3144302/nochnoy-dozor-nl
                )
...

Fields explanation: All field are self-explained.


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 best matching !MovieImdbID, MovieName, MovieYear, if available for each $moviehash. See also CheckMovieHash2(). Read more about Movie Identification.

Example output:

    [status] => 200 OK
    [data] => Array
        (
            [dab462412773581c] => Array
                (
                    [MovieHash] => dab462412773581c
                    [MovieImdbID] => 133152
                    [MovieName] => Planet of the Apes
                    [MovieYear] => 2001
                )

            [ae34f157eefc093c] => Array
                (
                    [MovieHash] => ae34f157eefc093c
                    [MovieImdbID] => 288477
                    [MovieName] => Ghost Ship
                    [MovieYear] => 2002
                )

            [abcdefg123211222] => Array
                (
                )

        )

    [seconds] => 0.133

Fields explanation: Array in data contains $moviehash => array(), even for unmatched moviehashes.


!CheckMovieHash2

array !CheckMovieHash2( $token, array($moviehash, $moviehash, ...) )

This method returns matching !MovieImdbID, MovieName, MovieYear, if available for each $moviehash, always sorted by SeenCount DESC. Read more about Movie Identification.

Example output:

    [status] => 200 OK
    [data] => Array
        (
            [3b2ae156d8c11f7a] => Array
                (
                    [0] => Array
                        (
                            [MovieHash] => 3b2ae156d8c11f7a
                            [MovieImdbID] => 103644
                            [MovieName] => Alien³
                            [MovieYear] => 1992
                            [SeenCount] => 48
                        )

                    [1] => Array
                        (
                            [MovieHash] => 3b2ae156d8c11f7a
                            [MovieImdbID] => 133093
                            [MovieName] => The Matrix
                            [MovieYear] => 1999
                            [SeenCount] => 5
                        )

                )

            [53fc6fe84ad5ee31] => Array
                (
                    [0] => Array
                        (
                            [MovieHash] => 53fc6fe84ad5ee31
                            [MovieImdbID] => 813715
                            [MovieName] => "Heroes"
                            [MovieYear] => 2006
                            [SeenCount] => 427
                        )

                    [1] => Array
                        (
                            [MovieHash] => 53fc6fe84ad5ee31
                            [MovieImdbID] => 1185913
                            [MovieName] => "Heroes" One of Us, One of Them
                            [MovieYear] => 2008
                            [SeenCount] => 260
                        )

                )
        ...

Fields explanation: Array in data contains $moviehash => array(), only for matched moviehashes.


InsertMovieHash

array InsertMovieHash( $token, array( array('moviehash' => $moviehash, 'moviebytesize' => $moviebytesize, 'imdbid' => $imdbid, 'movietimems' => $movietimems, 'moviefps' => $moviefps, 'moviefilename' => $moviefilename), array(...) ) )

Inserts or updates data to tables, which are used for CheckMovieHash() and !CheckMovieHash2(). Requested parameters are: moviehash, moviebytesize, imdbid, all rest parameters are optional, but preferred to supply them. Before accepting moviehashes, each moviehash is checked against log table if user doesn't already send it. Read more about Movie Identification.

Example output:

    [status] => 200 OK
    [data] => Array
        (
            [accepted_moviehashes] => Array
                (
                    [0] => 53fc6fe84ad5ee31
                    [1] => 3b2ae156d8c11f7a
                )

            [new_imdbs] => Array
                (
                )

        )

    [seconds] => 0.014

Fields explanation: accepted_moviehashes - hashes, which was inserted or updated, new_imdbs - imdb ids need to download from imdb.com


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, 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, 'hearingimpaired' => $hearing_impaired, 'highdefinition' => $high_definition, 'automatictranslation' => $automatic_translation), '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. Also please don't put any advertisment (eg. Uploaded by My Application) anywhere (eg. subauthorcomment), it will be deleted. sublanguageid - is optional, if it is not present, or is set to not allowed language string (eg 'unk'), auto-detection language of subtitles will be performed. Optional parameters in this method are: moviereleasename, movieaka, sublanguageid, subauthorcomment, hearingimpaired, highdefinition, automatictranslation, movietimems, moviefps, movieframes. If hearingimpaired, highdefinition and automatictranslation are not defined, set to 0 or empty flag will be not set.

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. 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 language name - please contact us with input/output text (for example you can get scots), we will analyze that file.


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 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 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 and in opensubtitles internal movie database where id starts at 10000000. 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/opensubtites movie id


GetIMDBMovieDetails

array GetIMDBMovieDetails( $token, $imdbid )

Returns array, info for $imdbid from 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.


InsertMovie

array InsertMovie( $token, array('moviename' => $moviename, 'movieyear' => $movieyear) )

Allows logged users insert new movies to opensubtitles internal movie database, which are not in IMDB.com. Guidelines for application: when user enters movie name and movie year call in your app SearchMoviesOnIMDB() where are returned movies stored in imdb.com and opensubtitles.org. When user checks movie does not exists in list, allow him to insert new movie. This needs to be done to avoid duplicates.

Example output:

    [status] => 200 OK
    [id] => 10000044
    [seconds] => 0.441

Fields explanation: id is idmovie in opensubtitles.org movie database for inserted movie. You can use it later for uploading subtitles.


SubtitlesVote

array SubtitlesVote( $token, array('idsubtitle' => $idsubtitle, 'score' => $score) )

Allows logged users vote for subtitles. Score must be from interval 1 to 10. If user will vote more than 1 time for same subtitles, next votes will be not counted.

Example output:

    [status] => 200 OK
    [data] => Array
        (
            [SubRating] => 8.0
            [SubSumVotes] => 1
            [IDSubtitle] => 3331501
        )

    [seconds] => 0.075

Fields explanation: SubRating is average subrating for given subtitles. SubSumVotes is how much times was voted for subtitles.


GetComments

array GetComments( $token, array($idsubtitle, $idsubtitle, ...))

Returns comments for subtitles

Example output:

    [status] => 200 OK
    [data] => Array
        (
            [_3387112] => Array
                (
                    [0] => Array
                        (
                            [IDSubtitle] => 3387112
                            [UserID] => 192696
                            [UserNickName] => neo_rtr
                            [Comment] => Greate Work. thank you
                            [Created] => 2008-12-14 17:20:42
                        )

                )
            [_3385570] => Array
                (
                    [0] => Array
                        (
                            [IDSubtitle] => 3385570
                            [UserID] => 745565
                            [UserNickName] => pee-jay_cz
                            [Comment] => Thank you.
                            [Created] => 2008-12-12 15:21:48
                        )
                    [1] => Array
                        (
                            [IDSubtitle] => 3385570
                            [UserID] => 754781
                            [UserNickName] => Guzeppi
                            [Comment] => You're welcome :)
                            [Created] => 2008-12-12 15:51:01
                        )
                )
        )
    [seconds] => 0.02

Fields explanation: All field are self-explained.


AddComment

array AddComment( $token, array('idsubtitle' => $idsubtitle, 'comment' => $comment, 'badsubtitle' => $int) )

Allows logged users add new comment to subtitles. badsubtitle is optional, if set to 1, subtitles are marked as bad

Example output:

Array
(
    [status] => 200 OK
    [seconds] => 0.228
)

Fields explanation: All field are self-explained.


AddRequest

array AddRequest( $token, array('sublanguageid' => $sublanguageid, 'idmovieimdb' => $idmovieimdb, 'comment' => $comment ) )

Add new request for subtitles, user must be logged in. All parameters are mandatory except comment field - you can put there releasename of movie. You should call this method, when no subtitles are found for given IMDB (not for moviehash!) and it should be done on user request. When request is filled, user should receive mail from opensubtitles.org about that.

Example output:

Array
(
    [status] => 200 OK
    [data] => Array
        (
            [request_url] => http://www.opensubtitles.net/en/requestd/idmovie-887/sublanguageid-cze
        )

    [seconds] => 7.676
)

Fields explanation: All field 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

XMLRPC should always return status code. For 2xx it means operation was sucessful, for 4xx it means there was some error and client should display this error to user.

Successful 2xx

  • 200 OK
  • 206 Partial content; message

Moved 3xx

  • 301 Moved (host)

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)
  • 413 Invalid ImdbID

Server Error 5xx

  • 503 Service Unavailable