V1.Metadata.SearchService:Similar

Jump to: navigation, search

Similar

Returns similar items in order of similarity and popularity.

Syntax

similar? nameid=nameid
trackid=trackid
albumid=albumid
amgvideoid=amgvideoid 		&entitytype=entitytype&apikey=apikey&sig=sig [&size=size]

Request Example 1

Find musicians similar to The Doors.
http://api.rovicorp.com/recs/v1/similar?apikey=apikey&sig=sig&nameid=MN0000114342&entitytype=artist

Request Example 2

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

Request Example 3

Get the five most similar movies to Avatar.
http://api.rovicorp.com/recs/v1/similar?apikey=apikey&sig=sig&amgvideoid=V+++352199&entitytype=movie&size=5

Request Parameters

ParameterRequiredDescription
apikey Yes Access code that authorizes your request for data from Rovi.
entitytype Yes Type of content.
To return similar . . .Specify this entitytype . . .    And this ID.
albumsalbumalbumid
moviesmovieamgvideoid
TV seriestvseries  amgvideoid
popular songssongtrackid
people involved in musicartistnameid
A request can return data for only one entity type except for the combination of movie and TV series. To do that, specify two entitytype parameters like this: entitytype=tvseries&entitytype=movie. Note:  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 example: 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
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. When using an AMG Video ID in a request, replace any spaces in the ID with plus (+) or percent20 (%20) symbols, like this: V+++295550. Your application can grab video IDs from responses to the following requests:

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

  • nameid
  • albumid
  • trackid
  • amgvideoid
nameid Conditional Rovi Music ID for a person, group, or organization, consisting of the prefix MN followed by a ten-digit number. For example: 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
trackid Conditional Rovi Music ID for a popular song, consisting of the prefix MT followed by a ten-digit number. For example: 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
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

ResponseTypeDescription
album Album A Rovi Music Album/Info response, returned only for a request with an albumid parameter and an entitytype of album.
id String [ ] Database ID for an item returned in a search response.
messages String Reasons why an item was selected for the search response.
movie Movie A Rovi DVDs Movie/Info response, returned only for a request with an amgvideoid parameter and an entitytype of movie or tvseries.
name Name A Rovi Music Name/Info response, returned only for a request with a nameid parameter and an entitytype of artist.
provider String Database in which a search result was found:
  • amgvideo
  • rovimusic
relevance Relevance [ ] Rating of an item in a search response. Items with a higher relevance appear earlier in the list of items.
song Song A Rovi Music Song/Info response, returned only for a request with a trackid parameter and an entitytype of song.
type String Entity type of a search result.

Response Example 1

The most similar movie to Avatar. Requested with http://api.rovicorp.com/recs/v1/similar?amgvideoid=V+++352199&entitytype=movie&size=1&apikey=apikey&sig=sig.
{"similarResponse": {
  "id": "tul1cstadgwapp01:gwy:clw",
  "controlSet": {
    "status": "ok",
    "code": 200,
    "messages": [""]
  },
  "results": [
    {
    "type": "movie",
    "relevance": [
      {
      "code": "Score",
      "name": 1.8
      }
    ],
    "provider": "amgvideo",
    "id": "V   423766",
    "messages": null,
    "movie": {
      "ids": {
        "cosmoId": "8904894",
        "movieId": "V   423766"
      },
      "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": null,
      "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": ""
    }
  }]
}
}

Response Example 2

The most similar song to Jeff Beck's A Day In The Life. Requested with http://api.rovicorp.com/recs/v1/similar?trackid=MT0009826914&entitytype=song&size=1&apikey=apikey&sig=sig.
{"similarResponse": {
  "id": "tul1cstadgwapp01:gwy:cm6",
  "controlSet": {
    "status": "ok",
    "code": 200,
    "messages": [""]
  },
  "results": [
    {
    "type": "song",
    "relevance": [
      {
      "code": "Score",
      "name": 2
    }],
    "provider": "rovimusic",
    "id": "MT0002388504",
    "messages": null,
    "song": {
      "ids": {
        "a:amgPopTrackId": "T  1345112",
        "a:isrcId": "NLF057890044",
        "a:muzeId": 2758008,
        "a:trackId": "MT0002388504"
      },
      "title": "Early in the Morning",
      "primaryArtists": {
        "AlbumArtist": {
          "id": "MN0000187478",
          "name": "Eric Clapton"
        }
      },
      "isPick": false,
      "genres": [
        {
        "Genre": {
          "id": "MA0000002467",
          "name": "Blues",
          "weight": 5
        },
        "Genre": {
          "id": "MA0000002613",
          "name": "Pop/Rock",
          "weight": 5
        }
      }],
      "appearances": null,
      "appearancesUri": "http://api.rovicorp.com/v1/song/appearances?format=xml&apikey=4p1k3y&trackId=MT0002388504",
      "moods": null,
      "moodsUri": "http://api.rovicorp.com/v1/song/moods?format=xml&apikey=4p1k3y&trackId=MT0002388504",
      "review": null,
      "reviewUri": null,
      "styles": null,
      "stylesUri": "http://api.rovicorp.com/v1/song/styles?format=xml&apikey=4p1k3y&trackId=MT0002388504",
      "themes": null,
      "themesUri": "http://api.rovicorp.com/v1/song/themes?format=xml&apikey=4p1k3y&trackId=MT0002388504"
    }
  }]
}
}

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/V1.Metadata.SearchService:Similar"
Personal tools