V1.Metadata.SearchService:FilterBrowse

Jump to: navigation, search

FilterBrowse

Locates content in select areas of Rovi Cloud Services based on field-level criteria and returns a JSON response with 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 string.

Syntax

filterbrowse?entitytype=entitytype&facet=facet&apikey=apikey&sig=sig [&filter=filter] [&include=include] [&provider=provider] [&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/v1/filterbrowse?apikey=apikey&sig=sig&entitytype=album&facet=genre&
filter=genreid%3dMA0000002613&filter=releasedate%3E20101224&filter=releasedate%3C20110101&
size=10

Request Example 2

Find artists active in contemporary blues during the 2000s.
http://api.rovicorp.com/search/v1/filterbrowse?apikey=apikey&sig=sig&entitytype=artist&facet=type&
filter=subgenreid%3dMA0000002960&filter=decade%3d2000s

Request Example 3

Find spy films released in 2009.
http://api.rovicorp.com/search/v1/filterbrowse?apikey=apikey&sig=sig&entitytype=movie&facet=type&
filter=genreid%3dD+++515&filter=releasedate%3E%3D20100101&filter=releasedate%3C20110101

Request Example 4

Find songs released in 2008 in the yodeling subgenre and return a list of the releases they appeared on.
http://api.rovicorp.com/search/v1/filterbrowse?apikey=apikey&sig=sig&entitytype=song&facet=genre&
filter=subgenreid%3dMA0000012228&filter=releasedate%3E%3D20080101&
filter=releasedate%3C20090101&include=song:appearances

Request Parameters

ParameterRequiredDescription
apikey Yes Access code that authorizes your request for data from Rovi.
entitytype Yes Type of content to search for.
To search in this area . . .   Specify this entitytype.
albumsalbum
moviesmovie
TV seriestvseries
popular songssong
people involved in musicartist
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. 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.
facet Yes 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.
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.

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. Note: Operators within the parameter value must be specified URL-encoded.

Examples:

  • Specify filter=length%3c120 to return only movies less than 120 minutes long.
  • Specify filter=genreid%3dMA0000002467 to limit the results to the blues genre.
  • Specify filter=releasedate%3E19991231 for releases in the year 2000 or later.
  • Specify filter=decade%3D1990s to limit the results to artists active in the 1990s.
  • Specify filter=mpaa%3dG%7Cmpaa%3dPG%7cmpaa%3dPG13 to return movies rated G, PG, or PG13.
  • Specify filter=subgenreid%3dD+++509%7Csubgenreid%3dD+++510 to return action thriller or martial arts movies.

The selection operators include:

OperatorURL EncodingMeaning
=  %3DIs equal to.
!=  %21%3DIs not equal to.
<  %3CIs less than.
<=  %3C%3DIs less than or equal to.
>  %3EIs greater than.
>=  %3E%3DIs greater than or equal to.
|  %7COr.

URL-encoded characters are not case-sensitive.

For the And operation, specify another filter parameter like this: filter=releasedate%3E%3D20070101&filter=releasedate%3C20080101. 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 select these fields . . .Example or Format
artist
  • decade
  • genreId
  • subGenreId

2000s
MA0000002467
MA0000002517

song
  • genreId
  • subGenreId
  • performerId
  • releaseDate

MA0000002467
MA0000002517
MN0000994823
YYYYMMDD

movie
  • mpaa
  • length
  • genreId
  • subGenreId
  • releaseDate

PG13
120 (minutes, integer)
D+++649
D++1376
YYYYMMDD

tvseries
  • length
  • genreId
  • subGenreId
  • releaseDate

120 (minutes, integer)
D+++649
D++1376
YYYYMMDD

album
  • genreId
  • subGenreId
  • performerId
  • releaseDate

MA0000002467
MA0000002517
MN0000994823
YYYYMMDD

include No Additional data to include in each response. To include moods in movie results, for example, specify include=movie:moods. For multiple includes, separate the values with commas like this: include=movie:moods,styles. For multiple entity types, specify separate parameters like this: include=movie:moods,tones&include=tvseries:moods,tones. A request can contain up to 100 include values.
For this entity type . . .You can include these results . . .
album
  • All
  • ClassicalReview
  • Credits
  • Images
  • Moods
  • PrimaryReview
  • Releases
  • Similar
  • Styles
  • Themes
  • Tracks
artist
  • All
  • Aliases
  • AssociatedWith
  • ClassicalBio
  • CollaboratorWith
  • Compositions
  • Contemporaries
  • Discography
  • Filmography
  • Followers
  • GroupMembers
  • Images
  • Influencers
  • MemberOf
  • Moods
  • MovieBio
  • MovieStyles
  • MusicBio
  • MusicCredits
  • MusicStyles
  • Similars
  • Songs
  • Themes
  • Videos
movie
  • All
  • Cast
  • Crew
  • Images
  • Keywords
  • Moods
  • Related
  • Releases
  • Review
  • Similar
  • Synopsis
  • Themes
  • Tones
  • Types
  • Videos
song
  • All
  • Appearances
  • Moods
  • Review
  • Styles
  • Themes
tvseries
  • All
  • Cast
  • Crew
  • Images
  • Keywords
  • Moods
  • Related
  • Releases
  • Review
  • Similar
  • Synopsis
  • Themes
  • Tones
  • Types
  • Videos
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.

provider No Not currently used; reserved for future use.
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

ResponseTypeDescription
album Album Album/Info response, returned only for a request with an entity type of album.
facetcounts FacetCounts [ ] Number of results available to be returned in each genre or entity type, as requested by the facet parameter.
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 Movie/Info response, returned only for a search request with an entitytype of movie or tvseries.
name Name Name/Info response, returned only for a search request with an entity type 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 Song/Info response, returned only for a request with an entity type of song.
type String Entity type of a search result.

Response Example 1

Top search result for West Coast blues musicians. Requested with http://api.rovicorp.com/search/v1/filterbrowse?entitytype=artist&facet=type&filter=subgenreid%3dMA0000012030&size=1&apikey=apikey&sig=sig.
{"searchResponse": {
  "id": "tul1cstadgwapp02:gwy:c0t",
  "controlSet": {
    "status": "ok",
    "code": 200,
    "messages": [""]
  },
  "results": [
    {
    "type": "artist",
    "relevance": [
      {
      "code": "Score",
      "name": 1.1307472
    }],
    "provider": "rovimusic",
    "id": "MN0000301955",
    "messages": null,
    "name": {
      "ids": {
        "a:amgClassicalId": "Q   441350",
        "a:amgMovieId": "P 25323",
        "a:amgPopId": "P      344",
        "a:nameId": "MN0000301955"
      },
      "name": "Lowell Fulson",
      "isGroup": false,
      "primaryMedia": "Popular",
      "musicGenres": {
        "Genre": {
          "id": "MA0000002467",
          "name": "Blues",
          "weight": 10
        },
        "Genre": {
          "id": "MA0000002809",
          "name": "R&B",
          "weight": 7
        }
      },
      "movieGenres": {
        "Genre": {
          "id": "D  1776",
          "name": "Music [nf]",
          "weight": 5
        }
      },
      "active": {
        "a:string": "1940s",
        "a:string": "1950s",
        "a:string": "1960s",
        "a:string": "1970s",
        "a:string": "1980s",
        "a:string": "1990s"
      },
      "birth": {
        "date": "1921-03-31",
        "place": "Tulsa, OK"
      },
      "death": {
        "date": "1999-03-06",
        "place": "Los Angeles, CA"
      },
      "country": "United States of America",
      "period": "",
      "headlineBio": "One of the founders of West Coast America blues, recorded steadily from the '40s through '90s.",
      "classicalBio": null,
      "classicalBioUri": null,
      "discography": null,
      "discographyUri": "http://api.rovicorp.com/v1/name/discography?format=xml&apikey=4p1k3y&nameId=MN0000301955",
      "filmography": null,
      "filmographyUri": "http://api.rovicorp.com/v1/name/filmography?format=xml&apikey=4p1k3y&nameId=MN0000301955",
      "followers": null,
      "followersUri": "http://api.rovicorp.com/v1/name/followers?format=xml&apikey=4p1k3y&nameId=MN0000301955",
      "groupMembers": null,
      "groupMembersUri": null,
      "memberOf": null,
      "memberOfUri": null,
      "images": null,
      "imagesUri": "http://api.rovicorp.com/v1/name/images?format=xml&apikey=4p1k3y&nameId=MN0000301955",
      "influencers": null,
      "influencersUri": null,
      "moods": null,
      "moodsUri": "http://api.rovicorp.com/v1/name/moods?format=xml&apikey=4p1k3y&nameId=MN0000301955",
      "movieBio": null,
      "movieBioUri": null,
      "musicBio": null,
      "musicBioUri": "http://api.rovicorp.com/v1/name/musicBio?format=xml&apikey=4p1k3y&nameId=MN0000301955",
      "musicCredits": null,
      "musicCreditsUri": "http://api.rovicorp.com/v1/name/musicCredits?format=xml&apikey=4p1k3y&nameId=MN0000301955",
      "songs": null,
      "songsUri": "http://api.rovicorp.com/v1/name/songs?format=xml&apikey=4p1k3y&nameId=MN0000301955",
      "musicStyles": null,
      "musicStylesUri": "http://api.rovicorp.com/v1/name/musicStyles?format=xml&apikey=4p1k3y&nameId=MN0000301955",
      "themes": null,
      "themesUri": "http://api.rovicorp.com/v1/name/themes?format=xml&apikey=4p1k3y&nameId=MN0000301955",
      "videos": null,
      "videosUri": null,
      "movieStyles": null,
      "movieStylesUri": "http://api.rovicorp.com/v1/name/movieStyles?format=xml&apikey=4p1k3y&nameId=MN0000301955",
      "contemporaries": null,
      "contemporariesUri": null,
      "associatedWith": null,
      "associatedWithUri": "http://api.rovicorp.com/v1/name/associatedwith?format=xml&apikey=4p1k3y&nameId=MN0000301955",
      "collaboratorWith": null,
      "collaboratorWithUri": "http://api.rovicorp.com/v1/name/collaboratorWith?format=xml&apikey=4p1k3y&nameId=MN0000301955",
      "compositions": null,
      "compositionsUri": null
    }
  }],
  "facetCounts": [
    {
    "name": "type",
    "facetCount": [
      {
      "name": "Artist",
      "count": 84
    }]
  }]
}
}

Response Example 2

Top search result for songs in the yodeling subgenre. Requested with http://api.rovicorp.com/search/v1/filterbrowse?entitytype=song&facet=type&facet=genre&filter=subgenreid%3dMA0000012228&size=1&apikey=apikey&sig=sig.
{"searchResponse": {
  "id": "tul1cstadgwapp01:gwy:c9g",
  "controlSet": {
    "status": "ok",
    "code": 200,
    "messages": [""]
  },
  "results": [
    {
    "type": "song",
    "relevance": [
      {
      "code": "Score",
      "name": 0.70710677
    }],
    "provider": "rovimusic",
    "id": "MT0012692510",
    "messages": null,
    "song": {
      "ids": {
        "a:amgPopTrackId": "T  5157047",
        "a:trackId": "MT0012692510"
      },
      "title": "Mother, the Queen of My Heart",
      "primaryArtists": {
        "AlbumArtist": {
          "id": "MN0000343852",
          "name": "Jimmie Rodgers"
        }
      },
      "isPick": true,
      "genres": [
        {
        "Genre": {
          "id": "MA0000002532",
          "name": "Country",
          "weight": 9
        }
      }],
      "appearances": null,
      "appearancesUri": "http://api.rovicorp.com/v1/song/appearances?format=xml&apikey=4p1k3y&trackId=MT0012692510",
      "moods": null,
      "moodsUri": "http://api.rovicorp.com/v1/song/moods?format=xml&apikey=4p1k3y&trackId=MT0012692510",
      "review": null,
      "reviewUri": null,
      "styles": null,
      "stylesUri": "http://api.rovicorp.com/v1/song/styles?format=xml&apikey=4p1k3y&trackId=MT0012692510",
      "themes": null,
      "themesUri": "http://api.rovicorp.com/v1/song/themes?format=xml&apikey=4p1k3y&trackId=MT0012692510"
    }
  }],
  "facetCounts": [
    {
    "name": "genre",
    "facetCount": [
      {
      "id": "MA0000002944",
      "name": "Children's",
      "count": 1
    },
    {
      "id": "MA0000002532",
      "name": "Country",
      "count": 210
    },
    {
      "id": "MA0000002613",
      "name": "Pop/Rock",
      "count": 1
    },
    {
      "id": "MA0000002592",
      "name": "Folk",
      "count": 3
    }]
  },
  {
    "name": "type",
    "facetCount": [
      {
      "name": "Track",
      "count": 210
    }]
  }]
}
}

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:FilterBrowse"
Personal tools