SnR/V2/FilterBrowse

Jump to: navigation, search

FilterBrowse Version 2.0

Locates content in Rovi Cloud Services based on field-level criteria and returns results listed in order of relevance. Relevance is a calculated score based on usage data and editorial weighting.

A FilterBrowse request is a Search request without the query. Use FilterBrowse to present custom views of music, movies, or TV, and let the user browse areas of interest and select content.

Syntax

endpoint/filterbrowse?apikey=apikey&sig=sig&entitytype=entitytype [&filter=filter] [&include=include] [&facet=facet] [&format=format] [&country=country] [&language=language] [&offset=offset] [&size=size]

Request Example 1

Get 10 pop/rock albums released in the last week of 2010 and show the number released in all genres.
http://api.rovicorp.com/search/v2/music/filterbrowse?apikey=apikey&sig=sig&entitytype=album&
facet=genre&size=10&filter=genreid:MA0000002613&filter=releasedate>20101224&
filter=releasedate<20110101

Request Example 2

Find artists active in contemporary blues during the 2000s.
http://api.rovicorp.com/search/v2/music/filterbrowse?apikey=apikey&sig=sig&entitytype=artist&
filter=subgenreid:MA0000002960&filter=decade:2000s

Request Example 3

Find spy films released in 2009.
http://api.rovicorp.com/search/v2/amgvideo/filterbrowse?apikey=apikey&sig=sig&entitytype=movie&
filter=genreid:D+++515&filter=releaseyear:2009

Request Example 4

Find songs released in 2004 in the yodeling subgenre and return a list of the releases they appeared on.
http://api.rovicorp.com/search/v2/music/filterbrowse?apikey=apikey&sig=sig&entitytype=song&
facet=genre&filter=subgenreid:MA0000012228&filter=releasedate>20040101&
filter=releasedate<20050101&include=song:appearances

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 search for.
In this endpoint . . .   To search in this area . . .   Specify this entitytype.
music ♫albumsalbum
popular songssong
people working in musicartist
amgvideo 日moviesmovie
TV seriestvseries
video ⊑⊒moviesmovie
TV seriestvseries
TV programsonetimeonly
To return data from multiple entity types within an endpoint, specify multiple 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.

country No Country of the language of the response. The current release of the API supports only US.
facet No Count of items available to be returned.
To return the item count available . . .  Specify this facet.
for the entity typetype
by genre or subgenregenre
To return both, specify two facet parameters: facet=type&facet=genre.
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.

Examples:

  • Specify filter=decade:1990s to limit the results to artists active in the 1990s.
  • Specify filter=length<120 to return only movies less than 120 minutes long.
  • Specify filter=genreid:MA0000002467 to limit the results to the blues genre.
  • Specify filter=releasedate>19991231 for releases in the year 2000 or later.
  • Specify filter=moodid:XA0000000952 to return music results with a bright mood.
  • Specify filter=mpaa:G|mpaa:PG|mpaa:PG13 to return movies rated G, PG, or PG13.
  • Specify filter=editorialrating>7 to return albums or movies with a rating greater than 7.
  • Specify filter=themeid:MA0000006310 to return music results with a Sunday afternoon theme.
  • Specify filter=toneid:D++2067&filter=toneid:D++1292 for movies with both gruesome and cerebral tones.
  • Specify filter=subgenreid:D+++509|subgenreid:D+++510 to return action thriller or martial arts movies.

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=releasedate>:20070101&
filter=releasedate<20080101. A request can contain up to 20 filter parameters.

The following shows which fields you can select for each 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 this entity type. . .You can filter on . . .Example or Format
album
  • moodid
  • themeid
  • genreid
  • subgenreid
  • performerid
  • releasedate
  • editorialrating
  • recordingtype

XA0000000952 (table)
MA0000005079 (table)
MA0000002467 (look up)
MA0000002517 (look up)
MN0000994823
YYYYMMDD
1 to 10
single (live, remix, clean, single, mainalbum, soundtrack, variousartists)

artist
  • decade
  • moodid
  • themeid
  • genreid
  • subgenreid

2000s
XA0000000952 (table)
MA0000005079 (table)
MA0000002467 (look up)
MA0000002517 (look up)

movie
  • mpaa
  • adult
  • length
  • toneid
  • moodid
  • themeid
  • genreid
  • subgenreid
  • releaseyear
  • editorialrating

PG13
true (amgvideo endpoint)
120 (minutes)
D++1304 (table) (amgvideo endpoint)
D++2030 (table) (amgvideo endpoint)
D++1431 (table) (amgvideo endpoint)
D+++649 (look up) (amgvideo endpoint)
D++1376 (look up) (amgvideo endpoint)
2008
1 to 10 (amgvideo endpoint)

onetimeonly
  • length

120 (minutes, integer)

song
  • moodid
  • themeid
  • genreid
  • subgenreid
  • performerid
  • releasedate

XA0000000952 (table)
MA0000005079 (table)
MA0000002467 (look up)
MA0000002517 (look up)
MN0000994823
YYYYMMDD

tvseries
  • mpaa
  • adult
  • length
  • toneid
  • moodid
  • themeid
  • genreid
  • subgenreid
  • editorialrating

PG13
true (amgvideo endpoint)
120 (minutes)
D++1304 (table) (amgvideo endpoint)
D++2030 (table) (amgvideo endpoint)
D++1431 (table) (amgvideo endpoint)
D+++649 (look up) (amgvideo endpoint)
D++1376 (look up) (amgvideo endpoint)
1 to 10 (amgvideo endpoint)

format No Format of the returned data: json or xml. The default is JSON.
include No Additional data to include in each result returned. To include cast members in movie results, for example, specify include=movie:cast. For multiple includes, separate the values with commas like this: include=movie:moods,crew. For multiple entity types, specify separate parameters like this: include=movie:cast,crew&include=tvseries:cast,crew. A request can contain up to 20 include values.
For endpointEntitytypeYou can include these results . . .
music ♫album
  • All ♫
  • ClassicalReview ♫
  • Credits ♫
  • Images ♫
  • Moods ♫
  • PrimaryReview ♫
  • Releases ♫
  • Similar ♫
  • Styles ♫
  • Themes ♫
  • Tracks ♫
music ♫song
  • All ♫
  • Appearances ♫
  • Moods ♫
  • Review ♫
  • Styles ♫
  • Themes ♫
music ♫artist
  • 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 日movie
  • All 日
  • Cast 日
  • Crew 日
  • Images 日
  • Keywords 日
  • Moods 日
  • Related 日
  • Releases 日
  • Review 日
  • Similar 日
  • Synopsis 日
  • Themes 日
  • Tones 日
  • Types 日
  • Videos 日
amgvideo 日tvseries
  • All 日
  • Cast 日
  • Crew 日
  • Images 日
  • Keywords 日
  • Moods 日
  • Related 日
  • Releases 日
  • Review 日
  • Similar 日
  • Synopsis 日
  • Themes 日
  • Tones 日
  • Types 日
  • Videos 日
video ⊑⊒movie
  • All ⊑⊒
  • Awards ⊑⊒
  • Cast ⊑⊒
  • Crew ⊑⊒
  • Event ⊑⊒
  • Images ⊑⊒
  • Keywords ⊑⊒
  • Review ⊑⊒
  • Synopsis ⊑⊒
  • Themes ⊑⊒
  • Tones ⊑⊒
video ⊑⊒tvseries
  • All ⊑⊒
  • Awards ⊑⊒
  • Cast ⊑⊒
  • Crew ⊑⊒
  • Images ⊑⊒
  • Keywords ⊑⊒
  • Review ⊑⊒
  • Seasons ⊑⊒
  • Synopsis ⊑⊒
  • Themes ⊑⊒
  • Tones ⊑⊒
video ⊑⊒onetimeonly
  • All ⊑⊒
  • Awards ⊑⊒
  • Cast ⊑⊒
  • Crew ⊑⊒
  • Event ⊑⊒
  • Images ⊑⊒
  • Keywords ⊑⊒
  • Review ⊑⊒
  • Synopsis ⊑⊒
  • Themes ⊑⊒
  • Tones ⊑⊒

* Notice: Do not include Credits or Factsheets in a production application. They are currently in alpha release and responses may change.

language No Language of the response data. This request supports only en (English).
offset No Number of items at the start of the returned list to skip. The default is zero.

Use offset and size to paginate the response.

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 FilterBrowse Version 2.0

ResponseTypeDescription
facetCounts facetCounts [ ] Number of results available to be returned in each genre or entity type, as requested by the facet parameter.
results result [ ] The search results listed in order of popularity and similarity and the filters specified in the request.
totalResultCounts Integer Total number of results found.

Response Example 1

Top search result for West Coast blues musicians. Requested with http://api.rovicorp.com/search/v2/music/
filterbrowse?apikey=apikey&sig=sig&entitytype=artist&facet=type&filter=subgenreid:MA0000012030&size=1&
format=xml.
<searchResponse id="tul1cstadgwapp02:gwy:2jpe">
  <controlSet>
    <status>ok</status>
    <code>200</code>
    <messages/>
  </controlSet>
  <results>
    <result>
      <type>artist</type>
      <relevance>
        <code>Score</code>
        <name>1</name>
      </relevance>
      <id>MN0000301955</id>
      <messages i:nil="true"/>
      <name>
        <ids>
          <amgClassicalId>Q 441350</amgClassicalId>
          <amgMovieId>P 25323</amgMovieId>
          <amgPopId>P 344</amgPopId>
          <cosmoId i:nil="true"/>
          <nameId>MN0000301955</nameId>
        </ids>
        <name>Lowell Fulson</name>
        <isGroup>false</isGroup>
        <primaryMedia>Popular</primaryMedia>
        <musicGenres>
          <Genre>
            <id>MA0000002467</id>
            <name>Blues</name>
            <weight>10</weight>
          </Genre>
          <Genre>
            <id>MA0000002809</id>
            <name>R&amp;B</name>
            <weight>7</weight>
          </Genre>
        </musicGenres>
        <movieGenres>
          <Genre>
            <id>D 1776</id>
            <name>Music [nf]</name>
            <weight>99</weight>
          </Genre>
        </movieGenres>
        <active xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
          <a:string>1940s</a:string>
          <a:string>1950s</a:string>
          <a:string>1960s</a:string>
          <a:string>1970s</a:string>
          <a:string>1980s</a:string>
          <a:string>1990s</a:string>
        </active>
        <birth>
          <date>1921-03-31</date>
          <place>Tulsa, OK</place>
        </birth>
        <death>
          <date>1999-03-06</date>
          <place>Los Angeles, CA</place>
        </death>
        <country>United States of America</country>
        <period/>
        <headlineBio>One of the founders of West Coast America blues, recorded steadily from the &apos;40s through &apos;90s.</headlineBio>
        <classicalBio i:nil="true"/>
        <classicalBioUri i:nil="true"/>
        <discography i:nil="true"/>
        <discographyUri>http://api.rovicorp.com/v1/name/discography?format=xml&amp;apikey=4p1k3y&amp;nameid=MN0000301955</discographyUri>
        <filmography i:nil="true"/>
        <filmographyUri>http://api.rovicorp.com/v1/name/filmography?format=xml&amp;apikey=4p1k3y&amp;nameid=MN0000301955</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=4p1k3y&amp;nameid=MN0000301955</imagesUri>
        <influencers i:nil="true"/>
        <influencersUri>http://api.rovicorp.com/v1/name/influencers?format=xml&amp;apikey=4p1k3y&amp;nameid=MN0000301955</influencersUri>
        <similars i:nil="true"/>
        <similarsUri>http://api.rovicorp.com/v1/name/similars?format=xml&amp;apikey=4p1k3y&amp;nameid=MN0000301955</similarsUri>
        <moods i:nil="true"/>
        <moodsUri>http://api.rovicorp.com/v1/name/moods?format=xml&amp;apikey=4p1k3y&amp;nameid=MN0000301955</moodsUri>
        <movieBio i:nil="true"/>
        <movieBioUri i:nil="true"/>
        <musicBio i:nil="true"/>
        <musicBioUri>http://api.rovicorp.com/v1/name/musicBio?format=xml&amp;apikey=4p1k3y&amp;nameid=MN0000301955</musicBioUri>
        <musicCredits i:nil="true"/>
        <musicCreditsUri>http://api.rovicorp.com/v1/name/musicCredits?format=xml&amp;apikey=4p1k3y&amp;nameid=MN0000301955</musicCreditsUri>
        <songs i:nil="true"/>
        <songsUri>http://api.rovicorp.com/v1/name/songs?format=xml&amp;apikey=4p1k3y&amp;nameid=MN0000301955</songsUri>
        <musicStyles i:nil="true"/>
        <musicStylesUri>http://api.rovicorp.com/v1/name/musicStyles?format=xml&amp;apikey=4p1k3y&amp;nameid=MN0000301955</musicStylesUri>
        <themes i:nil="true"/>
        <themesUri>http://api.rovicorp.com/v1/name/themes?format=xml&amp;apikey=4p1k3y&amp;nameid=MN0000301955</themesUri>
        <videos i:nil="true"/>
        <videosUri i:nil="true"/>
        <movieStyles i:nil="true"/>
        <movieStylesUri>http://api.rovicorp.com/v1/name/movieStyles?format=xml&amp;apikey=4p1k3y&amp;nameid=MN0000301955</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=4p1k3y&amp;nameid=MN0000301955</associatedWithUri>
        <collaboratorWith i:nil="true"/>
        <collaboratorWithUri>http://api.rovicorp.com/v1/name/collaboratorWith?format=xml&amp;apikey=4p1k3y&amp;nameid=MN0000301955</collaboratorWithUri>
        <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 i:nil="true"/>
        <schedule i:nil="true"/>
        <scheduleUri i:nil="true"/>
        <credits i:nil="true"/>
        <creditsUri i:nil="true"/>
      </name>
    </result>
  </results>
  <totalResultCounts>84</totalResultCounts>
  <facetCounts xmlns="com.rovicorp.snrservice" name="type">
    <facetCount>
      <name>Artist</name>
      <count>84</count>
    </facetCount>
  </facetCounts>
</searchResponse>

Response Example 2

Top search result for songs in the yodeling subgenre. Requested with http://api.rovicorp.com/search/v2/music/
filterbrowse?apikey=apikey&sig=sig&entitytype=song&facet=type&facet=genre&size=1&
filter=subgenreid:MA0000012228.
{
   "searchResponse":{
      "meta:id":"tul1cpgpsrapp2:gwy:1ffuk",
      "controlSet":{
         "status":"ok",
         "code":200,
         "messages":[
            ""
         ]
      },
      "results":[
         {
            "type":"song",
            "relevance":[
               {
                  "code":"Score",
                  "value":1.0197085
               }
            ],
            "id":"MT0010998194",
            "messages":null,
            "song":{
               "ids":{
                  "amgClassicalTrackId":null,
                  "amgPopTrackId":"T 3407878",
                  "isrcId":"USBB19601038",
                  "muzeId":null,
                  "trackId":"MT0010998194"
               },
               "title":"Standin' on the Corner",
               "primaryArtists":[
                  {
                     "id":"MN0000234518",
                     "name":"Louis Armstrong"
                  },
                  {
                     "id":"MN0000120323",
                     "name":"Duke Ellington"
                  }
               ],
               "isPick":false,
               "genres":[
                  {
                     "id":"MA0000002532",
                     "name":"Country",
                     "weight":9
                  }
               ],
               "appearances":null,
               "appearancesUri":"http://api.rovicorp.com/v1/song/appearances?format=json&apikey=4p1k3y&trackId=MT0010998194",
               "moods":null,
               "moodsUri":"http://api.rovicorp.com/v1/song/moods?format=json&apikey=4p1k3y&trackId=MT0010998194",
               "review":null,
               "reviewUri":"",
               "styles":null,
               "stylesUri":"http://api.rovicorp.com/v1/song/styles?format=json&apikey=4p1k3y&trackId=MT0010998194",
               "themes":null,
               "themesUri":"http://api.rovicorp.com/v1/song/themes?format=json&apikey=4p1k3y&trackId=MT0010998194",
               "sample":null,
               "sampleUri":"http://api.rovicorp.com/v1/song/sample?format=json&apikey=4p1k3y&trackId=MT0010998194"
            }
         }
      ],
      "totalResultCounts":196,
      "facetCounts":[
         {
            "name":"type",
            "facetCount":[
               {
                  "name":"Track",
                  "count":196
               }
            ]
         },
         {
            "name":"genre",
            "facetCount":[
               {
                  "id":"MA0000002532",
                  "name":"Country",
                  "count":196
               },
               {
                  "id":"MA0000002592",
                  "name":"Folk",
                  "count":1
               },
               {
                  "id":"MA0000002613",
                  "name":"Pop/Rock",
                  "count":2
               }
            ]
         }
      ]
   }
}
}

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/SnR/V2/FilterBrowse"
Personal tools