Recs/V2/Similar

Jump to: navigation, search

Similar Version 2.0

Returns similar items in order of similarity and popularity.

Syntax

endpoint/similar? nameid=nameid
albumid=albumid
amgvideoid=amgvideoid
cosmoprogramid=cosmoprogramid 		&apikey=apikey&sig=sig& entitytype=entitytype [&format=format] [&country=country] [&language=language] [&size=size]

Request Example 1

Request a list of musicians similar to The Doors.
http://api.rovicorp.com/recs/v2/music/similar?apikey=apikey&sig=sig&entitytype=artist&
nameid=MN0000114342

Request Example 2

Request the ten most similar albums to Michael Jackson's Thriller.
http://api.rovicorp.com/recs/v2/music/similar?apikey=apikey&sig=sig&entitytype=album&
albumid=MW0000056882&size=10

Request Example 3

Request the 10 most similar movies and television series to the movie When Harry Met Sally.
http://api.rovicorp.com/recs/v2/amgvideo/similar?apikey=apikey&sig=sig&entitytype=movie&
entitytype=tvseries&amgvideoid=V++++54134&size=10

Request Example 4

Request a list of television series similar to House in an XML response.
http://api.rovicorp.com/recs/v2/video/similar?apikey=apikey&sig=sig&entitytype=tvseries&
cosmoprogramid=4180581&format=xml

Request Parameters

♫  Music-related requests      日  Movie-related requests      ⊑⊒  TV-related requests

ParameterRequiredDescription
apikey Yes Access code that authorizes your request for data from Rovi.
endpoint Yes Database to search.
To search in . . .Specify this endpoint.
musicmusic ♫
movies and TV series (our DVD database)amgvideo 日
television (our international TV schedule database)video ⊑⊒
entitytype Yes Type of content.
In this endpoint . . . To find . . .Specify entitytype.   (And ID.)
music ♫albumsalbumalbumid
people in musicartistnameid
amgvideo 日moviesmovieamgvideoid
TV seriestvseriesamgvideoid
video ⊑⊒moviesmoviecosmoprogramid
TV seriestvseriescosmoprogramid
A request can return data for only one entity type except for the combination of movie and tvseries. To do that, specify two entitytype parameters like this: entitytype=tvseries&entitytype=movie. The top results may come from just one of the entity types: order of results is determined by relevance and is not deliberately balanced across the searched entity types.
sig Yes A calculated authorization code. To perform the calculation, execute the MD5 function on the concatenation of the following three strings:
  • Your API key.
  • The secret key you received with your API key.
  • The Unix time. Unix time is a timestamp supported in most development environments, and is generally defined as the number of seconds since January 1, 1970 00:00:00 GMT.

Perform the calculation at the time of each request to be sure it's within a five-minute window of the server time. If you're testing the call in a browser, use our online signature generator to perform the calculation.

albumid Conditional Rovi Music ID for an album, consisting of the prefix MW followed by a ten-digit number. For a request with an album ID, specify an endpoint of music and an entitytype of album like this: music/similar?entitytype=album&albumid=MW0000056882. You can grab album IDs from responses to the following requests:

Condition: The request must contain just one of these parameters:

  • nameid
  • albumid
  • trackid
  • amgvideoid
  • cosmoprogramid
amgvideoid Conditional All Media Guide (AMG) database ID for a movie or TV series, consisting of a ten-character string that starts with V and is followed by 9 digits with leading spaces. For a request with an amgvideo ID, specify an endpoint of amgvideo and an entitytype of movie or tvseries, like this: amgvideo/similar?entitytype=tvseries&amgvideoid=V+++295550. Your application can grab amgvideo IDs from responses to the following requests:

Condition: The request must contain just one of these parameters:

  • nameid
  • albumid
  • trackid
  • amgvideoid
  • cosmoprogramid
cosmoprogramid Conditional Cosmo database ID for a movie or television series. For a request with a Cosmo ID, specify an endpoint of video and an entitytype of movie or tvseries, like this: video/similar?entitytype=tvseries&cosmoprogramid=3899277. You can get Cosmo IDs with Search requests on a video endpoint. Cosmo is a database of television information.

Condition: The request must contain just one of these parameters:

  • nameid
  • albumid
  • trackid
  • amgvideoid
  • cosmoprogramid
nameid Conditional Rovi Music ID for a person or group, consisting of the prefix MN followed by a ten-digit number. For a request with a name ID, specify an endpoint of music and an entitytype of artist, like this: music/similar?entitytype=artist&nameid=MN0000114342. Your application can grab name IDs from responses to Search and from Info, Credits, Tracks, and Recommendations requests. For a complete list of requests that return name IDs, click here.

Condition: The request must contain just one of these parameters:

  • nameid
  • albumid
  • trackid
  • amgvideoid
  • cosmoprogramid
country No Country of the language of the response. The current release of the API supports only US.
format No Format of the returned data: json or xml. The default is JSON.
language No Language of the response data. This request supports only en (English).
size No The number of items you want to be returned. The default is 20.

Response

Response Header

ResponseTypeDescription
controlSet ControlSet The HTTP response status.
id String Server transaction ID for the response.

Response for Similar Version 2.0

ResponseTypeDescription
results result [ ] Information about items that are similar to the items specified in the request, listed in order of similarity and popularity.

Response Example 1

The most similar movie to Avatar. Requested with http://api.rovicorp.com/recs/v2/amgvideo/similar?
apikey=apikey&sig=sig&entitytype=movie&amgvideoid=V+++352199&size=1.
{
   "similarResponse":{
      "id":"tul1cpgssrapp1:gwy:19o8t",
      "controlSet":{
         "status":"ok",
         "code":200,
         "messages":[
            ""
         ]
      },
      "results":[
         {
            "type":"movie",
            "relevance":[
               {
                  "code":"Score",
                  "name":5.9
               }
            ],
            "provider":"amgvideo",
            "id":"V 423766",
            "messages":null,
            "movie":{
               "ids":"",
               "title":"District 9",
               "releaseYear":2009,
               "rating":8,
               "duration":112,
               "directors":[
                  {
                     "id":"P484717",
                     "name":"Neill Blomkamp"
                  }
               ],
               "countries":[
                  "USA"
               ],
               "mpaa":"R",
               "flags":[
                  "Graphic Violence",
                  "Profanity",
                  "Gore"
               ],
               "genres":[
                  {
                     "id":"D 652",
                     "name":"Science Fiction",
                     "weight":5
                  }
               ],
               "attributes":null,
               "cast":null,
               "castUri":"http://api.rovicorp.com/v1/movie/cast?format=xml&apikey=4p1k3y&movieid=V+++423766",
               "crew":null,
               "crewUri":"http://api.rovicorp.com/v1/movie/crew?format=xml&apikey=4p1k3y&movieid=V+++423766",
               "images":null,
               "imagesUri":"http://api.rovicorp.com/v1/movie/images?format=xml&apikey=4p1k3y&movieid=V+++423766",
               "moods":null,
               "moodsUri":"http://api.rovicorp.com/v1/movie/moods?format=xml&apikey=4p1k3y&movieid=V+++423766",
               "keywords":null,
               "keywordsUri":"http://api.rovicorp.com/v1/movie/keywords?format=xml&apikey=4p1k3y&movieid=V+++423766",
               "related":null,
               "relatedUri":null,
               "releases":null,
               "releasesUri":"http://api.rovicorp.com/v1/movie/releases?format=xml&apikey=4p1k3y&movieid=V+++423766",
               "review":null,
               "reviewUri":"http://api.rovicorp.com/v1/movie/review?format=xml&apikey=4p1k3y&movieid=V+++423766",
               "similar":null,
               "similarUri":"http://api.rovicorp.com/v1/movie/similar?format=xml&apikey=4p1k3y&movieid=V+++423766",
               "synopsis":null,
               "synopsisUri":"http://api.rovicorp.com/v1/movie/synopsis?format=xml&apikey=4p1k3y&movieid=V+++423766",
               "themes":null,
               "themesUri":"http://api.rovicorp.com/v1/movie/themes?format=xml&apikey=4p1k3y&movieid=V+++423766",
               "tones":null,
               "tonesUri":"http://api.rovicorp.com/v1/movie/tones?format=xml&apikey=4p1k3y&movieid=V+++423766",
               "types":null,
               "typesUri":"http://api.rovicorp.com/v1/movie/types?format=xml&apikey=4p1k3y&movieid=V+++423766",
               "videos":null,
               "videosUri":"http://api.rovicorp.com/v1/movie/videos?format=xml&apikey=4p1k3y&movieid=V+++423766",
               "studio":"",
               "producedBy":[
                  "WingNut Films"
               ],
               "releasedBy":[
                  "QED International",
                  "TriStar Pictures"
               ],
               "distributor":null
            }
         }
      ]
   }
}

Response Example 2

The most similar album to Michael Jackson's Thriller. Requested with http://api.rovicorp.com/recs/v2/music/
similar?apikey=apikey&sig=sig&entitytype=album&albumid=MW0000056882&size=1&format=xml.
<similarResponse xmlns:wsp="http://schemas.datacontract.org/2004/07/Rovi.Cps.Framework.Common.Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:meta="com.rovicorp.metadataservice" xmlns:snr="com.rovicorp.snrservice" xmlns="com.rovicorp.metadataservice" id="tul1cpgpsrapp3:gwy:10yv3">
  <controlSet>
    <status>ok</status>
    <code>200</code>
    <messages/>
  </controlSet>
  <results>
    <result>
      <type>album</type>
      <relevance>
        <code>Score</code>
        <value>5.8</value>
      </relevance>
      <id>MW0000197303</id>
      <messages i:nil="true"/>
      <album>
        <ids>
          <albumId>MW0000197303</albumId>
          <amgClassicalId i:nil="true"/>
          <amgPopId>R 10188</amgPopId>
        </ids>
        <title>Street Songs</title>
        <primaryArtists>
          <AlbumArtist>
            <id>MN0000366164</id>
            <name>Rick James</name>
          </AlbumArtist>
        </primaryArtists>
        <guestArtists>
          <AlbumArtist>
            <id>MN0000647670</id>
            <name>Gerald Albright</name>
          </AlbumArtist>
          <AlbumArtist>
            <id>MN0000018258</id>
            <name>Teena Marie</name>
          </AlbumArtist>
          <AlbumArtist>
            <id>MN0000569685</id>
            <name>The Temptations</name>
          </AlbumArtist>
          <AlbumArtist>
            <id>MN0000314050</id>
            <name>Narada Michael Walden</name>
          </AlbumArtist>
          <AlbumArtist>
            <id>MN0000622805</id>
            <name>Stevie Wonder</name>
          </AlbumArtist>
        </guestArtists>
        <flags xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
          <a:string>Digitally Remastered</a:string>
        </flags>
        <duration>2086</duration>
        <originalReleaseDate>1981-??-??</originalReleaseDate>
        <rating>8</rating>
        <isPick>false</isPick>
        <genres>
          <Genre>
            <id>MA0000002809</id>
            <name>R&amp;B</name>
            <weight>10</weight>
          </Genre>
        </genres>
        <headlineReview>
          <text>This 1981 release was the crossover breakthrough that earned him pop stardom.</text>
          <author>Jim Allen</author>
        </headlineReview>
        <classicalReview i:nil="true"/>
        <classicalReviewUri i:nil="true"/>
        <credits i:nil="true"/>
        <creditsUri>http://api.rovicorp.com/v1/album/credits?format=xml&amp;apikey=4p1k3y&amp;albumid=MW0000197303</creditsUri>
        <images i:nil="true"/>
        <imagesUri>http://api.rovicorp.com/v1/album/images?format=xml&amp;apikey=4p1k3y&amp;albumid=MW0000197303</imagesUri>
        <moods i:nil="true"/>
        <moodsUri>http://api.rovicorp.com/v1/album/moods?format=xml&amp;apikey=4p1k3y&amp;albumid=MW0000197303</moodsUri>
        <primaryReview i:nil="true"/>
        <primaryReviewUri>http://api.rovicorp.com/v1/album/primaryReview?format=xml&amp;apikey=4p1k3y&amp;albumid=MW0000197303</primaryReviewUri>
        <releases i:nil="true"/>
        <releasesUri>http://api.rovicorp.com/v1/album/releases?format=xml&amp;apikey=4p1k3y&amp;albumid=MW0000197303</releasesUri>
        <similar i:nil="true"/>
        <similarUri>http://api.rovicorp.com/v1/album/similar?format=xml&amp;apikey=4p1k3y&amp;albumid=MW0000197303</similarUri>
        <styles i:nil="true"/>
        <stylesUri>http://api.rovicorp.com/v1/album/styles?format=xml&amp;apikey=4p1k3y&amp;albumid=MW0000197303</stylesUri>
        <themes i:nil="true"/>
        <themesUri>http://api.rovicorp.com/v1/album/themes?format=xml&amp;apikey=4p1k3y&amp;albumid=MW0000197303</themesUri>
        <tracks i:nil="true"/>
        <tracksUri>http://api.rovicorp.com/v1/album/tracks?format=xml&amp;apikey=4p1k3y&amp;albumid=MW0000197303</tracksUri>
      </album>
    </result>
  </results>
</similarResponse>

Error Codes

CodeDescription
400 Incorrect or invalid request. The reason is shown in the Message object in ControlSet.
502 No results found. The Message object in ControlSet returns the following:
  {
      "code": "Empty Result",
      "name": "No results available for this request"
  }

See Also

↑ Top

Retrieved from "http://prod-doc.rovicorp.com/mashery/index.php/Recs/V2/Similar"
Personal tools