Data/music-api/v1.1/composition/info

Jump to: navigation, search

Composition/Info

Returns basic information about a classical music composition plus customized requests for all of the other Composition content that is available. These customized requests are designed to make your programming easy and efficient: in a single step you both verify availability of the data and capture the request. You just add the signature parameter and execute the request.

The composition/info request also provides an optional parameter to include responses from any or all of the other Composition requests. This may return a large amount of data. To speed data transmission, do the following:

  • Request only data that you need to immediately display.
  • Request a compressed response by including Accept-Encoding: gzip,deflate in the HTTP header.

A variety of compositions may be performed on a classical music album. A composition can include multiple parts or movements, each of which is recorded as a single track.

Syntax

composition/info? compositionid=compositionid
amgclassicalid=amgclassicalid
&apikey=apikey&sig=sig [&include=include] [&format=format] [&country=country] [&language=language]

Request Example 1

Request information about the composition Also sprach Zarathustra.

Request Example 2

Also request the list of parts.

Request Example 3

Request information using an AMG Classical ID for an existing application that uses legacy AMG IDs.

Request Parameters

Sort none.gif  Click to re-sort

Parameter Required Description
apikey Yes Access code that authorizes your request for data from Rovi.
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.

amgclassicalid Conditional All Media Guide (AMG) ID for a classical music composition, consisting of a ten-character string that starts with C and is followed by nine digits with leading spaces. For example: C    43235.

When using an AMG Classical ID in a request, replace any spaces in the ID with plus (+) or percent20 (%20) symbols, like this: C++++43235. AMG is a legacy database of entertainment information.

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

  • compositionid
  • amgclassicalid
compositionid Conditional Rovi Music ID for a classical music composition, consisting of the prefix MC followed by a ten-digit number. For example: MC0002369165. Your application can grab composition IDs from responses to the following requests:

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

  • compositionid
  • amgclassicalid
country No Country the language parameter applies to. The current release of the API supports only US.
format No Format of the returned data: json or xml. The default is JSON.
include No Other requests to include in the request. To include the list of parts in the response, for example, add &include=parts.

You can specify multiple includes in either of the following ways:

  • In multiple arguments, like this: include=parts&include=description.
  • In a single argument as a comma-separated list, like this: include=parts,description.

You can also include all Music Service Composition requests with with include=all. The possible values are:

For information about a request, please see the documentation for the request.

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

  • Request only data that you need to immediately display.
  • Request a compressed response by including Accept-Encoding: gzip,deflate in the HTTP header.
language No Language of the response data. This request supports only en (English).

Response

Response Header

ResponseTypeDescription
buildstringThe software release level of the API.
codeintegerHTTP status code. See the status field for the text part of the code.
durationintegerServer processing time in milliseconds. The difference between startTime and endTime.
endTimestringWhen the server sent the response (UTC time).
messagesMessage [ ]Elements of a multiple HTTP response status message.
parametersparametersThe parameters that were included in the request.
serverNamestringName of the server that processed the request.
startTimestringWhen the server received the request (UTC time).
statusstringText part of the HTTP status code, which is shown in the code field.

Response for Composition/Info

ResponseTypeDescription
alternateTitle string Another title the composition is known by.
avarageDuration integer Average performance time of the composition in seconds.
composers CompositionComposer [ ] Composers of the composition.
compositionDate string Date the composition was composed, in YYYY-MM-DD format.
description description Description of the composition, returned only if the request specified an include=description argument.
descriptionUri string The customized Composition/Description request, returned only if the data is available.
firstPerformanceDate string Date the composition was first performed, in YYYY-MM-DD format.
forms CompositionForm [ ] Classical forms that apply to the composition, sorted in alphabetical order.
genres Genre [ ] Musical genres the composition falls into, along with a weighting that reflects the relative importance of each genre.

Genres are sorted in order of importance (highest to lowest weight) and, within the same weight, alphabetically by genre name.

ids ids All of the IDs that are recognized by the API for a composition. The possible IDs are:
  • compositionId
  • amgClassicalId
parts string [ ] Names of the parts or movements of a classical music composition, returned only if the request specified an include=parts argument.
partsUri string The customized Composition/Parts request, returned only if the data is available.
periods CompositionPeriod [ ] Musical periods the composition belongs in.
publicationDate string The date the composition was published, in YYYY-MM-DD format.
rating integer An editorially assigned rating of the composition from 0 to 5, where 0 is no rating and higher numbers indicate a higher rating.
releases CompositionRelease [ ] Album releases that feature a performance of a composition, returned only if the request specified an include=releases argument.
releasesUri string The customized Composition/Releases request, returned only if the data is available.
revisionDate string The last date the composition was revised, in YYYY-MM-DD format.
title string Title of the composition.

JSON Response Example

Here's the response to Request Example 1, which asks for information about the composition Also sprach Zarathustra. The response is formatted with extra spaces and carriage returns to make it easy to read.
Requested with http://api.rovicorp.com/data/v1.1/composition/info?apikey=apikey&sig=sig&
compositionid=MC0002369165
.
{
  "status":"ok",
  "code":200,
  "messages":null,
  "build":"1.5.1.9",
  "parameters":{
    "apiKey":"apikey",
    "id":"MC0002369165"
  },
  "serverName":"tul1cssw4",
  "startTime":"2011-04-27T23:16:10.1893520Z",
  "endTime":"2011-04-27T23:16:10.1893520Z",
  "duration":0,
  "composition":{
    "ids":{
      "amgClassicalId":"C   43235",
      "compositionId":"MC0002369165"
    },
    "title":"Also sprach Zarathustra (Thus Spoke Zoroaster), tone poem for orchestra, Op. 30 (TrV 176)",
    "composers":[
      {
        "id":"MN0000307408",
        "name":"Richard Strauss"
      }
    ],
    "avarageDuration":2019,
    "compositionDate":"1896-??-??",
    "publicationDate":"",
    "revisionDate":"",
    "firstPerformanceDate":"",
    "rating":5,
    "alternateTitle":"2001: A Space Odyssey (Theme)",
    "genres":[
      {
        "id":"MA0000004499",
        "name":"Orchestral",
        "weight":10
      },
      {
        "id":"MA0000002521",
        "name":"Classical",
        "weight":9
      }
    ],
    "periods":[
      {
        "id":"MA0000000081",
        "name":"Post-Romantic"
      }
    ],
    "forms":[
      {
        "id":"MA0000005211",
        "name":"Tone Poem"
      }
    ],
    "description":null,
    "descriptionUri":"http://api.rovicorp.com/data/v1.1/composition/description?format=json&apikey=apikey&compositionid=MC0002369165",
    "parts":null,
    "partsUri":"http://api.rovicorp.com/data/v1.1/composition/parts?format=json&apikey=apikey&compositionid=MC0002369165",
    "releases":null,
    "releasesUri":"http://api.rovicorp.com/data/v1.1/composition/releases?format=json&apikey=apikey&compositionid=MC0002369165"
  }
}

XML Response Example

Here's an XML response to Request Example 1, which asks for information about the composition Also sprach Zarathustra.
Requested with http://api.rovicorp.com/data/v1.1/composition/info?apikey=apikey&sig=sig&
compositionid=MC0002369165&format=xml
..
<CompositionDetail xmlns="com.rovicorp.metadataservice" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <status>ok</status>
  <code>200</code>
  <messages i:nil="true"/>
  <build>1.5.1.9</build>
  <parameters>
    <apiKey>apikey</apiKey>
    <id>MC0002369165</id>
    <format>xml</format>
  </parameters>
  <serverName>tul1cssw3</serverName>
  <startTime>2011-04-27T23:15:48.5227092Z</startTime>
  <endTime>2011-04-27T23:15:48.5383345Z</endTime>
  <duration>15</duration>
  <composition>
    <ids>
      <amgClassicalId>C 43235</amgClassicalId>
      <compositionId>MC0002369165</compositionId>
    </ids>
    <title>Also sprach Zarathustra (Thus Spoke Zoroaster), tone poem for orchestra, Op. 30 (TrV 176)</title>
    <composers>
      <CompositionComposer>
        <id>MN0000307408</id>
        <name>Richard Strauss</name>
      </CompositionComposer>
    </composers>
    <avarageDuration>2019</avarageDuration>
    <compositionDate>1896-??-??</compositionDate>
    <publicationDate/>
    <revisionDate/>
    <firstPerformanceDate/>
    <rating>5</rating>
    <alternateTitle>2001: A Space Odyssey (Theme)</alternateTitle>
    <genres>
      <Genre>
        <id>MA0000004499</id>
        <name>Orchestral</name>
        <weight>10</weight>
      </Genre>
      <Genre>
        <id>MA0000002521</id>
        <name>Classical</name>
        <weight>9</weight>
      </Genre>
    </genres>
    <periods>
      <CompositionPeriod>
        <id>MA0000000081</id>
        <name>Post-Romantic</name>
      </CompositionPeriod>
    </periods>
    <forms>
      <CompositionForm>
        <id>MA0000005211</id>
        <name>Tone Poem</name>
      </CompositionForm>
    </forms>
    <description i:nil="true"/>
    <descriptionUri>http://api.rovicorp.com/data/v1.1/composition/description?format=xml&apikey=apikey&compositionid=MC0002369165</descriptionUri>
    <parts xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays" i:nil="true"/>
    <partsUri>http://api.rovicorp.com/data/v1.1/composition/parts?format=xml&apikey=apikey&compositionid=MC0002369165</partsUri>
    <releases i:nil="true"/>
    <releasesUri>http://api.rovicorp.com/data/v1.1/composition/releases?format=xml&apikey=apikey&compositionid=MC0002369165</releasesUri>
  </composition>
</CompositionDetail>


See Also

↑ Top

Personal tools