OpenSubtitles forum

Hi guys,

More and more clients are connecting to opensubtitles API using XML-RPC which is difficult to cache. We are proud to present you REST search. Idea is simple - client make URL, request it and we cache results on CDN (in Cloudflare), that means, responses are faster and our servers can take care of something else.

Make sure you provide your XML-RPC useragent (API) in http header. (#curl -A 'registeredUA' or <?php curl_setopt($curl, CURLOPT_USERAGENT, $agent); )

OK, how it looks?
to create request you need base URL, which is https://rest.opensubtitles.org/search and then search parameters ordered by name, otherwise you will be redirected (please sort them on client side!). Make sure url is in _lowercase_, otherwise redirect. Valid parameters are: Valid URLs (examples, try yourself to combine): NEW: for clients unable to change default User Agent it is possible now to set up custom HTTP header 'X-User-Agent':
INVALID URLs: Results are limited to 500 items. This REST method (search) is public and doesn't need any key or any special user-agent. Results are sorted by SCORE, so which are first in list should be better.
Always check for 200 response http code.
Example:
If you will find out this useful, let us know.

More REST methods to play with: Example passing SID parameter for download URL: If you want to download subtitles as logged in user, either use http basic auth, or add sid parameter into download link.

Nice.

What happens if only bytesize and hash are provided but not IMDBid? Or only IMDBid?

I understand that if I have 50 files (2 tv seasons) I must make 50 queries for each subtitle language. What are the limits (based on IP, I guess) for this method?

What agent should we use? Not sure if you're keeping statistics.

Hi Eduo, long time...

to answer your questions - you can try. Of course you can query just by imdbid:
https://rest.opensubtitles.org/search/i ... uageid-cze

or just moviehash and moviebytesize:
https://rest.opensubtitles.org/search/m ... c54e9cf314

if you have 50 files, you have to make 50 queries (by moviehash for example), yes. If you want 1 language not a problem, if you want all languages not a problem, but if you want 2 languages, you have to make 2 queries per file - it is done for sake of caching on CF (better hit ratio), but more requests...I know.

there is not limits, no UA needed just speed limit: 40 queries per IP per 10 seconds. We not making any stats for now.

This should help to avoid LogIn() in XMLRPC and caching better in CF.

But you are right, maybe we should request setting HTTP UA to actually know what is going on.

EDIT: I added UA checking, it makes sense.

Can you please post an example of an http header with a fake XML-RPC useragent in it?
Do you mean instead of "Mozilla/5.0 (Windows NT 5.1; rv:14.0) Gecko/20100101 Firefox/24.0.1" or whatever, I should use my app's user agent in the http request?

The rest of the calls look really straightforward (even for me ;o)

hi, yes instead of standard HTTP user agent you must use the user agent, which is registered for xml-rpc. I post example using "curl" command, in every language you define different user agent, for sure you will find it.

I tried the rest API today and it looks very nice.
There are some issues though.
One has to do with the subtitles returned.
Alternating between the XML-RPC and the JSON method does not return the same results for the same file.
JSON returns less some of the times.
With XML-RPC I use only the hash and the size (and the language).
With the JSON I also add the title as query, thinking that it might get me more results.
I tried with the title omitted and got the same results some of the times.
This is strange.

The other thing has to do with the limit of queries (40).
Almost all my friends that use Subber always search for at least 2 languages. English and their native one.
If they drop a Series folder to search, the number of files can easily get more than 20.
One season of a series can be more than 20.
Some series can get more than 200.
It might be more helpful to be able to send an array of languageIDs with the REST and get only these returns.
As it is now, I get all the languages and then I filter the ones I don't need.
This works but is a little wasteful.
Perhaps the limit is a tad low...

Should I use JSON instead XML-RPC ?

JSON API means you can issue a JSON request to server just like other JSON requests.
Because the JSON API is PUBLIC that means you will not need LOGIN credentials, and that is one request less to the OPENSUBTITILES servers.
Also, since the requests are cached, there is faster response too. Keep in mind that your USERAGENT must be registered and approved in OPENSUBTITLES or you will get a response "http useragent is not valid"
To make a simple test to the API, use a REST Client such as in Firefox you can install the AddOn RESTED client:
Open it, then enter the following:

URL: https://rest.opensubtitles.org/search/m ... c54e9cf314

Headers -> Add a New Header and on name field enter: User-Agent and on it value field enter "TemporaryUserAgent" don't forget the quotes.
Remember "TemporaryUserAgent" is for Development only and it has limitation; hence don't use it in production and instead use yours.

Click Submit, and Voilah! Your response will be there in nicely formatted JSON.

Hope this helps

Hi OpenSubttitles,

I was trying to use the new API in my application written in QT, but unfortunately QT doesn't allow change of User-Agent in the request header. It always defaults to Mozilla/5.0 as User-Agent.
Is it possible to use a custom request header name instead in order to pass this restriction?

Hi,

for QT set UA, quick google shows this: https://wiki.qt.io/How_to_set_user_agen ... pplication

it is not solution for your problem?

Hi Oss,

Thank you. This actually worked.
Another method is this http://www.misterion.ru/2012/10/qt-qml-user-agent.html
But i prefer yours instead.

Hi Oss,

I try this new API:
https://rest.opensubtitles.org/search/i ... /season-1/

But unfortunately, when I try to download subtitles I have problem with reCaptcha v2.
When I try to download for example:
https://dl.opensubtitles.org/en/downloa ... 3226300.gz

the server return:
HTTPError: HTTP Error 429: Unknown HTTP Status

add redirect me to:
http://www.opensubtitles.org/en/captcha ... 3226300.gz
and show reCaptcha v2 checkbox.

I understand why you protect opensubtitles.org with reCaptcha v2 and I am not requesting to disable it , but with currect setting of the reCaptcha v2 my application is not able to handle it.
I asked you in this thread
https://forum.opensubtitles.org/viewtop ... &start=180
to provide possibility to solve reCaptcha v2 without javascript. So, my application will be able to show reCaptcha v2 task to the end user for solving it.

Could you please check this?

Thank you,
SamSamSam

Any answer please?

There is some hole in the re-captcha v2 protection on this site, so I can use it to workaroud these problems.
But I don't want to do this, because I have respect for opensubtitles.org idea. I hope that you can take a look on the problem with reCaptcha v2 and change it settings.

429 http code is meant "too many requests", so you have to calm down.

Your IP can be in captcha mode, so in private message you can send me what are you doing exactly, send me urls where are you getting captcha and also your IP, so I can check

The problem with REST is that you are unauthenticated.

For sure I did not made to many requests.

Total numbers of downloaded subtitles files in this month are less than 30.

Your IP can be in captcha mode, so in private message you can send me what are you doing exactly, send me urls where are you getting captcha and also your IP, so I can check

I am not doing anything special. I already wrote when I got reCaptcha v2: when I try download subtitles from link returned via REST API.

The problem is not me. I can simple work around this problem. You will check my IP and remove it from reCaptcha database, but this is not what I am asking. I am a developer. I know that many users have such problems I get report form them.
So, I am not asking about solution for me, but general solution to give possibility to solve reCaptcha without javascript.
.
It can be done from reCaptcha configuration.

Please read reCaptcha documentation:
https://developers.google.com/recaptcha ... pt-enabled

Here you have a quote:

Does reCAPTCHA support users that don't have JavaScript enabled?

reCAPTCHA can only provide the optimal experience in terms of security and usability with JavaScript enabled. However, if supporting users who have disabled JavaScript is important for your site, you can enable the alternative challenge with the following steps. Navigate to the admin console and move the security preference slider to "easiest for users". Keep in mind that with this setting reCAPTCHA won't be able to use all of its security features.

My plugin is able to handle reCaptcha task in fallback mode and present reCaptcha task to end user to select valid pictures, but the reCaptcha widget must be configured to allow fallback mode.