Comment utiliser le module starapi ================================== .. toctree:: :maxdepth: 2 Introduction ------------ Après avoir installé le module :mod:`starapi` vous avez besoin de deux choses : * Une clé d'API fournie par Keolis, * Faire un import du module :mod:`starapi` et d'utiliser les classes dont vous avez besoin. Le module propose deux façons de faire : en utilisant les fonctions de haut niveau du module, ou en utilisant directement les fonctions et classes de bas niveau. Ainsi, en fonction de la granularité d'action dont vous avez besoin, vous êtes libres d'utiliser directement les couches les plus basses du module. C'est très pratique si vous voulez simplement faire quelques appels, ou construire tout un mécanisme de cache devant les appels. Client haut-niveau ------------------ Il existe deux clients haut-niveau : * Le réseau de vélo du Star : :class:`starapi.LeveloStar`. * Le réseau de bus et de métro du Star : :class:`starapi.NetworkStar`. Vous pouvez simplement obtenir un client pour ces API avec les fonctions :func:`starapi.levelostar` et :func:`starapi.networkstar` en fournissant votre clé d'API en paramètre. Vous obtiendrez alors un client prêt à l'emploi. Exemple ....... Prenons un cas simple : obtenir la liste des districts du réseau Le Vélo Star : :: >>> import starapi >>> client = starapi.levelostar('YOUR_KEOLIS_KEY_HERE') >>> districts = client.get_districts() >>> for district in districts: ... print('[%s] %s' % (district.get('id'), district.get('name'))) ... [34] Sud-Gare [35] Francisco Ferrer-Vern-Poterie [36] Jeanne d'Arc-Longs Champs-Atalante [37] Bréquigny [38] Le Blosne [39] Villejean-Beauregard [40] St Martin [41] Maurepas - Patton [42] Bourg l'Evêque-La Touche-Moulin du Comte [43] Thabor - St Hélier [44] Cleunay-Arsenal-Redon [45] Centre-Ville Les handlers : bas niveau ------------------------- Muni de vôtre clé d'API, vous pouvez instancier un :class:`~starapi.Handler` qui formatera les requêtes pour vous. Lorsque vous appelez une fonction du :class:`~starapi.Handler`, les paramètres sont vérifiés, puis une url est construite avec les paramètres formatés comme il faut. Enfin, un appel HTTP est effectué, et le résultat est directement retourné comme réponse à l'appel de la fonction. Comme le module `requests` est utilisé, c'est donc un objet `Response` de ce même module qui est retourné à chaque appel. Format de réponse ................. Le format de réponse des handlers est un objet Response du module `requests`. Le contenu de l'attribut `text` est alors le résultat de la requête. Dans le cas du Handler de base, il s'agit d'une réponse formatée en XML, qui peut être interprétée (par exemple) avec `lxml` : :: >>> r = api.getlines() >>> root = root.fromstring(r.text.encode('utf-8')) >>> root.xpath('/opendata/answer/status') [] >>> status = root.xpath('/opendata/answer/status')[0] >>> status.get('code') '0' >>> status.get('message') 'OK' **Remarque importante** : la valeur de l'attribut `text` est une chaîne de caractère unicode. Comme `lxml.etree` attend une chaîne encodée lorsque le XML contient une entête, pensez à encoder d'abords le résultat en `utf-8`. Structure du XML de réponse ........................... La structure de la réponse XML est toujours la même lorsque la requête a aboutie correctement : :: La balise `request` contient l'url de la requête appelée, avec tous ses paramètres. La balise `data` contient le contenu XML de la réponse, en tant que noeud normal du document XML (ce n'est donc pas du CDATA à interprété, mais bien une suite de noeud XML valide). En cas d'erreur, l'élément `/opendata/answer/data` n'existe pas, et un code d'erreur est présent dans la balise `status`. Status code ........... Les codes de retour de l'API les plus fréquents sont les suivants : ======== ========================================= =========================== Code Message Signification ======== ========================================= =========================== 0 OK Tout va bien. 3 The requested command could not be found. Commande introuvable : Please check spelling. probablement un bug du client à signaler. 103 A required parameter is not filled. Paramètre non fourni, le Please, check parameters. bug est de vôtre côté ! ======== ========================================= ===========================