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?
Code: Select all
https://rest.opensubtitles.org/search/episode-20/imdbid-4145054/moviebytesize-750005572/moviehash-319b23c54e9cf314/season-2/sublanguageid-eng
Code: Select all
episode (number)
imdbid (always format it as sprintf("%07d", $imdb) - when using imdb you can add /tags-hdtv for example.
moviebytesize (number)
moviehash (should be always 16 character, must be together with moviebytesize)
query (use url_encode, make sure " " is converted to "%20")
season (number)
sublanguageid (if ommited, all languages are returned)
tag (use url_encode, make sure " " is converted to "%20")
Code: Select all
curl -A 'TemporaryUserAgent' https://rest.opensubtitles.org/search/moviebytesize-750005572/moviehash-319b23c54e9cf314
curl -A 'TemporaryUserAgent' https://rest.opensubtitles.org/search/episode-20/imdbid-4145054/moviebytesize-750005572/moviehash-319b23c54e9cf314/season-2/sublanguageid-eng
curl -A 'TemporaryUserAgent' https://rest.opensubtitles.org/search/episode-11/imdbid-4145054/season-1/tags-web-dl
curl -A 'TemporaryUserAgent' https://rest.opensubtitles.org/search/query-matrix%20reloaded/sublanguageid-eng
curl -A 'TemporaryUserAgent' https://rest.opensubtitles.org/search/episode-8/sublanguageid-eng/tag-heroess01e08
Code: Select all
curl --header "X-User-Agent: TemporaryUserAgent" https://rest.opensubtitles.org/search/query-matrix%20reloaded/sublanguageid-cze
INVALID URLs:
Code: Select all
# duplicate parameters are not permitted
https://rest.opensubtitles.org/search/imdbid-4145054/imdbid-1234567
# duplicate values per parameter are not permitted
https://rest.opensubtitles.org/search/imdbid-4145054/sublanguageid-eng,cze
Always check for 200 response http code.
Example:
Code: Select all
# https://rest.opensubtitles.org/search/episode-1/imdbid-4145054/season-1/sublanguageid-cze
< HTTP/2 200
< date: Mon, 26 Mar 2018 08:48:54 GMT
< content-type: application/json
< set-cookie: __cfduid=debccacb67b21029477d3d105bd3943131522054134; expires=Tue, 26-Mar-19 08:48:54 GMT; path=/; domain=.opensubtitles.org; HttpOnly
< cache-control: public, max-age=43200
< last-modified: Mon, 26 Mar 2018 10:47:00 +0200
< access-control-allow-origin: *
< access-control-allow-headers: ETag, X-RateLimit-Remaining, Content-Type, Last-Modified
< x-robots-tag: noindex, nofollow
< vary: Accept-Encoding
< x-cache-backend: web3
< x-cache: MISS
< x-ratelimit-remaining: 40
< x-via: fw2.int.opensubtitles.org
< cf-cache-status: HIT
< expires: Mon, 26 Mar 2018 20:48:54 GMT
< expect-ct: max-age=604800, report-uri="https://report-uri.cloudflare.com/cdn-cgi/beacon/expect-ct"
< server: cloudflare
< cf-ray: 40185c628ecb6f7e-SIN
[{"MatchedBy":"imdbid","IDSubMovieFile":"0","MovieHash":"0","MovieByteSize":"0","MovieTimeMS":"0","IDSubtitleFile":"1955043364","SubFileName":"Shadowhunters.S01E01.HDTV.x264-KILLERS.srt","SubActualCD":"1","SubSize":"42803","SubHash":"66fea5461f173f689c3675c372cd055a","SubLastTS":"00:38:57","SubTSGroup":"1","IDSubtitle":"6461000","UserID":"0","SubLanguageID":"cze","SubFormat":"srt","SubSumCD":"1","SubAuthorComment":"","SubAddDate":"2016-01-13 23:19:41","SubBad":"0","SubRating":"0.0","SubSumVotes":"0","SubDownloadsCnt":"1332","MovieReleaseName":" Shadowhunters.S01E01.HDTV.x264-KILLERS","MovieFPS":"0.000","IDMovie":"406174","IDMovieImdb":"4601794","MovieName":"\"Shadowhunters: The Mortal Instruments\" The Mortal Cup","MovieNameEng":null,"MovieYear":"2016","MovieImdbRating":"7.6","SubFeatured":"0","UserNickName":"","SubTranslator":"","ISO639":"cs","LanguageName":"Czech","SubComments":"0","SubHearingImpaired":"0","UserRank":"","SeriesSeason":"1","SeriesEpisode":"1","MovieKind":"episode","SubHD":"0","SeriesIMDBParent":"4145054","SubEncoding":"UTF-8","SubAutoTranslation":"0","SubForeignPartsOnly":"0","SubFromTrusted":"0","SubTSGroupHash":"a5985421faabcab605e61243794a4d7f","SubDownloadLink":"https:\/\/dl.opensubtitles.org\/en\/download\/src-api\/vrf-19a20c51\/filead\/1955043364.gz","ZipDownloadLink":"https:\/\/dl.opensubtitles.org\/en\/download\/src-api\/vrf-f52d0baa\/subad\/6461000","SubtitlesLink":"http:\/\/www.opensubtitles.org\/en\/subtitles\/6461000\/shadowhunters-the-mortal-instruments-the-mortal-cup-cs","QueryNumber":"0","QueryParameters":{"episode":1,"season":1,"imdbid":"4145054","sublanguageid":"cze"},"Score":10.01332},{"MatchedBy":"imdbid","IDSubMovieFile":"0","MovieHash":"0","MovieByteSize":"0","MovieTimeMS":"0","IDSubtitleFile":"1955231797","SubFileName":"Shadowhunters S01E02 The Descent Into Hell Isn't Easy.srt","SubActualCD":"1","SubSize":"51130","SubHash":"5ec1754f14ed36e087a5c799815fadc9","SubLastTS":"00:40:41","SubTSGroup":"3","IDSubtitle":"6651521","UserID":"0","SubLanguageID":"cze","SubFormat":"srt","SubSumCD":"1","SubAuthorComment":"","SubAddDate":"2016-06-08 15:54:26","SubBad":"0","SubRating":"0.0","SubSumVotes":"0","SubDownloadsCnt":"170","MovieReleaseName":" Shadowhunters S01E02 The Descent Into Hell Isn't Easy","MovieFPS":"25.000","IDMovie":"406174","IDMovieImdb":"4601794","MovieName":"\"Shadowhunters: The Mortal Instruments\" The Mortal Cup","MovieNameEng":null,"MovieYear":"2016","MovieImdbRating":"7.6","SubFeatured":"0","UserNickName":"","SubTranslator":"","ISO639":"cs","LanguageName":"Czech","SubComments":"0","SubHearingImpaired":"0","UserRank":"","SeriesSeason":"1","SeriesEpisode":"1","MovieKind":"episode","SubHD":"0","SeriesIMDBParent":"4145054","SubEncoding":"CP1250","SubAutoTranslation":"0","SubForeignPartsOnly":"0","SubFromTrusted":"0","SubTSGroupHash":"a201acec74b8fdf5f64130bda9a7c5c7","SubDownloadLink":"https:\/\/dl.opensubtitles.org\/en\/download\/src-api\/vrf-19b60c5a\/filead\/1955231797.gz","ZipDownloadLink":"https:\/\/dl.opensubtitles.org\/en\/download\/src-api\/vrf-f5480bb3\/subad\/6651521","SubtitlesLink":"http:\/\/www.opensubtitles.org\/en\/subtitles\/6651521\/shadowhunters-the-mortal-instruments-the-mortal-cup-cs","QueryNumber":"0","QueryParameters":{"episode":1,"season":1,"imdbid":"4145054","sublanguageid":"cze"},"Score":10.0017},{"MatchedBy":"imdbid","IDSubMovieFile":"0","MovieHash":"0","MovieByteSize":"0","MovieTimeMS":"0","IDSubtitleFile":"1955209010","SubFileName":"Shadowhunters - 01x01 - The Mortal Cup (Pilot).KILLERS.English.HI.C.orig.Addic7ed.com.srt","SubActualCD":"1","SubSize":"41037","SubHash":"b67051a0013745caf50c0706c2a954ae","SubLastTS":"00:38:58","SubTSGroup":"1","IDSubtitle":"6628618","UserID":"0","SubLanguageID":"cze","SubFormat":"srt","SubSumCD":"1","SubAuthorComment":"","SubAddDate":"2016-05-17 13:33:06","SubBad":"0","SubRating":"0.0","SubSumVotes":"0","SubDownloadsCnt":"79","MovieReleaseName":" Shadowhunters - 01x01 - The Mortal Cup (Pilot).KILLERS.English.HI.C.orig.Addic7ed.com","MovieFPS":"23.976","IDMovie":"406174","IDMovieImdb":"4601794","MovieName":"\"Shadowhunters: The Mortal Instruments\" The Mortal Cup","MovieNameEng":"","MovieYear":"2016","MovieImdbRating":"7.6","SubFeatured":"0","UserNickName":"","SubTranslator":"","ISO639":"cs","LanguageName":"Czech","SubComments":"0","SubHearingImpaired":"0","UserRank":"","SeriesSeason":"1","SeriesEpisode":"1","MovieKind":"episode","SubHD":"0","SeriesIMDBParent":"4145054","SubEncoding":"CP1250","SubAutoTranslation":"0","SubForeignPartsOnly":"0","SubFromTrusted":"0","SubTSGroupHash":"a5985421faabcab605e61243794a4d7f","SubDownloadLink":"https:\/\/dl.opensubtitles.org\/en\/download\/src-api\/vrf-199b0c49\/filead\/1955209010.gz","ZipDownloadLink":"https:\/\/dl.opensubtitles.org\/en\/download\/src-api\/vrf-f55d0bbe\/subad\/6628618","SubtitlesLink":"http:\/\/www.opensubtitles.org\/en\/subtitles\/6628618\/shadowhunters-the-mortal-instruments-the-mortal-cup-cs","QueryNumber":"0","QueryParameters":{"episode":1,"season":1,"imdbid":"4145054","sublanguageid":"cze"},"Score":10.00079},{"MatchedBy":"imdbid","IDSubMovieFile":"0","MovieHash":"0","MovieByteSize":"0","MovieTimeMS":"0","IDSubtitleFile":"1955105830","SubFileName":"Shadowhunters.S01E01.1080p.WEB-DL.DD5.1.H264-RARBG.srt","SubActualCD":"1","SubSize":"41135","SubHash":"2a012782be0d93f31c4053669d6c2f76","SubLastTS":"00:39:05","SubTSGroup":"5","IDSubtitle":"6524935","UserID":"0","SubLanguageID":"cze","SubFormat":"srt","SubSumCD":"1","SubAuthorComment":"","SubAddDate":"2016-02-25 21:36:46","SubBad":"0","SubRating":"0.0","SubSumVotes":"0","SubDownloadsCnt":"74","MovieReleaseName":" Shadowhunters.S01E01.1080p.WEB-DL.DD5.1.H264-RARBG","MovieFPS":"23.976","IDMovie":"406174","IDMovieImdb":"4601794","MovieName":"\"Shadowhunters: The Mortal Instruments\" The Mortal Cup","MovieNameEng":"","MovieYear":"2016","MovieImdbRating":"7.6","SubFeatured":"0","UserNickName":"","SubTranslator":"","ISO639":"cs","LanguageName":"Czech","SubComments":"0","SubHearingImpaired":"0","UserRank":"","SeriesSeason":"1","SeriesEpisode":"1","MovieKind":"episode","SubHD":"1","SeriesIMDBParent":"4145054","SubEncoding":"CP1250","SubAutoTranslation":"0","SubForeignPartsOnly":"0","SubFromTrusted":"0","SubTSGroupHash":"ad6e0f888438099ed83c2d1a335588bd","SubDownloadLink":"https:\/\/dl.opensubtitles.org\/en\/download\/src-api\/vrf-19a10c4e\/filead\/1955105830.gz","ZipDownloadLink":"https:\/\/dl.opensubtitles.org\/en\/download\/src-api\/vrf-f5510bbb\/subad\/6524935","SubtitlesLink":"http:\/\/www.opensubtitles.org\/en\/subtitles\/6524935\/shadowhunters-the-mortal-instruments-the-mortal-cup-cs","QueryNumber":"0","QueryParameters":{"episode":1,"season":1,"imdbid":"4145054","sublanguageid":"cze"},"Score":10.00074}]
More REST methods to play with:
Code: Select all
curl -A 'TemporaryUserAgent' http://rest.opensubtitles.org/suggest/query-a/sublanguageid-eng
curl -A 'TemporaryUserAgent' http://rest.opensubtitles.org/getsublanguages/language-en
curl -vvv -d 'username=your_username&password=your_password' -X POST -A 'TemporaryUserAgent v1.2' https://rest.opensubtitles.org/auth
curl -vvv --user username:password -A 'TemporaryUserAgent v1.2' https://rest.opensubtitles.org/auth
Code: Select all
http://dl.opensubtitles.org/en/download/src-api/vrf-19d50c5e/sid-{YOUR_SID_HERE}/filead/1951976249.gz