wiki:XmlRpcIntro

Version 10 (modified by majky, 16 years ago) (diff)

Added 'AddComment?' method

Introduction to OSDb

Sections

  1. Introduction to OSDb
  2. Instructions
    1. Languages
    2. File handling
  3. XML-RPC methods
    1. Session handling
    2. Search and download
    3. Upload
    4. Movies
    5. Reporting and rating
    6. User interface
    7. Checking
  4. Credits

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 ​XML-RPC so you might want to take a look at its ​specifications and ​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 ​forum to discuss possibilities.

​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

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:

You can also download ​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 languageCompressDecompressBase64 encodeBase64 decode
PHP​gzcompress​gzdecompress??
TO-DO

XML-RPC methods

Every method returns a XML-RPC struct data type.

On ​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

  • LogIn - login user and start session

struct LogIn(string $username, string $password, string $language, string $useragent)

  • LogOut - logout user and end session

struct LogOut(string $token)

  • NoOperation - keep-alive user's session, verify token/session validity

struct NoOperation(string $token)

Search and download

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

  • 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), ...))

struct DownloadSubtitles(string $token, array($IDSubtitleFile, $IDSubtitleFile,...) $data)

Upload

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)

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

struct SearchMoviesOnIMDB(string $token, string $query)

struct GetIMDBMovieDetails(string $token, string $imdbid)

struct InsertMovie(string $token, struct('moviename' => string $moviename, 'movieyear' => string $movieyear) $movieinfo)

Reporting and rating

  • ServerInfo - get basic server information and statistics

struct ServerInfo()

struct ReportWrongMovieHash(string $token, string $IDSubMovieFile)

struct SubtitlesVote(string $token, struct('idsubtitle' => int $idsubtitle, 'score' => int $score) $vote)

struct AddComment(string $token, struct('idsubtitle' => int $idsubtitle, 'comment' => string $comment, 'badsubtitle' => int $badsubtitle) $data)

User interface

struct GetSubLanguages(string $language = 'en')

struct DetectLanguage(string $token, array($text, $text, ...) $data)

struct GetAvailableTranslations(string $token, string $program)

  • GetTranslation - get given language translation file for a client application

struct GetTranslation(string $token, string $iso639, string $format, string $program )

  • AutoUpdate - check for latest version of a client application

struct AutoUpdate (string $program_name)

Checking

  • CheckMovieHash - check if video files are already stored in the database

struct CheckMovieHash(string $token, array($moviehash, $moviehash, ...) $hashes)

  • 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