Api.Search::About

Api.Search is a REST API reachable through HTTP GET requests.
Results are currently offered in two formats : JSON && XML.

With Api.Search you can search in All Titles, Movie Titles , Tv Titles , Movie Releases and Tv Episodes.
You will need an API key to use our api. Request Api Key.

Need help ? contact us : api AT subtitleseeker.com .


Api.Search::Parameters

Api is accessible && working with HTTP GET requests at :

http://api.subtitleseeker.com/search/
Parameter Value Notes
api_key [required] The Api key ,request Api Key
q [required] Text search term.
search_in [optional] Search category.
  • titles [default]
  • movie_titles
  • tv_titles
  • releases
  • tv_episodes
max_results [optional] Number of results returned :
  • 25 [default]
  • 50
  • 75
  • 100
return_type [optional] Returned format :
  • xml [default]
  • json
gzip [optional] Gzip compression On/Off :
  • ON [default]
  • OFF

Take a look at some examples , responses or errors


Api.Search::Responses

Every valid request will return these basic parameters.
Take a look at the errors codes to process invalid requests.

Name Type Description
got_error int (0=valid|1=invalid). Is this query valid ?
search_term string searchterm from q
search_in string search category from search_in
returned_items int total returned items
total_matches int total matches found on search term/category
html_search_url string html search url link.
items > item array Resultset for each match
page_generation_time int Page generation time in seconds

Item results with TITLE search category


Every valid request will return these items for : titles,movie_titles and tv_titles .

Name Type Description
title string title of the movie/tv show
aka string aka - alternative title
year int year of the movie/tv show
imdb int internet movie database ID ( Imdb.com )
title_url string short_url to subtitleseeker title page
total_subtitles int number of subtitles this title holds
title_type string Title category ( search_in )
title_type_int int Title category as integer
last_crawled string Last time this title has been crawled
last_crawled_date int last crawl time in date format
last_crawled_unix int last crawl time in unix format

Item results with RELEASES search category


Every valid request will return these items for : releases .

Name Type Description
release string release name.
release_url string Link to the release on subtitleseeker
release_id int release ID. ( Unique , use with api.get)
total_subtitles int number of subtitles this release holds
total_languages int number of languages this release holds
title string title of the movie
year int year of the movie
imdb int internet movie database ID ( Imdb.com )
title_url string short_url to subtitleseeker title page

Item results with TV_EPISODES search category


Every valid request will return these items for : tv_episodes .

Name Type Description
title string title of the Tv show
year int year of the tv show
imdb int internet movie database ID ( Imdb.com )
title_url string short_url to subtitleseeker title page
season int Season
episode int episode
episode_id int episode ID ( Unique , use with api.get)
episode_url string Link to episode on subtitleseeker
episode_title string title of the episode
episode_airdate int Airdate of the episode
total_subtitles int number of subtitles this episode holds

Api.Search::Errors

Error codes are returned with an invalid request.
When parameter got_error is returned as 1

We kept it very simple. Most wrongly inputted parameters will simply be reset to there default.
You are looking on a way to determine if your valid query returned any results ?
Then use returned_items or total_matches .

If you get a SP_ERROR , there is a problem on our end and we probably already got a message.
Send us an email anyway.

short msg
NO_API_KEY [api_key] Not set ! Get your api key at : api.subtitleseeker.com
API_KEY_INVALID [api_key] Api key does not seem to be valid. Wrong Key? Or Banned ? please contact api AT subtitleseeker.com
INVALID_SEARCHTERM [q] No search term or term is shorter then minimum lenght ( 3 characters ).
INVALID_MAX_RESULTS [max_results] invalid max_results . Options : 25,50,75,100
SP_ERRORS Backend Server errors. Either a server is down,timed out or there is a bug in the code , please let us know : api AT subtitleseeker.com

Api.Search::Examples

Example 1 : Basic


You want to search The Dark Knight in all titles :

URL XML :
http://api.subtitleseeker.com/search/?api_key=API_KEY&q=The+Dark+Knight
URL JSON:
http://api.subtitleseeker.com/search/?api_key=API_KEY&q=The+Dark+Knight&return_type=json


Example 2 : Title + Year


You want to search The Dark Knight AND you know the year :

URL XML :
http://api.subtitleseeker.com/search/?api_key=API_KEY&q=The+Dark+Knight+2008
URL JSON:
http://api.subtitleseeker.com/search/?api_key=API_KEY&q=The+Dark+Knight+2008&return_type=json


Example 3 : Movie Title


You want to search The Dark Knight AND you know it is a movie :

URL XML :
http://api.subtitleseeker.com/search/?api_key=API_KEY&q=The+Dark+Knight&search_in=movie_titles
URL JSON:
http://api.subtitleseeker.com/search/?api_key=API_KEY&q=The+Dark+Knight&search_in=movie_titles&return_type=json


Example 4 : Title + Only have release


You want to search The Dark Knight title , but you got only a scene release. :The.Dark.Knight.2008.720p.BluRay.DTS.x264-ESiR
No problem. We will fix the query and even sort directly on the year..

URL XML :
http://api.subtitleseeker.com/search/?api_key=API_KEY&q=The.Dark.Knight.2008.720p.BluRay.DTS.x264-ESiR
URL JSON:
http://api.subtitleseeker.com/search/?api_key=API_KEY&q=The.Dark.Knight.2008.720p.BluRay.DTS.x264-ESiR&return_type=json


Example 5 : Search Releases With Title


You want to search The Dark Knight Releases , with a movie title .

URL XML :
http://api.subtitleseeker.com/search/?api_key=API_KEY&q=The Dark Knight&search_in=releases
URL JSON:
http://api.subtitleseeker.com/search/?api_key=API_KEY&q=The Dark Knight&search_in=releases&return_type=json


Example 6 : Search Releases With Title+ Scenegroup


You want to find The.Dark.Knight.2008.DvDrip-aXXo Releases.
But you only have the title and group name
Title : The Dark Knight
GroupName :aXXo
No problem : TITLE -GROUPNAME
Note : Do not forget the DASH ( - ) .

URL XML :
http://api.subtitleseeker.com/search/?api_key=API_KEY&q=The.Dark.Knight.2008.DvDrip-aXXo&search_in=releases
URL JSON:
http://api.subtitleseeker.com/search/?api_key=API_KEY&q=The.Dark.Knight.2008.DvDrip-aXXo&search_in=releases&return_type=json


Example 7 : Search tv episodes


You want to find true blood episodes.

URL XML :
http://api.subtitleseeker.com/search/?api_key=API_KEY&q=True+Blood&search_in=tv_episodes
URL JSON:
http://api.subtitleseeker.com/search/?api_key=API_KEY&q=True+Blood&search_in=tv_episodes&return_type=json


Example 8 : Search tv episodes with a specific Season/Episode


You want to find true blood season 3.
Just use "True blood season 3" Or "True Blood s03 "

Want to specify an episode ?
Then use "True Blood Season 3 episode 2" Or "True Blood S03E02"

URL XML :
http://api.subtitleseeker.com/search/?api_key=API_KEY&q=True Blood s03&search_in=tv_episodes
URL JSON:
http://api.subtitleseeker.com/search/?api_key=API_KEY&q=True Blood s03&search_in=tv_episodes&return_type=json


Example 9 : Search tv episodes with a release


You want to find the season/episode link for True Blood season 4 episode 12
but you only got the release "True.Blood.S04E12.720p.HDTV.X264-DIMENSION"
No problem we will clean your query and rip the season/episode right out of the release.

URL XML :
http://api.subtitleseeker.com/search/?api_key=API_KEY&q=True.Blood.S04E12.720p.HDTV.X264-DIMENSION&search_in=tv_episodes
URL JSON:
http://api.subtitleseeker.com/search/?api_key=API_KEY&q=True.Blood.S04E12.720p.HDTV.X264-DIMENSION&search_in=tv_episodes&return_type=json


Just test our API with trial and error and figure out what is possible.
Enjoy!

Contact : api [AT] subtitleseeker.com