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