Manuel utilisateur Web Service Médiamétrie-eStat Buropolis, Bât 2 1240, route des Dolines Sophia Antipolis 06560 Valbonne Tél Logo : 04 92 38 client 38 20 à Fax insérer : 04 92 : 96 91 25 E-mail Insertion/images/À : commercial@mediametrie-estat.com SAS au capital de 80.496 euros / R.C.S Grasse B 440 736 395 Manuel utilisateur Web Service Page 1
SOMMAIRE Présentation du document... 3 Le Web Service : principes généraux... 4 La récupération de vos données... 5 L'étape d'authentification... 5 L'étape de récupération de vos données... 6 Les paramètres du Web Service... 7 Exemple... 8
PRESENTATION DU DOCUMENT Ce document a pour objectif de vous présenter le fonctionnement du Web Service de Médiamétrie-eStat. Nous aborderons successivement les thèmes des possibilités du Web Service, des étapes de récupération de vos données et des paramètres à spécifier pour une utilisation optimale. Manuel utilisateur Web Service Page 3
LE WEB SERVICE : PRINCIPES GENERAUX Le Web Service (WS) de Médiamétrie-eStat est une option disponible sur l ensemble des univers de mesure (Web, Streaming, Podcast, Apps, ) Il s agit d un outil vous permettant de récupérer simplement, rapidement et de manière automatique l ensemble de vos données "brutes" (c est-à-dire non calculées) sur la totalité de vos comptes. Ces extractions peuvent alors être utilisées comme données d'entrée pour vos analyses ou être intégrées dans différentes applications métiers telles que : - Une application mobile - Un site Internet - Un Intranet - Un outil de requêtage ou de Data Mining - Un tableur (pour l'utilisation macros par exemple) - Notre Web Service est conçu selon l'architecture REST, basée sur l'architecture du Web et de ses standards http et URI). Les données peuvent-être échangées sous les formats XML ou JSON de manière indifférenciée. Cela signifie qu'une donnée émise en XML peut être reçue et exploitée en JSON (et inversement). Manuel utilisateur Web Service Page 4
LA RECUPERATION DE VOS DONNEES La récupération de vos données se fait en deux étapes (accessibles aussi bien en GET qu'en POST) : 1- Une étape d'authentification 2- Une étape de récupération L'étape d'authentification Afin de vous authentifier, vous devez effectuer une requête (voir ci-dessous). Une fois celle-ci réalisée, un "jeton" (token) vous est attribué. Il permet d'identifier un utilisateur connecté au Web Service et est valable 6 heures. Au-delà, il expire et une nouvelle requête d'authentification est nécessaire. En GET Une requête d authentification en mode GET est de la forme suivante : https://ws.estat.com/gosu/rest/auth/xml?login=login&password=password Cette requête retourne le token attribué ainsi que le nom et le numéro de chacun des comptes associés à votre login au format XML. Remarque : Pour obtenir le format JSON, il vous suffit de remplacer «xml» par «json» dans l url ci-dessus). En POST Pour utiliser des appels en POST, vous devez vous baser sur le format d échange défini par le document XSD disponible ici : https://ws.estat.com/gosu/doc/tech/authreq. La requête d authentification doit donc être incluse dans le corps d une requête HTTP POST, soit en XML, soit en JSON. Exemple de requête d authentification en XML pour une requête en POST <?xml version="1.0" encoding="utf-8"?> <tokenrequest> <login>login</login> <password>password</password> </tokenrequest> Login et password représentant les identifiants de connexion de votre compte. Manuel utilisateur Web Service Page 5
L'étape de récupération de vos données Une fois identifié, vous devez effectuer une nouvelle requête vous permettant de récupérer vos données. Il vous sera nécessaire de renseigner le jeton qui vous a été attribué. En GET Une requête de restitution de données en mode GET est de la forme suivante : https://ws.estat.com/gosu/rest/data/xml?tokenid=token&serial=serial&date=date&indic ator=code_indicateur Cette requête retourne les valeurs de chacune des unités contenues dans l indicateur spécifié dans l URL au format XML. Remarque : Pour obtenir le format JSON, il vous suffit de remplacer «xml» par «json» dans l url ci-dessus). En POST Pour utiliser des appels en POST, vous devez vous baser sur le format d échange défini par le document XSD disponible ici : https://ws.estat.com/gosu/doc/tech/datareq. La requête de récupération des données doit donc être incluse dans le corps d une requête HTTP POST, soit en XML, soit en JSON. Pour la récupération de données, le POST permet une plus grande souplesse en gérant simultanément plusieurs filtres de données. Exemple de requête de récupération de données en XML pour une requête en POST <?xml version="1.0" encoding="utf-8"?> <gosurequest tokenid="token"> <serial>serial</serial> <date>date</date> <indicator>code_indicateur</indicator> </gosurequest> Manuel utilisateur Web Service Page 6
Les paramètres du Web Service Voici la description des 4 paramètres obligatoires présents dans la requête de récupération de données : - tokenid désigne le jeton qui vous identifie. Il expire au bout de 6 heures d inactivité. - serial désigne le numéro du compte à partir duquel vous souhaitez récupérer des données. - date désigne la journée pour laquelle vous souhaitez avoir des chiffres. Vous pouvez également récupérer directement des données hebdomadaires ou mensuelles en utilisant le paramètre periodtype=w ou periodtype=m. La date spécifiée doit être la première journée de la période voulue. Elle doit être au format aaaa-mm-jj. Remarque : Les analyses sur une semaine ou sur un mois ne peuvent s'effectuer uniquement du lundi au dimanche ou du 1 er au 30/31 et non sur une période glissante (du jeudi au jeudi ou du 15 septembre au 15 octobre par exemple). - indicator désigne l indicateur que vous souhaitez récupérer. La liste des indicateurs qui peuvent être récupérés depuis le Web Service est disponible ici : https://ws.estat.com/gosu/doc/indicators D autres paramètres peuvent être spécifiés pour faciliter la récupération et l organisation de vos données : - Triez et ordonnez les données récupérées avec les paramètres unit, value et order. - Filtrez vos données grâce aux paramètres filterlabel, filtertype et filtervalue. Remarque : Les requêtes en mode POST permettent d'appliquer plusieurs filtres, contrairement à celles en modes GET qui ne gère qu'un filtre. - Définissez le mode de sélection des comptes de cumul (cumulé ou ventilé) avec le paramètre mastermode. - Définir un top sur l'affichage de vos résultats (par exemple, les 50 meilleurs résultats en fonction d'une unité) Vous pouvez retrouver plus de détails sur l utilisation des paramètres en cliquant ici : https://ws.estat.com/gosu/doc/tech/dataget Manuel utilisateur Web Service Page 7
Exemple Je suis identifié et je souhaite obtenir sur mon compte, sur une semaine, les performances de mes 50 niveaux 1 les plus performants en triant par ordre décroissant mon indicateur de visites. La requête correspondante à ce besoin est la suivante : <?xml version="1.0" encoding="utf-8"?> <gosurequest tokenid="8fc06296bcce522c0ea0b984c20f7e97be343ce539d05f8be9aa948820b8455c" page="1" pagesize="1000"> <serial>08619</serial> <date>2011-10-17</date> <indicator>web_2niveaux_niveau1</indicator> <top unit="visites" order="desc" value="50" /> <periodtype>w</periodtype> </gosurequest> Nous espérons que notre Web Service vous donnera entière satisfaction et restons à votre disposition pour répondre à toutes vos questions. L'équipe de Médiamétrie-eStat. Support-pro@estat.com Manuel utilisateur Web Service Page 8