API Music Story

L'API Music Story n’est désormais disponible que pour nos clients premium.
N'hésitez pas à nous contacter sur notre email musicstorypro@music-story.com pour connaître nos différentes offres et profiter de nos données.

Généralités

L'API Music-Story permet de récupérer, en XML et JSON, un ensemble de méta-données musicales.
Les données fournies peuvent être :

Sécurité

Pour utiliser l'API Music Story, vous devez vous inscrire sur ce portail après avoir accepté les conditions d'utilisation. Un email contenant les deux clés associées à votre compte : votre API key, et votre API secret key, vous sera envoyé. Vous pourrez aisément regénérer ces clés en vous rendant dans la partie Mon compte. Vous bénéficierez ainsi du compte basic, pour pouvoir démarrer sans abonnement.
Cette documentation est à votre disposition, ainsi qu'un outil de test.
L'authentification se fait à l'aide de la technologie OAUTH 1.0. Les requêtes sont donc signées. Pour vous aider, n'hésitez pas à vous référé à la RFC OAuth 1.0. Voici un guide pour ces signatures : The Oauth 1.0 Guide. Netflix a également une documentation intéressante : Authentication overview.

Règles générales

Ces règles s'appliquent dans le cadre d'une utilisation non commerciale, pour plus d'informations merci de lire les conditions d'utilisation.
Les points suivants sont à respecter:

Pour profiter d'une utilisation moins contraignante, contactez-nous.

Langue de l'API

L'API peut avoir certain de ses champs disponible en français et en anglais. Pour ce faire, il vous suffit d'indiquer le code ISO de la langue que vous désirez. Exemples :

Encodage des requètes

Les données interprétées et retournées par l'API sont encodées en UTF-8.

Limites

Selon votre offre, vos nombre de requête peut être limité. Au démarrage, sans abonnement particulier, votre limite est à 10 000 requêtes par mois.
et de 3 requêtes par seconde. Vous devez également respecter une limite d'accès aux données éditoriales : 150 items par mois.

Pour plus d'explication veuillez consulter les F.A.Q..

Champs standard

Pour chaque requête, les champs suivant sont retournés :

Recherche, filtres et pagination

La recherche s'effectue grâce à la méthode search des objets, quand celle-ci est présente.

La recherche fonctionne tel un connecteur et prend en paramètre un ou plusieurs filtres correspondants aux champs de l'objet et aux valeurs recherchées liées.
Il est également possible de filtrer les résultats de tout type de requête en utilisant ces paramètres de filtrage.
Le fonctionnement est explicité dans l'outil de test, et des exemples sont mis à disposition dans la documentation.

Les résultats de requête sont paginés, par défaut le nombre de résultats est de 10 par page. Il est possible de le préciser grâce à "pageCount". Le nombre de résultats est limité à 100 par page.

Les champs de type date peuvent être filtrés ou recherchées de plusieurs manière:


Lors d'une recherche sur un ou plusieurs champs de type string, la réponse de l'API contient une balise <search_scores>. Elle contient une liste de score de proximité pour chaque champs string recherchés calculé à partir de la distance de levenshtein séparant la valeur donnée au filtre de la valeur trouvée par l'API (ex:http://api.music-story.com/artist/search?name=John&firstname=John). Ce champs peut être masqué en ajoutant "no_score=1" à la requête.

Codes réponse

Le code réponse est contenu dans le champs code, lorsque celui-ci est vide ou égal à 0, la requête est un succès. Sinon, il peut s'être produit une erreur (code à valeur négative) ou une simple alerte (code à valeur positive).
Les codes d'alerte peuvent être :

Les codes d'erreur peuvent être : En cas d'erreur, un objet erreur vous est retourné, contenant plus de précision sur l'erreur : Ci-après le tableau listant la liste des erreurs que vous pouvez rencontrer :

Valeur de code Valeur de type Valeur de errcode Signification
-1 AccountException 40301 Votre compteur de requête mensuel est atteint.
40302 Votre compteur de requête d'items de type Éditorial est atteint.
-2 DataException 40401 Objet inconnu.
40402 Objet introuvable.
40403 Connecteur inconnu.
40404 Connecteur introuvable.
40405 Pas de filtre pour la recherche.
40406 Index inaccessible pour cet objet.
40407 Paramètres manquants.
-3 OAuthException 40101 Il faut spécifier au moins un des deux champs oauth_consumer_key dans le cas d'une demande de token ou oauth_token_key pour toutes autres requêtes.
40102 Il faut spécifier le champs oauth_consumer_key.
40103 Il faut spécifier le champs oauth_token.
40104 Il faut spécifier le champs oauth_signature.
40105 La valeur de oauth_consumer_key est incorrecte, la clé publique OAuth est introuvable.
40106 La valeur de oauth_token_key est incorrecte, le token d'accès OAuth est introuvable.
40107 La signature OAuth est incorrecte. Pour calculer la signature, référez vous a la RFC OAuth 1.0.

Historique

L'évolution de l'API Music Story:

2013-06-17v1.00
2013-09-26v1.10 :Mise en place des recherches par date seule et intervalles de date
2013-10-11v1.20 :Système de traduction automatique des champs
2014-01-13v1.21 :Ajout du connecteur spécial 'Artist-Title'
2014-01-13v1.22 :Ajout du connecteur 'Recording-Partenaires'
2014-03-13v1.23 :Ajout des champs 'timeline' et 'actu' sur l'objet News
2014-04-08v1.24 :Ajout de l'objet 'Chart'
2014-04-18v1.25 :Ajout des chroniques en provenance d'autres médias (Télérama...)
2014-04-24v1.26 :Comptabilisation des requêtes 'Editorial' différenciée selon source Music Story ou autre
2014-05-06v1.27 :Ajout de l'objet 'Timeline', historique des news d'un artiste
Ajout des news en provenance d'autres médias.
2014-05-16v1.28 :Ajout de l'objet 'Lyric' et des connecteurs 'LyricFind'







Votre première requête API

Cet article à pour but de vous aider à utiliser l'API music-story, tous particulièrement en ce qui concerne la sécurité OAuth 1.0 que l'API utilise. Il prendra la forme d'un tutoriel explicatif, dans lequel on va récupérer la discographie de l'artiste "Bob Marley". Cet article implique que vous soyez déjà inscrit à l'API music-story et que vous ayez déjà reçus vos clés d'API. Dans le cas contraire, vous pouvez vous inscrire gratuitement ici. Les exemples donnés seront codés en PHP.

Signature de votre requête

Afin de protéger vos requête sur l'API music-story, et que personne ne puisse faire de requêtes à votre place (et donc faire descendre votre compteur de requête à votre insu), chaque requête à l'API music-story doit être signée. Ce chapitre vous explique comment signer votre requête.
Cette signature se fait grâce à deux éléments, la clé "consumer_secret", que vous avez reçus lors de votre inscription, et la clé "token_secret", qui elle est fournie par l'API elle-même.

Il va falloir d'abords récupérer vos tokens d'accès. Afin de récupérer les informations de token, on va effectuer une requête sur l'API à l'adresse :
http://api.music-story.com/oauth/request_token?oauth_consumer_key=<VOTRE CONSUMER KEY>&oauth_signature=<SIGNATURE OAUTH>

La signature de la requête se calcul selon la RFC 5849 - 3.4. Signature, que vous pouvez consulter pour plus d'information, seule une utilisation concrète sera expliqué dans cet article.


Voici un exemple de code permettant d'obtenir la signature d'une requête :

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);
}

La requête http://api.music-story.com/oauth/request_token?oauth_consumer_key=<VOTRE CONSUMER KEY>&oauth_signature=<SIGNATURE OAUTH> vous retournera alors vos token d'accès, par exemple :

<?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>

Recherche d'un artiste

Les tokens répérés, on va maintenant rechercher notre artiste Bob Marley dans la base de données Music-Story. On va donc exécuter une requête de recherche sur les artistes ayant pour nom "Bob Marley" :
http://api.music-story.com/artist/search?name=Bob%20Marley&oauth_token=<VOTRE TOKEN D'ACCES>&oauth_signature=<SIGNATURE OAUTH>
La signature OAuth se fera en utilisant cette fois-ci votre oauth_token_secret (cf. Chapitre 1). La requête nous retourne la liste des artistes ayant pour nom "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>

Ici, l'artiste qui nous intéresse est donc l'artiste 878. Celui-ci vous permettra d'accéder à toutes les méta-données de l'artiste

Récupération de la discographie de l'artiste

Une fois que nous avons récupéré l'id de notre artiste (878), il nous suffit d'utiliser le connecteur album pour récupérer la discographie de l'artiste :
http://api.music-story.com/artist/878/albums?link=Main&oauth_token=<VOTRE TOKEN D'ACCES>&oauth_signature=<SIGNATURE OAUTH>
On obtient ainsi la discographie de l'artiste :

<?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>

On voit ici que nous avons en tous 18 pages. Pour parcourir les pages, il vous suffit de rajouter le paramètre "page" à votre requête. Par exemple, pour avoir la page 2 :
http://api.music-story.com/artist/878/albums?oauth_token=<VOTRE 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 ?