[[PageOutline(3-4, Sections)]]

== !SearchSubtitles == 


=== Intro ===

  search for subtitle files matching your videos using either video file hashes or IMDb IDs.


=== Description ===

  '''struct !SearchSubtitles(string $token, array(struct('sublanguageid' => string $sublanguageid, 'moviehash' => string $moviehash, 'moviebytesize' => int $moviesize, 'imdbid' => string $imdbid ), struct(...)))'''

  This function can be used to search for subtitle files.
  There are two ways to call it:
  
    1. using video file hashes (more at once allowed):
      Search the database using video file hashes to get exact matches for your video files.
    
    2. using IMDb IDs:
      If method 1 returns no subtitle files, you can use this method to search for subtitle files matching given ''imdbid''.

      You'll most probably have to synchronize the subtitles yourself or try more to find a match. If you find one, please, contribute by uploading them using [wiki:XmlRpcUploadSubtitles UploadSubtitles] method.
     
      When this method is used you don't have to specify ''moviehash'' and ''moviebytesize''.
     
      Some fields (IDSubMovieFile, !MovieHash, !MovieByteSize, MovieTimeMS) are missing in output when using this method.
      
  If ''sublanguageid'' is empty or contains the string 'all' - search is performed for all languages.
  
  Also remember you can not combine ''imdbid'' and ''moviehash'' searches in one call.


=== Parameters ===

  First parameter is the session ''token'', second is the list of video files using this structure: 
{{{
  array(  <--- array/list of video files
    struct(   <--- information about one video file
      (string) [sublanguageid],
      (string) [moviehash],
      (double) [moviebytesize],
      (string) [imdbid]
    ), struct( ), ...
  }
}}}

  ''token'' (required)::
    token string identifying user's session, taken from [wiki:XmlRpcLogIn LogIn] result structure.
  ''sublanguageid''::
    list of language ISO639-3 language codes to search for, divided by ',' (e.g. 'cze,eng,slo'),
    see [wiki:XmlRpcGetSubLanguages GetSubLanguages] function for a list of available languages
  ''moviehash''::
    video file hash as calculated by one of the implementation functions as seen on [wiki:HashSourceCodes Hash Source Codes] page
  ''moviebytesize''::
    size of video file in bytes
  ''imdbid'' (optional)::
    [http://www.imdb.com IMDb] ID of movie this video is part of, belongs to.


=== Return Values ===

  Output is returned in this structure: 
{{{
  struct(
    array(
      struct( subfile ), struct( subfile ), ...
    ) [data],
    (double) [seconds]
  )
}}}

  and contains these elements:
    ''data''::
      array of found subtitle file matches, when no matches are found ''data'' is empty.
      ''subfile''::
        structure that holds the subtitle file information, see [wiki:XmlRpcStruSubFile subtitle file structure]
    ''seconds''::
      time taken to execute this command on server


=== Implementations ===

  There are currently no available sample implementations.


=== Changelog ===

  Version 1: created this function
  
  Version 2: added search by IMDb ID


=== Examples ===


==== Input ====

{{{
#!xml
<methodCall>
 <methodName>SearchSubtitles</methodName>
 <params>
  <param>
   <value><string>5fdgt2e9qriblpbojnq0j46op1</string></value>
  </param>
  <param>
   <value>
    <array>
     <data>
      <value>
       <struct>
        <member>
         <name>sublanguageid</name>
         <value><string>cze,eng,ger,slo</string>
         </value>
        </member>
        <member>
         <name>moviehash</name>
         <value><string>7d9cd5def91c9432</string></value>
        </member>
        <member>
         <name>moviebytesize</name>
         <value><double>735934464</double></value>
        </member>
       </struct>
      </value>
     </data>
    </array>
   </value>
  </param>
 </params>
</methodCall>
}}}

  
==== Output ====

{{{
#!xml
<methodResponse>
 <params>
  <param>
   <value>
    <struct>
     <member>
      <name>data</name>
      <value>
       <array>
        <data>
         <value>
          <struct>
           <member>
            <name>IDSubMovieFile</name>
            <value><string>144635</string></value>
           </member>
           <member>
            <name>MovieHash</name>
            <value><string>7d9cd5def91c9432</string></value>
           </member>
           <member>
            <name>MovieByteSize</name>
            <value><string>735934464</string></value>
           </member>
           <member>
            <name>MovieTimeMS</name>
            <value><string>6631000</string></value>
           </member>
           <member>
            <name>IDSubtitleFile</name>
            <value><string>1951854837</string></value>
           </member>
           <member>
            <name>SubFileName</name>
            <value><string>nedivx-27dresses.en.HI.srt</string></value>
           </member>
           <member>
            <name>SubActualCD</name>
            <value><string>1</string></value>
           </member>
           <member>
            <name>SubSize</name>
            <value><string>149346</string></value>
           </member>
           <member>
            <name>SubHash</name>
            <value><string>d7fb67a524f86b83245a927d7b2d0b75</string></value>
           </member>
           <member>
            <name>IDSubtitle</name>
            <value><string>3272414</string></value>
           </member>
           <member>
            <name>UserID</name>
            <value><string>451347</string></value>
           </member>
           <member>
            <name>SubLanguageID</name>
            <value><string>eng</string></value>
           </member>
           <member>
            <name>SubFormat</name>
            <value><string>srt</string></value>
           </member>
           <member>
            <name>SubSumCD</name>
            <value><string>1</string></value>
           </member>
           <member>
            <name>SubAuthorComment</name>
            <value><string>Extracted from DVD. Hearing Impaired.</string></value>
           </member>
           <member>
            <name>SubAddDate</name>
            <value><string>2008-04-15 01:51:02</string></value>
           </member>
           <member>
            <name>SubBad</name>
            <value><string>0</string></value>
           </member>
           <member>
            <name>SubRating</name>
            <value><string>10.0</string></value>
           </member>
           <member>
            <name>SubDownloadsCnt</name>
            <value><string>1013</string></value>
           </member>
           <member>
            <name>MovieReleaseName</name>
            <value><string>27.Dresses.DVDRip.XviD-NeDiVx (Hearing Impaired)</string></value>
           </member>
           <member>
            <name>IDMovie</name>
            <value><string>30833</string></value>
           </member>
           <member>
            <name>IDMovieImdb</name>
            <value><string>988595</string></value>
           </member>
           <member>
            <name>MovieName</name>
            <value><string>27 Dresses</string></value>
           </member>
           <member>
            <name>MovieNameEng</name>
            <value><string/></value>
           </member>
           <member>
            <name>MovieYear</name>
            <value><string>2008</string></value>
           </member>
           <member>
            <name>MovieImdbRating</name>
            <value><string>6.2</string></value>
           </member>
           <member>
            <name>UserNickName</name>
            <value><string>LeapinLar</string></value>
           </member>
           <member>
            <name>ISO639</name>
            <value><string>en</string></value>
           </member>
           <member>
            <name>LanguageName</name>
            <value><string>English</string></value>
           </member>
           <member>
            <name>SubDownloadLink</name>
            <value><string>http://www.opensubtitles.org/en/download/file/1951854837.gz</string></value>
           </member>
           <member>
            <name>ZipDownloadLink</name>
            <value><string>http://www.opensubtitles.org/en/download/sub/3272414</string></value>
           </member>
          </struct>
         </value>
         
         ... more subtitle file structures go here (if any) ...
         
        </data>
       </array>
      </value>
     </member>
     <member>
      <name>seconds</name>
      <value><double>0.02</double></value>
     </member>
    </struct>
   </value>
  </param>
 </params>
</methodResponse>
}}}


=== Notes ===

  * results are always grouped by !MovieHash, !MovieByteSize, SubLanguageID, IDSubMovieFile and sorted by seencount descending, maximum number of results is 250.
  * field '!MovieFrames' isn't being sent from the server. Make this field optional or just remove it.


=== See also ===

  * [wiki:XmlRpcDownloadSubtitles DownloadSubtitles]
  * [wiki:XmlRpcUploadSubtitles UploadSubtitles]
  

=== Comments ===

	add your comments, hints and suggestion here if you like ...


[Prev] [wiki:XmlRpcIntro Home] [Next]