Music Story API

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:

To enjoy a less restrictive use, contact us.

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:


When you search by a string field, the answer will contain a <search_scores> tag. This tag contain a score list for each field string searched based on the Levenshtein distance between value given to the filter and the value found by the API. (ex: http://api.music-story.com/artist/search?name=John&firstname=John). This field can be hidden by adding "no_score=1" to the request.

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:

The error codes can be : In the case of an error, an object error is sent back, including more details about the error : The following table lists the errors which you can encounter:

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-17v1.00
2013-09-26v1.10 :Date value and date interval search function
2013-10-11v1.20 :API fields translation system
2014-01-13v1.21 :Special connector 'Artist-Title' added
2014-01-13v1.22 :Connectors 'Recording-Partners' added
2014-03-13v1.23 :'timeline' and 'actu' fields added on 'News' object
2014-04-08v1.24 :'Chart' object added
2014-04-18v1.25 :Reviews from others medias added
2014-04-24v1.26 :Counting of 'Editorial' requests depending on source, Music Story or others
2014-05-06v1.27 :'Timeline' object added historical of news for an artist)
News from others medias added
2014-05-16v1.28 :Adding of the 'Lyric' object and the 'Lyricfind' connector







Your first API request

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>
music story

Forgot your password ?