Subscribe to Our Newsletter
The Music Story API is now only available to our premium customers.
Feel free to contact us at musicstorypro@music-story.com to find out about our various offers and take advantage of our data.
General points
The Music Story API allows you to collect, through XML and JSON, a set of music data and metadata.
These data can be:
Getting started
To use our API, you must register on this web site after agreeing to the terms of use. You will receive an email containing the two keys associated with your account: your API key and your API secret key. You can easily regenerate these keys by going into My account section. You will benefit from a basic account to be able to start without a subscription.
Extensive documentation is available, as well as a testing tool.
Authentication is using the OAuth 1.0 technology. Requests are also signed. Here is a guide for these signatures: The Oauth 1.0 Guide. And this is an interesting documentation from Netflix: Authentication oveview.
Main rules
These rules are applicable in the context of a non-commercial use. For more details, please refer to the terms of use.
The following points need to be considered:
API Languages
Some API fields can be get on English or French. For that, you just have to put your language ISO code in the API request. Examples :Request encoding
Data interpreted and returned by the Music Story API are encode in UTF-8
Limits
Depending on your subscription, your number of request is limited. Basic package is limited to 50,000 requests per month.
You must also comply with a limited access to editorial data: 150 items per month concerning the basic package.
A limit of three requests per second also exists, for technical reasons.
Common fields
For each request, following fields are returned:
Research, filters and pagination
It is possible to carry out a search on all objects.
The search works as a connector and takes into account one or more filters corresponding to object fields and researched related values.
It is also possible to filter the results of any type of request using these filter settings.
This operation is explained in the test tool, and examples are provided in the documentation.
The search results are paginated, results are limited to 100 per page.
Date fields can be filter by differents ways:
Response code
The response code is included in the field code, if it is empty or equal to 0, the request is a success. If it is otherwise, there can be a mistake (code with a negative value) or simply a warning (code with positive value).
The warning codes can be:
| Value of code | Value of type | Value of errcode | Signification |
|---|---|---|---|
| -1 | AccountException | 40301 | Maximum number of monthly requests reached. |
| 40302 | Maximum number of Editorial type requests has been reached. | ||
| -2 | DataException | 40401 | Unknown object |
| 40402 | object not found | ||
| 40403 | Unknown connector | ||
| 40404 | connector not found | ||
| 40405 | No filters for the research | ||
| 40406 | No index available for this object | ||
| 40407 | Settings missing | ||
| -3 | OAuthException | 40101 | You have to specify at least one of the two fields oauth_consumer_key in the case of a deman of token or oauth_token_key for any other requests. |
| 40102 | You have to specify the field oauth_consumer_key | ||
| 40103 | You have to specify the field oauth_token | ||
| 40104 | You have to specify the field oauth_signature | ||
| 40105 | The value of the oauth_consumer_key is incorrect, the public key OAuth can not be found | ||
| 40106 | The value of the oauth_token_key is incorrect, the access d'accès OAuth can not be found | ||
| 40107 | The Oauth signature is incorrect. To calculate the signature, please refer to the RFC OAuth 1.0. |
Release history
Music Story API evolution:
| 2013-06-17 | v1.00 | |
| 2013-09-26 | v1.10 : | Date value and date interval search function |
| 2013-10-11 | v1.20 : | API fields translation system |
| 2014-01-13 | v1.21 : | Special connector 'Artist-Title' added |
| 2014-01-13 | v1.22 : | Connectors 'Recording-Partners' added |
| 2014-03-13 | v1.23 : | 'timeline' and 'actu' fields added on 'News' object |
| 2014-04-08 | v1.24 : | 'Chart' object added |
| 2014-04-18 | v1.25 : | Reviews from others medias added |
| 2014-04-24 | v1.26 : | Counting of 'Editorial' requests depending on source, Music Story or others |
| 2014-05-06 | v1.27 : | 'Timeline' object added historical of news for an artist) News from others medias added |
| 2014-05-16 | v1.28 : | Adding of the 'Lyric' object and the 'LyricFind' connector |
This article has for purpose to help you use the Music Story API and particularly what concerns the OAuth 1.0 security the API uses. It will take the form of an explanatory tutorial, in which we will retrieve the discographiy of the artist « Bob Marley ». This article implies that you already registered to the Music Story API and that you have received your API keys. If this is not the case, you can register for free here. The examples given will be coded in PHP.
Signature of your request
In order to protect your requests on the msuci story API, and that nobody can make requests instead of you (and thus make your request meter without you knowing ), every request to the Music Story API must be signed. This chapter explains how to sign your request.
This signature is done thanks to two elements, the key "consumer_secret", that you received when you registered , and the key "token_secret", which is given by the API itself.
You will have to first retrieve the access tokens. In order to retrieve the token informations, we will carry out a request to the API at the adress :
http://api.music-story.com/oauth/request_token?oauth_consumer_key=<VOTRE CONSUMER KEY>&oauth_signature=<SIGNATURE OAUTH>
The signature of the request is calculated according to the RFC 5849 - 3.4. Signature, that you can look into for more information, one concrete use will be explained in this article.
Here is an example of code allowing to obtain the signature of a request :
function sign_request($request, $consumer_secret, $token_secret = null, $http_method = 'GET') {
$a = explode('?', $request);
$host_uri = $a[0];
$params = isset($a[1])?$a[1]:null;
$params = explode('&', $params);
if(isset($params['oauth_signature'])) unset($params['oauth_signature']);
sort($params);
ksort($params);
$encoded_parameters = implode('&',$params);
$base = str_replace('+', ' ', str_replace('%7E', '~', rawurlencode($http_method)));
$base.= '&';
$base.= str_replace('+', ' ', str_replace('%7E', '~', rawurlencode($host_uri)));
$base.= '&';
$base.= str_replace('+', ' ', str_replace('%7E', '~', rawurlencode($encoded_parameters)));
$hmac_key = str_replace('+', ' ', str_replace('%7E', '~', rawurlencode($consumer_secret)));
$hmac_key.= '&';
$hmac_key.= str_replace('+', ' ', str_replace('%7E', '~', rawurlencode($token_secret)));
$oauth_signature = base64_encode(hash_hmac('sha1', $base, $hmac_key, true));
return $request.(strpos($request, '?')?'&':'?').'oauth_signature='.rawurlencode($oauth_signature);
}
The request http://api.music-story.com/oauth/request_token?oauth_consumer_key=<Your CONSUMER KEY>&oauth_signature=<SIGNATURE OAUTH>we will send back your access tokens, for example :
<?xml version="1.0" encoding="utf-8"> <root> <version>0.9</version> <code>0</code> <data> <token>b14449ef373d89281c4f1a8f32ea77dd873aa600</token> <token_secret>51be5e7678535a504c039b2451f4900c8e8c0ad4</token_secret> </data> </root>
Search for an artist
The tokens spotted, we are now going to search our artist Bob Marley in the Music Story database. We are going to carry out a search on the artists having for name "Bob Marley" :
http://api.music-story.com/artist/search?name=Bob%20Marley&oauth_token=<VOTRE TOKEN D'ACCES>&oauth_signature=<SIGNATURE OAUTH>
The Oauth signature will be done using this time your oauth_token_secret (cf. Chapter 1). The return retrieves the list of the artists with the name "Bob Marley" :
<?xml version="1.0" encoding="utf-8"> <root> <version>0.9</version> <code>0</code> <count>2</count> <pageCount>1</pageCount> <currentPage>1</currentPage> <data> <item> <id>878</id> <name>Bob Marley</name> <ipi/> <type>Person</type> <url>http://data.music-story.com/bob-marley</url> <firstname>Bob</firstname> <lastname>Marley</lastname> <coeff_actu>8</coeff_actu> <update_date>2013-07-03 14:20:00</update_date> <creation_date>2013-04-09 00:00:00</creation_date> </item> <item> <id>100418</id> <name>Bob Marley and The Wailers</name> <ipi/> <type>Band</type> <url> http://data.music-story.com/bob-marley-and-the-wailers </url> <firstname/> <lastname/> <coeff_actu>0</coeff_actu> <update_date>2013-02-27 00:00:00</update_date> <creation_date>2013-02-27 00:00:00</creation_date> </item> </data> </root>
Here the artist that holds our interest is the artist 878. This code will allow you to access to all the metadata linked to the artist
Retrieving the discography of an artist
Once we have retrieved the id of our artist (878), we now have to use the album connector to retrieve the discography of the artist :
http://api.music-story.com/artist/878/albums?link=Main&oauth_token=<VOTRE TOKEN D'ACCES>&oauth_signature=<SIGNATURE OAUTH>
We thus obtain the discography of the artist :
<?xml version="1.0" encoding="utf-8"> <root> <version>0.9</version> <code>0</code> <count>173</count> <pageCount>18</pageCount> <currentPage>1</currentPage> <data> <item> <id>504977</id> <title>Reggae Roots, Vol. 5</title> <url> http://data.music-story.com/bob-marley/reggae-roots-vol-5-compilation </url> <label>Daxa</label> <distributor/> <type>Compilation</type> <format>Album</format> <release_date>2013-04-17</release_date> <update_date>2013-07-04 00:10:03</update_date> <creation_date>2013-05-28 06:07:53</creation_date> <link> <item>Main</item> <item>Performer</item> </link> </item> <item> [...] </data> </root>
We can see that we have a total of 18 pages. To go through the pages, you only need to add the setting "page" to your request. For example, to go to the page 2:
http://api.music-story.com/artist/878/albums?oauth_token=<Your TOKEN D'ACCES>&oauth_signature=<SIGNATURE OAUTH>&page=2
<?xml version="1.0" encoding="utf-8"> <root> <version>0.9</version> <code>0</code> <count>173</count> <pageCount>18</pageCount> <currentPage>1</currentPage> <data> <item> <id>362763</id> <title>Could You Be Loved</title> <url> http://data.music-story.com/bob-marley/could-you-be-loved-karaoke-single </url> [...] </data> </root>
