Manuel utilisateur Web Service

Manuel utilisateur Web Service
Médiamétrie-eStat
Buropolis, Bât 2
1240, route des Dolines
Sophia Antipolis
06560 Valbonne
Tél
: 04 92 38
38 20 à
Logo
client
Fax
:
04
92
96
91 25
insérer :
E-mail
:
[email protected]
Insertion/images/À
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
https://ws.estat.com/gosu/rest/auth/xml?login=LOGIN&password=PASSWORD
suivante :
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 1er 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.
[email protected]
Manuel utilisateur Web Service
Page 8