Catalog-matching-api/v2.1/match/name

Jump to: navigation, search

Match/Name

Returns Rovi IDs for a person or group in your catalog in order of confidence level, based on name and field-level data, along with data you can use to verify a match.

Note: The primary Rovi ID for a name is the name ID.

Syntax

catalog/match/name?apikey=apikey&sig=sig&name=name [&birthdate=birthdate] [&deathdate=deathdate] [&include=include] [&format=format] [&size=size]

Request Example 1

Get IDs for the director Werner Herzog in an XML response and include a biography for verification.

Request Example 2

Get IDs for the actress Julia Stiles and include a list of films she's been in.

Request Example 3

Get IDs for members of The Band.

Request Parameters

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

ParameterRequiredDescription
apikey Yes Access code that authorizes your request for data from Rovi.
catalog Yes Database to match against.
To match against . . .Specify this catalog.
people in musicmusic 
people in movies and TV series (our DVD database)amgvideo 
people in television (our international TV schedule database)video ⊑⊒
name Yes Name of the person or group. This returns the top search result for that name. Replace any spaces with plus (+) or percent20 (%20) symbols.
sig Yes A calculated, 32-hex-digit authorization code. To perform the calculation, execute the MD5 function on the concatenation of the following three ASCII 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.

Express the alpha hex digits as lower case.

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.

birthdate No Date of birth in YYYYMMDD format.
deathdate No Date of death in YYYYMMDD format.
format No Format of the returned data: json or xml. The default is JSON.

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.

include No Additional data to include in each result returned. To include images of a person, for example, specify include=images. For multiple includes, separate the values with commas like this: include=images,factsheets. A request can contain up to 20 include values.

The data that is available for a person depends, in general, on the area of work they are involved in as shown by the catalog icons:

  •   music
  •   movies
  • ⊑⊒  television
For catalogYou can include these results . . .
music 
  • All
  • Aliases 
  • AssociatedWith 
  • ClassicalBio 
  • CollaboratorWith 
  • Compositions 
  • Contemporaries 
  • Credits*
  • Discography 
  • Factsheets* 
  • Filmography
  • Followers 
  • GroupMembers 
  • Images 
  • Influencers 
  • MemberOf 
  • Moods 
  • MovieBio
  • MovieStyles
  • MusicBio 
  • MusicCredits 
  • MusicStyles 
  • Similars 
  • Songs 
  • Themes 
  • Videos 
  • Web 
amgvideo    
  • All
  • Aliases 
  • AssociatedWith 
  • ClassicalBio
  • CollaboratorWith
  • Compositions
  • Contemporaries
  • Credits* 
  • Discography
  • Factsheets* 
  • Filmography 
  • Followers
  • GroupMembers
  • Images 
  • Influencers
  • MemberOf
  • Moods
  • MovieBio 
  • MovieStyles 
  • MusicBio
  • MusicCredits
  • MusicStyles
  • Similars
  • Songs
  • Themes
  • Videos 
  • Web 
video ⊑⊒
  • All
  • Aliases ⊑⊒
  • AssociatedWith
  • ClassicalBio
  • CollaboratorWith
  • Compositions
  • Contemporaries
  • Credits* ⊑⊒
  • Discography
  • Factsheets* ⊑⊒
  • Filmography ⊑⊒
  • Followers
  • GroupMembers
  • Images ⊑⊒
  • Influencers
  • MemberOf
  • Moods
  • MovieBio ⊑⊒
  • MovieStyles ⊑⊒
  • MusicBio
  • MusicCredits
  • MusicStyles
  • Similars
  • Songs
  • Themes
  • Videos ⊑⊒
  • Web ⊑⊒

Reminder: These options may return a large amount of data. To speed data transmission, do the following:

  • Request only data that you need.
  • Request a compressed response by including Accept-Encoding: gzip,deflate in the HTTP header.
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 Match/Name

ResponseTypeDescription
results result [ ] Information about items that match the criteria specified in the request.

Response Example 1

Here's the response to Request Example 3, looking for the members in The Band. Just the top result is requested here to show as a sample.
Requested with http://api.rovicorp.com/recognition/v2.1/music/match/name?apikey=apikey&sig=sig&
name=the+band&include=groupmembers&size=1
{
   "matchResponse":{
      "meta:id":"tul1cpgssrapp1:gwy:2wyp9",
      "controlSet":{
         "status":"ok",
         "code":200,
         "messages":null
      },
      "results":[
         {
            "type":"artist",
            "relevance":[
               {
                  "code":"Score",
                  "value":0.6
               }
            ],
            "id":"MN0000038490",
            "messages":null,
            "name":{
               "ids":{
                  "amgClassicalId":"Q 284901",
                  "amgMovieId":"P 3678",
                  "amgPopId":"P 3624",
                  "cosmoId":null,
                  "nameId":"MN0000038490"
               },
               "name":"The Band",
               "isGroup":true,
               "primaryMedia":"Popular",
               "musicGenres":[
                  {
                     "id":"MA0000002613",
                     "name":"Pop/Rock",
                     "weight":10
                  }
               ],
               "movieGenres":[
                  {
                     "id":"D 1776",
                     "name":"Music [nf]",
                     "weight":99
                  }
               ],
               "active":[
                  "1960s",
                  "1970s",
                  "1980s",
                  "1990s"
               ],
               "birth":{
                  "date":"1967-??-??",
                  "place":"Toronto, Ontario, Canada"
               },
               "death":{
                  "date":"1976-11-??",
                  "place":""
               },
               "country":"Canada",
               "period":"",
               "headlineBio":"Former backing band for Bob Dylan who helped usher in the back-to-basics roots-rock approach of the '70s.",
               "classicalBio":null,
               "classicalBioUri":null,
               "discography":null,
               "discographyUri":"http://api.rovicorp.com/v1/name/discography?format=json&apikey=141341&nameid=MN0000038490",
               "filmography":null,
               "filmographyUri":"http://api.rovicorp.com/v1/name/filmography?format=json&apikey=141341&nameid=MN0000038490",
               "followers":null,
               "followersUri":"http://api.rovicorp.com/v1/name/followers?format=json&apikey=141341&nameid=MN0000038490",
               "groupMembers":[
                  {
                     "id":"MN0000182291",
                     "name":"Garth Hudson"
                  },
                  {
                     "id":"MN0000346074",
                     "name":"Richard Manuel"
                  },
                  {
                     "id":"MN0000865769",
                     "name":"Randy Ciarlante"
                  },
                  {
                     "id":"MN0000290918",
                     "name":"Richard Bell"
                  },
                  {
                     "id":"MN0002291726",
                     "name":"Stan Szelest"
                  },
                  {
                     "id":"MN0000052924",
                     "name":"Blondie Chaplin"
                  },
                  {
                     "id":"MN0000275130",
                     "name":"Robbie Robertson"
                  },
                  {
                     "id":"MN0000299307",
                     "name":"Rick Danko"
                  },
                  {
                     "id":"MN0000823165",
                     "name":"Levon Helm"
                  },
                  {
                     "id":"MN0000294785",
                     "name":"Jim Weider"
                  }
               ],
               "groupMembersUri":"http://api.rovicorp.com/v1/name/groupMembers?format=json&apikey=141341&nameid=MN0000038490",
               "memberOf":null,
               "memberOfUri":null,
               "images":null,
               "imagesUri":"http://api.rovicorp.com/v1/name/images?format=json&apikey=141341&nameid=MN0000038490",
               "influencers":null,
               "influencersUri":"http://api.rovicorp.com/v1/name/influencers?format=json&apikey=141341&nameid=MN0000038490",
               "similars":null,
               "similarsUri":"http://api.rovicorp.com/v1/name/similars?format=json&apikey=141341&nameid=MN0000038490",
               "moods":null,
               "moodsUri":"http://api.rovicorp.com/v1/name/moods?format=json&apikey=141341&nameid=MN0000038490",
               "movieBio":null,
               "movieBioUri":null,
               "musicBio":null,
               "musicBioUri":"http://api.rovicorp.com/v1/name/musicBio?format=json&apikey=141341&nameid=MN0000038490",
               "musicCredits":null,
               "musicCreditsUri":"http://api.rovicorp.com/v1/name/musicCredits?format=json&apikey=141341&nameid=MN0000038490",
               "songs":null,
               "songsUri":"http://api.rovicorp.com/v1/name/songs?format=json&apikey=141341&nameid=MN0000038490",
               "musicStyles":null,
               "musicStylesUri":"http://api.rovicorp.com/v1/name/musicStyles?format=json&apikey=141341&nameid=MN0000038490",
               "themes":null,
               "themesUri":"http://api.rovicorp.com/v1/name/themes?format=json&apikey=141341&nameid=MN0000038490",
               "videos":null,
               "videosUri":null,
               "movieStyles":null,
               "movieStylesUri":"http://api.rovicorp.com/v1/name/movieStyles?format=json&apikey=141341&nameid=MN0000038490",
               "contemporaries":null,
               "contemporariesUri":"http://api.rovicorp.com/v1/name/contemporaries?format=json&apikey=141341&nameid=MN0000038490",
               "associatedWith":null,
               "associatedWithUri":"http://api.rovicorp.com/v1/name/associatedwith?format=json&apikey=141341&nameid=MN0000038490",
               "collaboratorWith":null,
               "collaboratorWithUri":null,
               "compositions":null,
               "compositionsUri":null,
               "aliases":null,
               "aliasesUri":null,
               "web":null,
               "webUri":null,
               "factsheets":null,
               "factsheetsUri":null,
               "schedule":null,
               "scheduleUri":null,
               "credits":null,
               "creditsUri":null
            }
         }
      ]
   }
}

Response Example 2

Here's the response to Request Example 1, looking for IDs for Werner Herzog in an XML response and a biography. Just the top result is requested here to show as a sample.
Requested with http://api.rovicorp.com/recognition/v2.1/amgvideo/match/name?apikey=apikey&sig=sig&
name=werner+herzog&include=moviebio&format=xml&size=1
<matchResponse 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:meta="com.rovicorp.metadataservice" xmlns="com.rovicorp.metadataservice" meta:id="tul1cpgssrapp1:gwy:2vxjr">
  <controlSet>
    <status>ok</status>
    <code>200</code>
    <messages i:nil="true"/>
  </controlSet>
  <results>
    <result>
      <type>credit</type>
      <relevance>
        <code>Score</code>
        <value>0.6</value>
      </relevance>
      <availabilties/>
      <id>P 94214</id>
      <messages i:nil="true"/>
      <name>
        <ids>
          <amgClassicalId>Q 29457</amgClassicalId>
          <amgMovieId>P 94214</amgMovieId>
          <amgPopId>P 628301</amgPopId>
          <cosmoId>582627</cosmoId>
          <nameId>MN0001516976</nameId>
        </ids>
        <name>Werner Herzog</name>
        <isGroup>false</isGroup>
        <primaryMedia>Movies</primaryMedia>
        <musicGenres>
          <Genre>
            <id>MA0000004432</id>
            <name>Stage &amp; Screen</name>
            <weight>10</weight>
          </Genre>
          <Genre>
            <id>MA0000002521</id>
            <name>Classical</name>
            <weight>9</weight>
          </Genre>
        </musicGenres>
        <movieGenres>
          <Genre>
            <id>D 658</id>
            <name>Avant-garde / Experimental</name>
            <weight>45</weight>
          </Genre>
          <Genre>
            <id>D 1659</id>
            <name>Culture &amp; Society [nf]</name>
            <weight>82</weight>
          </Genre>
          <Genre>
            <id>D 649</id>
            <name>Drama</name>
            <weight>99</weight>
          </Genre>
          <Genre>
            <id>D 1661</id>
            <name>Film, TV &amp; Radio [nf]</name>
            <weight>45</weight>
          </Genre>
          <Genre>
            <id>D 1055</id>
            <name>History [nf]</name>
            <weight>53</weight>
          </Genre>
        </movieGenres>
        <active>
          <a:string>1970s</a:string>
          <a:string>1980s</a:string>
          <a:string>1990s</a:string>
          <a:string>2000s</a:string>
        </active>
        <birth>
          <date>09/05/1942</date>
          <place>Munich, Germany</place>
        </birth>
        <death>
          <date/>
          <place/>
        </death>
        <country/>
        <period>1962-2012</period>
        <headlineBio/>
        <classicalBio i:nil="true"/>
        <classicalBioUri i:nil="true"/>
        <discography i:nil="true"/>
        <discographyUri i:nil="true"/>
        <filmography i:nil="true"/>
        <filmographyUri>http://api.rovicorp.com/v1/name/filmography?format=xml&amp;apikey=141341&amp;amgmovieid=P+94214</filmographyUri>
        <followers i:nil="true"/>
        <followersUri i:nil="true"/>
        <groupMembers i:nil="true"/>
        <groupMembersUri i:nil="true"/>
        <memberOf i:nil="true"/>
        <memberOfUri i:nil="true"/>
        <images i:nil="true"/>
        <imagesUri>http://api.rovicorp.com/v1/name/images?format=xml&amp;apikey=141341&amp;amgmovieid=P+94214</imagesUri>
        <influencers i:nil="true"/>
        <influencersUri i:nil="true"/>
        <similars i:nil="true"/>
        <similarsUri i:nil="true"/>
        <moods i:nil="true"/>
        <moodsUri i:nil="true"/>
        <movieBio>
          <text>One of the most influential filmmakers in New German Cinema and one of the most extreme personalities in film &lt;I&gt;per se&lt;/I&gt;, larger-than-life [rovilink=&quot;P&quot;]Werner Herzog[/rovilink] quickly gained recognition not only for creating some of the most fantastic narratives in film, but for pushing himself and his crew to unprecedented lengths, again and again, in order to achieve the effects he demanded. Born [rovilink=&quot;P&quot;]Werner Stipetic[/rovilink] in Munich on September 5, 1942, [rovilink=&quot;P&quot;]Herzog[/rovilink] tremendous intelligence from an early age, and recognized his future vocation in his early teens, when he began submitting scripts to German film producers. Herzog began producing short films in college, and shot his premier feature, [rovilink=&quot;V&quot;]Lebenszeichen[/rovilink] in 1968. The director followed it with a 1970 documentary about the disabled, [rovilink=&quot;V&quot;]Behinderte Zukunft[/rovilink] ([rovilink=&quot;V&quot;]Handicapped Future[/rovilink]). His second feature film, the 1970 [rovilink=&quot;V&quot;]Even Dwarfs Started Small[/rovilink], depicts the daily activities of a bunch of dwarfs and midgets in a German penal community, who descend into an anarchic state. He continued to shoot arthouse features throughout the &apos;70s in his native Germany like [rovilink=&quot;V&quot;]Fata Morgana[/rovilink], [rovilink=&quot;V&quot;]Land des Schweigens und der Dunkelheit[/rovilink], [rovilink=&quot;V&quot;]Aguirre the Wrath of God[/rovilink], [rovilink=&quot;V&quot;]The Mystery of Kaspar Hauser[/rovilink] , [rovilink=&quot;V&quot;]Heart of Glass[/rovilink], [rovilink=&quot;V&quot;]Die grosse Ekstase des Bildschnitzers Steiner[/rovilink], [rovilink=&quot;V&quot;]Stroszek[/rovilink], [rovilink=&quot;V&quot;]Nosferatu[/rovilink] ,[rovilink=&quot;V&quot;]Woyzeck[/rovilink], and[rovilink=&quot;V&quot;]God&apos;s Angry Man[/rovilink]. Between 1980 and 1982, [rovilink=&quot;P&quot;]Herzog[/rovilink] managed to top the insanity of that film shoot with [rovilink=&quot;V&quot;]Fitzcarraldo[/rovilink], the story of a nineteenth century opera lover, determined to bring the music of Enrico Caruso to the Peruvian Indians. The production proved to be difficult. During shooting, a plane crashed and killed several locals, lead [rovilink=&quot;P&quot;]Jason Robards[/rovilink] acquired amoebic dysentery and had to be replaced with [rovilink=&quot;P&quot;]Kinski[/rovilink], second-billed [rovilink=&quot;P&quot;]Mick Jagger[/rovilink] abandoned the production, steamer ships used for the set became mired in the mud and could not be moved until rainy season, and tribal war nearly erupted nearby. Herzog soon found himself more interested in hardcore documentary work, and began focusing on non-fiction, with [rovilink=&quot;V&quot;]Lessons of Darkness[/rovilink] (1992), [rovilink=&quot;V&quot;]Bells from the Deep: Faith and Superstition in Russia[/rovilink] (1993), [rovilink=&quot;V&quot;]The Transformation of the World into Music[/rovilink] (1994), [rovilink=&quot;V&quot;]Little Dieter Needs to Fly[/rovilink] (1997), [rovilink=&quot;V&quot;]Wings of Hope[/rovilink] (2000), [rovilink=&quot;V&quot;]Wheel of Time[/rovilink] (2003) and [rovilink=&quot;V&quot;]Incident at Loch Ness[/rovilink] (2004). [rovilink=&quot;V&quot;]Grizzly Man[/rovilink] (2004) - comprised of footage shot by ill-fated &quot;Grizzly Bear expert&quot; [rovilink=&quot;V&quot;]Timothy Treadwell[/rovilink] just before his death in a bear attack - elicited particularly strong acclaim, while 2010&apos;s [rovilink=&quot;V&quot;]Cave of Forgotten Dreams[/rovilink] captured the 30,000 year old cave art in the Chauvet Cave using 3D cameras. [rovilink=&quot;P&quot;]Herzog[/rovilink]&apos;s focus on documentaries didn&apos;t keep him from working on narrative films as a whole. 2001&apos;s [rovilink=&quot;V&quot;]Invincible[/rovilink] dramatized the story of a Jewish man who rose to power with the Nazis, only to renounce his party affiliations and swear allegiance to his people, and the director&apos;s 2006 [rovilink=&quot;V&quot;]Rescue Dawn[/rovilink] starred [rovilink=&quot;P&quot;]Christian Bale[/rovilink] as real life pilot [rovilink=&quot;P&quot;]Dieter Dengler[/rovilink], who was shot down over Vietnam, and held in a Vietnamese prison camp, only to lead a successful escape with his inmates. Changing gears dramatically, 2010&apos;s [rovilink=&quot;V&quot;]Bad Lieutenant: Port of Call New Orleans[/rovilink] starred [rovilink=&quot;P&quot;]Nicholas Cage[/rovilink] as an insane cop. In addition to his directing and screenwriting work, [rovilink=&quot;P&quot;]Herzog[/rovilink] has acted in a number of films, perhaps most memorably in [rovilink=&quot;P&quot;]Les Blank[/rovilink]&apos;s 1980 [rovilink=&quot;D&quot;]documentary[/rovilink] [rovilink=&quot;V&quot;]Werner Herzog Eats His Shoe[/rovilink]. The film was the result of a bet [rovilink=&quot;P&quot;]Herzog[/rovilink] once had with an American film student: [rovilink=&quot;P&quot;]Herzog[/rovilink] told the student -- who was always talking about making a film but never actually doing it -- that if he actually completed the film, [rovilink=&quot;P&quot;]Herzog[/rovilink] would eat his own shoe. The student was [rovilink=&quot;P&quot;]Errol Morris[/rovilink], who later became known for his [rovilink=&quot;D&quot;]documentaries[/rovilink] [rovilink=&quot;V&quot;]Gates of Heaven[/rovilink], [rovilink=&quot;V&quot;]The Thin Blue Line[/rovilink], and [rovilink=&quot;V&quot;]Fast, Cheap &amp; Out of Control[/rovilink], and he did indeed make his film. Having lost the bet, [rovilink=&quot;P&quot;]Herzog[/rovilink] made good on his promise, and the result was one of the stranger moments in [rovilink=&quot;D&quot;]documentary[/rovilink] history. In {$Paul Cox}&apos;s 1983 picture {#Man of Flowers}, [rovilink=&quot;P&quot;]Herzog[/rovilink] plays the central character&apos;s stern, disciplinarian father during a wordless flashback.</text>
          <author>Nathan Southern</author>
        </movieBio>
        <movieBioUri>http://api.rovicorp.com/v1/name/movieBio?format=xml&amp;apikey=141341&amp;amgmovieid=P+94214</movieBioUri>
        <musicBio i:nil="true"/>
        <musicBioUri i:nil="true"/>
        <musicCredits i:nil="true"/>
        <musicCreditsUri>http://api.rovicorp.com/v1/name/musicCredits?format=xml&amp;apikey=141341&amp;amgmovieid=P+94214</musicCreditsUri>
        <songs i:nil="true"/>
        <songsUri i:nil="true"/>
        <musicStyles i:nil="true"/>
        <musicStylesUri>http://api.rovicorp.com/v1/name/musicStyles?format=xml&amp;apikey=141341&amp;amgmovieid=P+94214</musicStylesUri>
        <themes i:nil="true"/>
        <themesUri i:nil="true"/>
        <videos i:nil="true"/>
        <videosUri i:nil="true"/>
        <movieStyles i:nil="true"/>
        <movieStylesUri>http://api.rovicorp.com/v1/name/movieStyles?format=xml&amp;apikey=141341&amp;amgmovieid=P+94214</movieStylesUri>
        <contemporaries i:nil="true"/>
        <contemporariesUri i:nil="true"/>
        <associatedWith i:nil="true"/>
        <associatedWithUri>http://api.rovicorp.com/v1/name/associatedwith?format=xml&amp;apikey=141341&amp;amgmovieid=P+94214</associatedWithUri>
        <collaboratorWith i:nil="true"/>
        <collaboratorWithUri i:nil="true"/>
        <compositions i:nil="true"/>
        <compositionsUri i:nil="true"/>
        <aliases i:nil="true"/>
        <aliasesUri i:nil="true"/>
        <web i:nil="true"/>
        <webUri i:nil="true"/>
        <factsheets i:nil="true"/>
        <factsheetsUri>http://api.rovicorp.com/v1/name/factsheets?format=xml&amp;apikey=141341&amp;amgmovieid=P+94214</factsheetsUri>
        <schedule i:nil="true"/>
        <scheduleUri i:nil="true"/>
        <credits i:nil="true"/>
        <creditsUri>http://api.rovicorp.com/v1/name/credits?format=xml&amp;apikey=141341&amp;amgmovieid=P+94214</creditsUri>
      </name>
    </result>
  </results>
</matchResponse>

Error Codes

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

See Also

↑ Top

Personal tools