V1.Metadata.SearchService:FullSearch

Jump to: navigation, search

Search

Searches titles for a string in select areas of Rovi Cloud Services and returns a JSON response with results listed in order of popularity and similarity to the search query.

Syntax

search?query=query&entitytype=entitytype&facet=facet&apikey=apikey&sig=sig [&filter=filter] [&include=include] [&provider=provider] [&offset=offset] [&size=size]

Request Example 1

Find the TV series The Office and return a list of movies and TV series that are similar.
http://api.rovicorp.com/search/v1/search?apikey=apikey&sig=sig&query=the+office&
entitytype=tvseries&facet=type&size=1&include=movie:similar

Request Example 2

Ask what groups the artist Eric Clapton has been a member of.
http://api.rovicorp.com/search/v1/search?apikey=apikey&sig=sig&query=eric+clapton&
entitytype=artist&facet=type&size=1&include=artist:memberof

Request Example 3

Get ten pop/rock songs released in the year 2010 with the word love in the title and show the number of those songs in all genres.
http://api.rovicorp.com/search/v1/search?apikey=apikey&sig=sig&query=love&entitytype=song&
facet=genre&filter=genreid%3dMA0000002613&filter=releasedate%3e%3d20090101&
filter=releasedate%3c20100101&size=10

Request Example 4

Get the next ten songs in the list.
http://api.rovicorp.com/search/v1/search?apikey=apikey&sig=sig&query=love&entitytype=song&
facet=genre&filter=genreid%3dMA0000002613&filter=releasedate%3e%3d20090101&
filter=releasedate%3c20100101&size=10&offset=10

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.
query Yes The URL-encoded search string. Spaces may be replaced with plus (+) or percent20 (%20) symbols. The case of characters does not affect the results (search is not case-sensitive).
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 Search

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

Response to the search for the song Pacific Pride. Requested with http://api.rovicorp.com/search/v1/search?query=pacific+pride&entitytype=song&facet=type&apikey=apikey&sig=sig.
{"searchResponse": {
  "id": "tul1cstadgwapp01:gwy:bip",
  "controlSet": {
    "status": "ok",
    "code": 200,
    "messages": [""]
  },
  "results": [
    {
    "type": "song",
    "relevance": [
      {
      "code": "Score",
      "name": 1.118034
    }],
    "provider": "rovimusic",
    "id": "MT0039727343",
    "messages": null,
    "song": {
      "ids": {
        "a:amgPopTrackId": "T 22175635",
        "a:muzeId": 29252795,
        "a:trackId": "MT0039727343"
      },
      "title": "Pacific Pride",
      "primaryArtists": {
        "AlbumArtist": {
          "id": "MN0002497794",
          "name": "No Joy"
        }
      },
      "isPick": true,
      "genres": null,
      "appearances": null,
      "appearancesUri": "http://api.rovicorp.com/v1/song/appearances?format=xml&apikey=4p1k3y&trackId=MT0039727343",
      "moods": null,
      "moodsUri": null,
      "review": null,
      "reviewUri": null,
      "styles": null,
      "stylesUri": null,
      "themes": null,
      "themesUri": null
    }
  },
  {
    "type": "song",
    "relevance": [
      {
      "code": "Score",
      "name": 0.17888544
    }],
    "provider": "rovimusic",
    "id": "MT0039957778",
    "messages": null,
    "song": {
      "ids": {
        "a:amgPopTrackId": "T 22390529",
        "a:isrcId": "GBKPL0711643",
        "a:muzeId": 29564317,
        "a:trackId": "MT0039957778"
      },
      "title": "Pacific Parade",
      "primaryArtists": {
        "AlbumArtist": {
          "id": "MN0000875458",
          "name": "Larry Killip"
        }
      },
      "isPick": false,
      "genres": null,
      "appearances": null,
      "appearancesUri": "http://api.rovicorp.com/v1/song/appearances?format=xml&apikey=4p1k3y&trackId=MT0039957778",
      "moods": null,
      "moodsUri": null,
      "review": null,
      "reviewUri": null,
      "styles": null,
      "stylesUri": null,
      "themes": null,
      "themesUri": null
    }
  }],
  "facetCounts": [
    {
    "name": "type",
    "facetCount": [
      {
      "name": "Track",
      "count": 2
    }]
  }]
}
}

Response Example 2

Response to the search for the cellist Janos Starker. Requested with http://api.rovicorp.com/search/v1/search?query=janos+starker&entitytype=artist&facet=type&apikey=apikey&sig=sig.
{"searchResponse": {
  "id": "tul1cstadgwapp01:gwy:bib",
  "controlSet": {
    "status": "ok",
    "code": 200,
    "messages": [""]
  },
  "results": [
    {
    "type": "artist",
    "relevance": [
      {
      "code": "Score",
      "name": 1.2935823
    }],
    "provider": "rovimusic",
    "id": "MN0000697600",
    "messages": null,
    "name": {
      "ids": {
        "a:amgClassicalId": "Q    54486",
        "a:amgPopId": "P   199858",
        "a:nameId": "MN0000697600"
      },
      "name": "Janos Starker",
      "isGroup": false,
      "primaryMedia": "Classical",
      "musicGenres": {
        "Genre": {
          "id": "MA0000002521",
          "name": "Classical",
          "weight": 10
        }
      },
      "movieGenres": null,
      "active": {
        "a:string": "1970s",
        "a:string": "1980s",
        "a:string": "1990s",
        "a:string": "2000s"
      },
      "birth": {
        "date": "1924-07-05",
        "place": "Budapest, Hungary"
      },
      "death": {
        "date": "",
        "place": ""
      },
      "country": "Hungary",
      "period": "Romantic",
      "headlineBio": "",
      "classicalBio": null,
      "classicalBioUri": "http://api.rovicorp.com/v1/name/classicalbio?format=xml&apikey=4p1k3y&nameId=MN0000697600",
      "discography": null,
      "discographyUri": "http://api.rovicorp.com/v1/name/discography?format=xml&apikey=4p1k3y&nameId=MN0000697600",
      "filmography": null,
      "filmographyUri": null,
      "followers": null,
      "followersUri": null,
      "groupMembers": null,
      "groupMembersUri": null,
      "memberOf": null,
      "memberOfUri": null,
      "images": null,
      "imagesUri": "http://api.rovicorp.com/v1/name/images?format=xml&apikey=4p1k3y&nameId=MN0000697600",
      "influencers": null,
      "influencersUri": null,
      "moods": null,
      "moodsUri": null,
      "movieBio": null,
      "movieBioUri": null,
      "musicBio": null,
      "musicBioUri": "http://api.rovicorp.com/v1/name/musicBio?format=xml&apikey=4p1k3y&nameId=MN0000697600",
      "musicCredits": null,
      "musicCreditsUri": "http://api.rovicorp.com/v1/name/musicCredits?format=xml&apikey=4p1k3y&nameId=MN0000697600",
      "songs": null,
      "songsUri": "http://api.rovicorp.com/v1/name/songs?format=xml&apikey=4p1k3y&nameId=MN0000697600",
      "musicStyles": null,
      "musicStylesUri": "http://api.rovicorp.com/v1/name/musicStyles?format=xml&apikey=4p1k3y&nameId=MN0000697600",
      "themes": null,
      "themesUri": null,
      "videos": null,
      "videosUri": null,
      "movieStyles": null,
      "movieStylesUri": null,
      "contemporaries": null,
      "contemporariesUri": null,
      "associatedWith": null,
      "associatedWithUri": null,
      "collaboratorWith": null,
      "collaboratorWithUri": "http://api.rovicorp.com/v1/name/collaboratorWith?format=xml&apikey=4p1k3y&nameId=MN0000697600",
      "compositions": null,
      "compositionsUri": null
    }
  }],
  "facetCounts": [
    {
    "name": "type",
    "facetCount": [
      {
      "name": "Artist",
      "count": 1
    }]
  }]
}
}

Response Example 3

Response to the search for the movie Avatar and the request for a list of DVD releases. Requested with http://api.rovicorp.com/search/v1/search?query=avatar&entitytype=movie&facet=type&include=movie:releases&size=1&apikey=apikey&sig=sig.
{"searchResponse": {
  "id": "tul1cstadgwapp02:gwy:b9w",
  "controlSet": {
    "status": "ok",
    "code": 200,
    "messages": [""]
  },
  "results": [
    {
    "type": "movie",
    "relevance": [
      {
      "code": "Score",
      "name": 1.4139781
    }],
    "provider": "amgvideo",
    "id": "V   352199",
    "messages": null,
    "movie": {
      "ids": {
        "movieId": "V   352199"
      },
      "title": "Avatar",
      "releaseYear": 2009,
      "rating": 6,
      "duration": 160,
      "directors": [
        {
        "id": "P 10397",
        "name": "James Cameron"
      }],
      "countries": ["USA"],
      "mpaa": "PG13",
      "flags": ["Profanity",
      "Sexual Situations",
      "War Violence",
      "Smoking"],
      "genres": [
        {
        "id": "D   652",
        "name": "Science Fiction",
        "weight": 5
      }],
      "attributes": ["High Production Values",
      "High Budget"],
      "cast": null,
      "castUri": "http://api.rovicorp.com/v1/movie/cast?format=xml&apikey=4p1k3y&movieid=V+++352199",
      "crew": null,
      "crewUri": "http://api.rovicorp.com/v1/movie/crew?format=xml&apikey=4p1k3y&movieid=V+++352199",
      "images": null,
      "imagesUri": "http://api.rovicorp.com/v1/movie/images?format=xml&apikey=4p1k3y&movieid=V+++352199",
      "moods": null,
      "moodsUri": "http://api.rovicorp.com/v1/movie/moods?format=xml&apikey=4p1k3y&movieid=V+++352199",
      "keywords": null,
      "keywordsUri": "http://api.rovicorp.com/v1/movie/keywords?format=xml&apikey=4p1k3y&movieid=V+++352199",
      "related": null,
      "relatedUri": null,
      "releases": [
        {
        "ids": {
          "releaseId": "E247882"
        },
        "title": "Avatar [Extended Collector's Edition] [3 Discs]",
        "studio": "20th Century Fox",
        "rating": 6,
        "formats": ["DVD"],
        "year": "2010 11 16",
        "hasCommentary": true,
        "isPurchasable": true
      },
      {
        "ids": {
          "releaseId": "E247888"
        },
        "title": "Avatar [Extended Collector's Edition] [3 Discs] [Blu-ray]",
        "studio": "20th Century Fox",
        "rating": 6,
        "formats": ["Blu-ray"],
        "year": "2010 11 16",
        "hasCommentary": true,
        "isPurchasable": true
      },
      {
        "ids": {
          "releaseId": "E248895"
        },
        "title": "Avatar [Extended Collector's Edition] [3 Discs] [Blu-ray]",
        "studio": "20th Century Fox Home Entertainment (Canadian)",
        "rating": 6,
        "formats": ["Blu-ray"],
        "year": "2010 11 16",
        "hasCommentary": true,
        "isPurchasable": true
      },
      {
        "ids": {
          "releaseId": "E237815"
        },
        "title": "Avatar",
        "studio": "20th Century Fox",
        "rating": 6,
        "formats": ["DVD"],
        "year": "2010 04 22",
        "hasCommentary": true,
        "isPurchasable": true
      },
      {
        "ids": {
          "releaseId": "E237816"
        },
        "title": "Avatar [2 Discs] [Blu-ray/DVD]",
        "studio": "20th Century Fox",
        "rating": 6,
        "formats": ["Blu-ray",
        "DVD"],
        "year": "2010 04 22",
        "hasCommentary": true,
        "isPurchasable": true
      },
      {
        "ids": {
          "releaseId": "E237928"
        },
        "title": "Avatar [Bilingual]",
        "studio": "20th Century Fox (Canadian)",
        "rating": 6,
        "formats": ["DVD"],
        "year": "2010 04 22",
        "hasCommentary": true,
        "isPurchasable": true
      },
      {
        "ids": {
          "releaseId": "E241860"
        },
        "title": "Avatar [Blu-ray]",
        "studio": "20th Century Fox Home Entertainment",
        "rating": 6,
        "formats": ["Blu-ray"],
        "year": "",
        "hasCommentary": true,
        "isPurchasable": true
      },
      {
        "ids": {
          "releaseId": "E237927"
        },
        "title": "Avatar [2 Discs] [Bilingual] [Blu-ray/DVD]",
        "studio": "20th Century Fox (Canadian)",
        "rating": 6,
        "formats": ["Blu-ray",
        "DVD"],
        "year": "2010 04 22",
        "hasCommentary": true,
        "isPurchasable": true
      },
      {
        "ids": {
          "releaseId": "E248894"
        },
        "title": "Avatar [Extended Collector's Edition] [3 Discs]",
        "studio": "20th Century Fox Home Entertainment (Canadian)",
        "rating": 6,
        "formats": ["DVD"],
        "year": "2010 11 16",
        "hasCommentary": true,
        "isPurchasable": true
      }],
      "releasesUri": "http://api.rovicorp.com/v1/movie/releases?format=xml&apikey=4p1k3y&movieid=V+++352199",
      "review": null,
      "reviewUri": "http://api.rovicorp.com/v1/movie/review?format=xml&apikey=4p1k3y&movieid=V+++352199",
      "similar": null,
      "similarUri": "http://api.rovicorp.com/v1/movie/similar?format=xml&apikey=4p1k3y&movieid=V+++352199",
      "synopsis": null,
      "synopsisUri": "http://api.rovicorp.com/v1/movie/synopsis?format=xml&apikey=4p1k3y&movieid=V+++352199",
      "themes": null,
      "themesUri": "http://api.rovicorp.com/v1/movie/themes?format=xml&apikey=4p1k3y&movieid=V+++352199",
      "tones": null,
      "tonesUri": "http://api.rovicorp.com/v1/movie/tones?format=xml&apikey=4p1k3y&movieid=V+++352199",
      "types": null,
      "typesUri": "http://api.rovicorp.com/v1/movie/types?format=xml&apikey=4p1k3y&movieid=V+++352199",
      "videos": null,
      "videosUri": "http://api.rovicorp.com/v1/movie/videos?format=xml&apikey=4p1k3y&movieid=V+++352199",
      "studio": ""
    }
  }],
  "facetCounts": [
    {
    "name": "type",
    "facetCount": [
      {
      "name": "Movie",
      "count": 3
    }]
  }]
}
}

Response Example 4

The first pop/rock song out of 136 that are titled My Way. Requested with http://api.rovicorp.com/search/v1/search?query=my+way&entitytype=song&facet=type&facet=genre&filter=genreid%3dMA0000002613&size=1&apikey=apikey&sig=sig.
{"searchResponse": {
  "id": "tul1cstadgwapp01:gwy:bi8",
  "controlSet": {
    "status": "ok",
    "code": 200,
    "messages": [""]
  },
  "results": [
    {
    "type": "song",
    "relevance": [
      {
      "code": "Score",
      "name": 1.118034
    }],
    "provider": "rovimusic",
    "id": "MT0034729453",
    "messages": null,
    "song": {
      "ids": {
        "a:amgPopTrackId": "T  2631992",
        "a:trackId": "MT0034729453"
      },
      "title": "My Way",
      "primaryArtists": {
        "AlbumArtist": {
          "id": "MN0000180228",
          "name": "Elvis Presley"
        },
        "AlbumArtist": {
          "id": "MN0000745915",
          "name": "Paul Anka"
        }
      },
      "isPick": false,
      "genres": [
        {
        "Genre": {
          "id": "MA0000011877",
          "name": "Vocal",
          "weight": 9
        },
        "Genre": {
          "id": "MA0000002613",
          "name": "Pop/Rock",
          "weight": 8
        }
      }],
      "appearances": null,
      "appearancesUri": "http://api.rovicorp.com/v1/song/appearances?format=xml&apikey=4p1k3y&trackId=MT0034729453",
      "moods": null,
      "moodsUri": "http://api.rovicorp.com/v1/song/moods?format=xml&apikey=4p1k3y&trackId=MT0034729453",
      "review": null,
      "reviewUri": null,
      "styles": null,
      "stylesUri": "http://api.rovicorp.com/v1/song/styles?format=xml&apikey=4p1k3y&trackId=MT0034729453",
      "themes": null,
      "themesUri": "http://api.rovicorp.com/v1/song/themes?format=xml&apikey=4p1k3y&trackId=MT0034729453"
    }
  }],
  "facetCounts": [
    {
    "name": "genre",
    "facetCount": [
      {
      "id": "MA0000002572",
      "name": "Electronic",
      "count": 16
    },
    {
      "id": "MA0000004431",
      "name": "Religious",
      "count": 1
    },
    {
      "id": "MA0000002809",
      "name": "R&B",
      "count": 8
    },
    {
      "id": "MA0000002467",
      "name": "Blues",
      "count": 3
    },
    {
      "id": "MA0000002692",
      "name": "Latin",
      "count": 1
    },
    {
      "id": "MA0000002532",
      "name": "Country",
      "count": 4
    },
    {
      "id": "MA0000011877",
      "name": "Vocal",
      "count": 5
    },
    {
      "id": "MA0000002567",
      "name": "Easy Listening",
      "count": 2
    },
    {
      "id": "MA0000002674",
      "name": "Jazz",
      "count": 4
    },
    {
      "id": "MA0000002592",
      "name": "Folk",
      "count": 2
    },
    {
      "id": "MA0000002660",
      "name": "International",
      "count": 5
    },
    {
      "id": "MA0000002521",
      "name": "Classical",
      "count": 1
    },
    {
      "id": "MA0000002613",
      "name": "Pop/Rock",
      "count": 136
    }]
  },
  {
    "name": "type",
    "facetCount": [
      {
      "name": "Track",
      "count": 136
    }]
  }]
}
}

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