[NEW] REST search, JSON results
Posted: Mon Mar 26, 2018 10:52 am
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.
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