Recommendations-api/v2.1/similar

Jump to: navigation, search

Similar

Returns similar items in order of similarity.

Syntax

endpoint/similar? nameid=nameid
trackid=trackid
albumid=albumid
amgvideoid=amgvideoid
cosmoprogramid=cosmoprogramid 		&apikey=apikey&sig=sig& entitytype=entitytype [&clu=clu] [&start=start] [&end=end] [&rep=rep] [&filter=filter] [&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.1/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.1/music/similar?apikey=apikey&sig=sig&entitytype=album&
albumid=MW0000056882&size=10

Request Example 3

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

Request Example 4

Request ten movies or TV series that are similar to the series White Collar that are appearing on Time-Warner Cable in Beverly Hills during the New Year's weekend and show up to five rebroadcast times for each result.
http://api.rovicorp.com/recs/v2.1/video/similar?apikey=apikey&sig=sig&entitytype=movie&
entitytype=tvseries&cosmoprogramid=12100588&size=10&clu=360861&
start=20111230180000-0800&end=20120102220000-0800&rep=5

Request Example 5

Request a list of songs similar to David Bowie's Modern Love.
http://api.rovicorp.com/recs/v2.1/music/similar?apikey=apikey&sig=sig&entitytype=song&
trackid=MT0000045446

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 to look for.
For this endpoint . . . To find . . .Specify entitytype.   (And ID.)
music ♫songssongtrackid
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.

Cosmo is a database of television information. You can get Cosmo IDs from responses to the following requests:

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

  • nameid
  • albumid
  • trackid
  • amgvideoid
  • cosmoprogramid
nameid Conditional Rovi Name 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
trackid Conditional Rovi Music ID for a song, consisting of the prefix MT followed by a ten-digit number. For a request with a track ID, specify an endpoint of music and an entitytype of song, like this: music/similar?entitytype=song&trackid=MT0009472348.

Your application can grab track IDs from responses to the following requests:

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

  • nameid
  • albumid
  • trackid
  • amgvideoid
  • cosmoprogramid
clu No Service ID of a television service to match against. Service IDs for television services are available with calls to Services.

The broadcast time of each returned program is shown in an availabilities object. To return more than one broadcast time, specify the rep parameter.

Notes:

  • Requires an endpoint of video.
  • To check multiple television services, specify multiple parameters like this: clu=360861&clu=20494.
  • To limit the broadcast time window to less than the next two weeks, specify the start or end parameters, or both.
  • To return only programs in the broadcast time window, add filter=availability to the request.
  • Here are some Service IDs you can use for evaluation tests:
    • 20419 — Chicago Area Broadcast TV
    • 890504 — CanalSat in Paris, France
    • 68809 — Shaw Cable in Moose Jaw, Saskatchewan
    • 60795 — Time Warner Cable in Southern Manhattan
    • 360861 — Time Warner Cable in Beverly Hills, California
country No Country of the language of the response. The current release of the API supports only US.
end No If you specify the clu parameter, end specifies the end of the broadcast time window in one of the following formats:
  • UTC time: YYYYmmDDhhMMssZ. For example: 20120315140000Z for 2012-03-15 14:00:00 GMT.
  • Local time with a UTC offset: YYYYmmDDhhMMss + or - hhMM (positive or negative offset). For example, for the same time specified as US Pacific time: 20120315060000‑0800.

If not specified, the end time is two weeks after the time of the request.

filter No Field content that determines which results are returned. Like a WHERE clause in an SQL statement, this parameter selects only results with fields that meet your criteria.

This parameter requires an endpoint of  video.

Examples:

  • Specify filter=releaseyear>2009 to return only shows released in 2010 or later.
  • Specify filter=ratingid:3|ratingid:4|ratingid:5 to return movies rated G, PG, or PG13.

The selection operators include:

Operator    Meaning
:Is equal to.
!:Is not equal to.
<Is less than.
<:Is less than or equal to.
>Is greater than.
>:Is greater than or equal to.
|Or.

For the And operation, specify another filter parameter like this: filter=releaseyear>:2004&filter=releaseyear<2009.

The following shows which fields you can select for each video entity type. If you specify a filter that does not apply to an entity type, no data will be returned for that entity type.

For . . .You can filter on . . .Description
movie
  • availability
Returns only results that are found in the television service specified by the clu parameter. Specified without a value, like this: filter=availability.
  • ratingid
Includes only content that has a particular parental rating. See the IDs in the ratings table.
  • releaseyear
Filters content by release year.
tvseries
  • availability
Returns only content found by the clu parameter. Specified without a value, like this: filter=availability.
  • ratingid
Returns only content that has a particular parental rating. See the IDs in the ratings table.
format No Format of the returned data: json or xml. The default is XML.

Alternatively you can specify the response format in an HTTP Accept header with either of these Accept field content types:

  • application/xml
  • application/json

If you specify both, the format parameter overrides the Accept header.

language No Language of the response data. This request supports only en (English).
rep No If you specify the clu parameter, rep specifies the maximum number of broadcasts to be reported in the availabilities object. For example, to return up to five broadcasts during the time specified, specify rep=5. Default is 1.
size No The number of items you want to be returned. The default is 20.
start No If you specify the clu parameter, start specifies the start of the broadcast time window in one of the following formats:
  • UTC time: YYYYmmDDhhMMssZ. For example: 20120315140000Z for 2012-03-15 14:00:00 GMT.
  • Local time with a UTC offset: YYYYmmDDhhMMss + or - hhMM (positive or negative offset). For example, for the same time specified as US Pacific time: 20120315060000‑0800.

If not specified, the start time is the time of the request.

Response

Response Header

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

Response for Similar

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

Response Example 1

The most similar movie to Avatar.
Requested with http://api.rovicorp.com/recs/v2.1/amgvideo/similar?apikey=apikey&sig=sig&
entitytype=movie&amgvideoid=V+++352199&size=1&format=json.
{
   "similarResponse":{
      "meta:id":"tul1cpgpsrapp3:gwy:3r2li9",
      "controlSet":{
         "status":"ok",
         "code":200,
         "messages":null
      },
      "results":[
         {
            "type":"movie",
            "relevance":[
               {
                  "code":"Score",
                  "value":90.03087
               }
            ],
            "id":"V 491527",
            "messages":null,
            "movie":{
               "ids":{
                  "cosmoId":"14096633",
                  "movieId":"V 491527"
               },
               "title":"John Carter",
               "releaseYear":2012,
               "rating":3,
               "duration":118,
               "directors":[
                  {
                     "id":"P203257",
                     "name":"Andrew Stanton"
                  }
               ],
               "countries":[
                  "USA"
               ],
               "mpaa":"PG13",
               "flags":[
                  "Violence"
               ],
               "genres":[
                  {
                     "id":"D 652",
                     "name":"Science Fiction",
                     "weight":5
                  }
               ],
               "attributes":null,
               "cast":null,
               "castUri":"http://api.rovicorp.com/data/v1.1/movie/cast?format=json&apikey=4p1k3y&movieid=V+++491527",
               "crew":null,
               "crewUri":"http://api.rovicorp.com/data/v1.1/movie/crew?format=json&apikey=4p1k3y&movieid=V+++491527",
               "images":null,
               "imagesUri":"http://api.rovicorp.com/data/v1.1/movie/images?format=json&apikey=4p1k3y&movieid=V+++491527",
               "moods":null,
               "moodsUri":"http://api.rovicorp.com/data/v1.1/movie/moods?format=json&apikey=4p1k3y&movieid=V+++491527",
               "keywords":null,
               "keywordsUri":"http://api.rovicorp.com/data/v1.1/movie/keywords?format=json&apikey=4p1k3y&movieid=V+++491527",
               "related":null,
               "relatedUri":"http://api.rovicorp.com/data/v1.1/movie/related?format=json&apikey=4p1k3y&movieid=V+++491527",
               "releases":null,
               "releasesUri":"http://api.rovicorp.com/data/v1.1/movie/releases?format=json&apikey=4p1k3y&movieid=V+++491527",
               "review":null,
               "reviewUri":"http://api.rovicorp.com/data/v1.1/movie/review?format=json&apikey=4p1k3y&movieid=V+++491527",
               "similar":null,
               "similarUri":"http://api.rovicorp.com/data/v1.1/movie/similar?format=json&apikey=4p1k3y&movieid=V+++491527",
               "synopsis":null,
               "synopsisUri":"http://api.rovicorp.com/data/v1.1/movie/synopsis?format=json&apikey=4p1k3y&movieid=V+++491527",
               "themes":null,
               "themesUri":"http://api.rovicorp.com/data/v1.1/movie/themes?format=json&apikey=4p1k3y&movieid=V+++491527",
               "tones":null,
               "tonesUri":"http://api.rovicorp.com/data/v1.1/movie/tones?format=json&apikey=4p1k3y&movieid=V+++491527",
               "types":null,
               "typesUri":"http://api.rovicorp.com/data/v1.1/movie/types?format=json&apikey=4p1k3y&movieid=V+++491527",
               "videos":null,
               "videosUri":"http://api.rovicorp.com/data/v1.1/movie/videos?format=json&apikey=4p1k3y&movieid=V+++491527",
               "studio":"",
               "producedBy":null,
               "releasedBy":[
                  "Walt Disney Pictures"
               ],
               "distributor":null
            }
         }
      ]
   }
}

Response Example 2

The most similar album to Michael Jackson's Thriller.
Requested with http://api.rovicorp.com/recs/v2.1/music/similar?apikey=apikey&sig=sig&
entitytype=album&albumid=MW0000056882&format=xml&size=1.
<similarResponse xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="com.rovicorp.metadataservice" xmlns:meta="com.rovicorp.metadataservice" meta:id="tul1cpgpsrapp17:gwy:3p05b0">
  <controlSet>
    <status>ok</status>
    <code>200</code>
    <messages i:nil="true" />
  </controlSet>
  <results>
    <result>
      <type>album</type>
      <relevance>
        <code>Score</code>
        <value>85.59312</value>
      </relevance>
      <availabilties xmlns="com.rovicorp.snrservice" />
      <id>MW0000268192</id>
      <messages i:nil="true" />
      <album>
        <ids>
          <albumId>MW0000268192</albumId>
          <amgClassicalId i:nil="true" />
          <amgPopId>R 12203</amgPopId>
        </ids>
        <title>Madonna</title>
        <primaryArtists>
          <AlbumArtist>
            <id>MN0000237205</id>
            <name>Madonna</name>
          </AlbumArtist>
        </primaryArtists>
        <guestArtists>
          <AlbumArtist>
            <id>MN0000655346</id>
            <name>Gwen Guthrie</name>
          </AlbumArtist>
          <AlbumArtist>
            <id>MN0000024932</id>
            <name>Paul Pesco</name>
          </AlbumArtist>
          <AlbumArtist>
            <id>MN0000456085</id>
            <name>Norma Jean Wright</name>
          </AlbumArtist>
        </guestArtists>
        <flags>
          <a:string>Digitally Remastered</a:string>
          <a:string>Studio Recording</a:string>
        </flags>
        <duration>2447</duration>
        <originalReleaseDate>1983-??-??</originalReleaseDate>
        <rating>9</rating>
        <isPick>false</isPick>
        <genres>
          <Genre>
            <id>MA0000002613</id>
            <name>Pop/Rock</name>
            <weight>10</weight>
          </Genre>
          <Genre>
            <id>MA0000002572</id>
            <name>Electronic</name>
            <weight>5</weight>
          </Genre>
        </genres>
        <headlineReview>
          <text>Madonna's debut, a whipsmart classic of club gone commercial.</text>
          <author i:nil="true" />
        </headlineReview>
        <classicalReview i:nil="true" />
        <classicalReviewUri i:nil="true" />
        <credits i:nil="true" />
        <creditsUri>http://api.rovicorp.com/data/v1.1/album/credits?format=xml&apikey=4p1k3y&albumid=MW0000268192</creditsUri>
        <moods i:nil="true" />
        <moodsUri>http://api.rovicorp.com/data/v1.1/album/moods?format=xml&apikey=4p1k3y&albumid=MW0000268192</moodsUri>
        <primaryReview i:nil="true" />
        <primaryReviewUri>http://api.rovicorp.com/data/v1.1/album/primaryReview?format=xml&apikey=4p1k3y&albumid=MW0000268192</primaryReviewUri>
        <releases i:nil="true" />
        <releasesUri>http://api.rovicorp.com/data/v1.1/album/releases?format=xml&apikey=4p1k3y&albumid=MW0000268192</releasesUri>
        <similar i:nil="true" />
        <similarUri>http://api.rovicorp.com/data/v1.1/album/similar?format=xml&apikey=4p1k3y&albumid=MW0000268192</similarUri>
        <styles i:nil="true" />
        <stylesUri>http://api.rovicorp.com/data/v1.1/album/styles?format=xml&apikey=4p1k3y&albumid=MW0000268192</stylesUri>
        <themes i:nil="true" />
        <themesUri>http://api.rovicorp.com/data/v1.1/album/themes?format=xml&apikey=4p1k3y&albumid=MW0000268192</themesUri>
        <tracks i:nil="true" />
        <tracksUri>http://api.rovicorp.com/data/v1.1/album/tracks?format=xml&apikey=4p1k3y&albumid=MW0000268192</tracksUri>
        <recordingDates i:nil="true" />
      </album>
    </result>
  </results>
</similarResponse>

Response Example 3

The most similar show to the TV series White Collar appearing on Time-Warner Cable in Beverly Hills, with up to three broadcast times.
Requested with http://api.rovicorp.com/recs/v2.1/video/similar?apikey=apikey&sig=sig&
entitytype=movie&entitytype=tvseries&cosmoprogramid=12100588&clu=360861&rep=3&size=1.
{
   "similarResponse":{
      "meta:id":"tul1cpgpsrapp20:gwy:3ikyh8",
      "controlSet":{
         "status":"ok",
         "code":200,
         "messages":null
      },
      "results":[
         {
            "type":"tvseries",
            "relevance":[
               {
                  "code":"Score",
                  "value":95.11005
               }
            ],
            "availabilities":[
               {
                  "start":"20140323040000+0000",
                  "source":"CLU_360861",
                  "end":"20140323050000+0000",
                  "cosmosource":11616,
                  "format":"sd",
                  "available_as":{
                     "id":14056331,
                     "type":"CosmoIdProgram"
                  }
               },
               {
                  "start":"20140323030000+0000",
                  "source":"CLU_360861",
                  "end":"20140323040000+0000",
                  "cosmosource":11616,
                  "format":"sd",
                  "available_as":{
                     "id":19901000,
                     "type":"CosmoIdProgram"
                  }
               },
               {
                  "start":"20140404070000+0000",
                  "source":"CLU_360861",
                  "end":"20140404080000+0000",
                  "cosmosource":13123,
                  "format":"sd",
                  "available_as":{
                     "id":6688066,
                     "type":"CosmoIdProgram"
                  }
               }
            ],
            "id":6688066,
            "messages":null,
            "video":{
               "ids":{
                  "amgMovieId":null,
                  "cosmoId":"6688066",
                  "iguideId":6688066,
                  "pidPaid":null,
                  "videoId":null
               },
               "seriesIds":null,
               "masterTitle":"Burn Notice",
               "secondaryTitle":"",
               "episodeTitle":null,
               "category":"Other",
               "color":"Color",
               "lastAirDate":"2013-09-12T00:00:00.00Z",
               "originalAirDate":"2007-06-28T00:00:00.00Z",
               "programType":"Series",
               "releaseYear":2007,
               "duration":60,
               "subcategory":"action/adventure",
               "syndicated":false,
               "programLanguage":"English",
               "partNumber":null,
               "partTotal":null,
               "parentalRatings":null,
               "parentalRatingsUri":"http://api.rovicorp.com/data/v1.1/video/parentalRatings?format=json&apikey=4p1k3y&cosmoid=6688066",
               "cast":null,
               "castUri":"http://api.rovicorp.com/data/v1.1/video/cast?format=json&apikey=4p1k3y&cosmoid=6688066",
               "crew":null,
               "crewUri":"http://api.rovicorp.com/data/v1.1/video/crew?format=json&apikey=4p1k3y&cosmoid=6688066",
               "awards":null,
               "awardsUri":"http://api.rovicorp.com/data/v1.1/video/awards?format=json&apikey=4p1k3y&cosmoid=6688066",
               "images":null,
               "imagesUri":"http://api.rovicorp.com/data/v1.1/video/images?format=json&apikey=4p1k3y&cosmoid=6688066",
               "clip":null,
               "clipUri":null,
               "seasons":null,
               "seasonsUri":"http://api.rovicorp.com/data/v1.1/video/seasons?format=json&apikey=4p1k3y&cosmoid=6688066",
               "variants":null,
               "variantsUri":"http://api.rovicorp.com/data/v1.1/video/variants?format=json&apikey=4p1k3y&cosmoid=6688066",
               "schedule":"",
               "scheduleUri":null,
               "event":null,
               "eventUri":null,
               "keywords":null,
               "keywordsUri":"http://api.rovicorp.com/data/v1.1/video/keywords?format=json&apikey=4p1k3y&cosmoid=6688066",
               "moods":null,
               "moodsUri":null,
               "related":null,
               "relatedUri":"http://api.rovicorp.com/data/v1.1/video/related?format=json&apikey=4p1k3y&cosmoid=6688066",
               "review":null,
               "reviewUri":null,
               "synopsis":null,
               "synopsisUri":"http://api.rovicorp.com/data/v1.1/video/synopsis?format=json&apikey=4p1k3y&cosmoid=6688066",
               "themes":null,
               "themesUri":"http://api.rovicorp.com/data/v1.1/video/themes?format=json&apikey=4p1k3y&cosmoid=6688066",
               "tones":null,
               "tonesUri":"http://api.rovicorp.com/data/v1.1/video/tones?format=json&apikey=4p1k3y&cosmoid=6688066"
            }
         }
      ]
   }
}

Response Example 4

The most similar song to David Bowie's Modern Love.
Requested with http://api.rovicorp.com/recs/v2.1/music/similar?apikey=apikey&sig=sig&
entitytype=song&trackid=MT0000045446&format=json&size=1.
{
   "similarResponse":{
      "meta:id":"tul1cpgpsrapp13:gwy:3oef5r",
      "controlSet":{
         "status":"ok",
         "code":200,
         "messages":null
      },
      "results":[
         {
            "type":"song",
            "relevance":[
               {
                  "code":"Score",
                  "value":18.29482
               }
            ],
            "id":"MT0001631814",
            "messages":null,
            "song":{
               "ids":{
                  "amgClassicalTrackId":null,
                  "amgPopTrackId":"T 26347178",
                  "isrcId":"GBAAN7400040",
                  "muzeId":"2994231",
                  "trackId":"MT0001631814"
               },
               "title":"Heartbreak Hotel",
               "primaryArtists":[
                  {
                     "id":"MN0000080118",
                     "name":"Kevin Ayers"
                  },
                  {
                     "id":"MN0000944011",
                     "name":"Cale"
                  },
                  {
                     "id":"MN0000224638",
                     "name":"John Cale"
                  },
                  {
                     "id":"MN0001757321",
                     "name":"Eno"
                  },
                  {
                     "id":"MN0000617196",
                     "name":"Brian Eno"
                  },
                  {
                     "id":"MN0000868306",
                     "name":"Nico"
                  },
                  {
                     "id":"MN0000489520",
                     "name":"Mike Oldfield"
                  },
                  {
                     "id":"MN0000292915",
                     "name":"Robert Wyatt"
                  }
               ],
               "isPick":true,
               "genres":[
                  {
                     "id":"MA0000002613",
                     "name":"Pop/Rock",
                     "weight":10
                  },
                  {
                     "id":"MA0000002745",
                     "name":"New Age",
                     "weight":5
                  }
               ],
               "appearances":null,
               "appearancesUri":"http://api.rovicorp.com/data/v1.1/song/appearances?format=json&apikey=4p1k3y&trackId=MT0001631814",
               "moods":null,
               "moodsUri":null,
               "review":null,
               "reviewUri":null,
               "styles":null,
               "stylesUri":null,
               "themes":null,
               "themesUri":null,
               "sample":null,
               "sampleUri":"http://api.rovicorp.com/data/v1.1/song/sample?format=json&apikey=4p1k3y&trackId=MT0001631814"
            }
         }
      ]
   }
}

Error Codes

CodeDescription
400 Incorrect or invalid request. The reason is shown in the Message object in ControlSet.

See Also

↑ Top

Retrieved from "http://prod-doc.rovicorp.com/mashery/index.php/Recommendations-api/v2.1/similar"
Personal tools