Introduction to OSDb

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

• 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:

• ​List of ISO 639-1 2-letter codes on Wikipedia
• ​List of ISO 639-2 3-letter codes on Wikipedia

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 language	Compress	Decompress	Base64 encode	Base64 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

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

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

• DownloadSubtitles - download given subtitle files

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

---

Upload

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

• 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

• SearchMoviesOnIMDB - search for a movie (using movie title)

struct SearchMoviesOnIMDB(string $token, string $query)

• GetIMDBMovieDetails - get movie details for given IMDb ID

struct GetIMDBMovieDetails(string $token, string $imdbid)

• InsertMovie - insert a new movie

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

---

Reporting and rating

• ServerInfo - get basic server information and statistics

struct ServerInfo()

• ReportMovieHash - report wrong
• SubtitlesVote - rate subtitles

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

---

User interface

• GetSubLanguages - get supported subtitle languages

struct GetSubLanguages(string $language = 'en')

• DetectLanguage - detect language for given text

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

• GetAvailableTranslations - get list of available translations for a client application

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