PK ÎmCșù€ Ï Ï star-api-0.0.1/starapi.html
Le module starapi est le seul import dont vous avez besoin. Il contient deux classes Handler et BaseHandler qui permettent d’interroger l’API Star.
Pour utiliser le client python de l’API, il suffit de l’installer, et d’importer le module starapi. Ensuite, muni de vĂŽtre clĂ© d’API, vous pouvez instancier un Handler qui formatera les requĂȘtes pour vous.
Lorsque vous appelez une fonction du 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.
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')
[<Element status at 0x1ed2eb0>]
>>> 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.
La structure de la rĂ©ponse XML est toujours la mĂȘme lorsque la requĂȘte a aboutie correctement :
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<opendata>
<request><!-- REQUEST URL --></request>
<answer>
<status code="0" message="OK"/>
<data>
<!-- DATA RESPONSE -->
</data>
</answer>
</opendata>
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.
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. Please check spelling. | Commande introuvable : probablement un bug du client Ă signaler. |
103 | A required parameter is not filled. Please, check parameters. | ParamÚtre non fourni, le bug est de vÎtre cÎté ! |
Une bonne partie du travail du client consiste Ă appeler des URLs de l’API en choisissant la bonne version, la bonne commande, et la bonne clĂ©.
Pour simplifier une partie du travail, les méthodes de la classe Handler sont décorées avec le décorateur api_command().
Cette derniĂšre prend en premier paramĂštre la version de l’API qui supporte la commande, qui peut prendre comme valeur l’une des constantes suivantes :
Respectivement ayant pour valeur 1.0, 2.0 et 2.1.
ParamĂštres: |
|
---|---|
Type retourné: | function |
Cette fonction est un dĂ©corateur qui permet d’encapsuler l’envoie de la commande en tant que requĂȘte HTTP GET Ă l’API Keolis, sans avoir besoin de gĂ©rer la version et/ou le nom de la commande dans le corps de la fonction qui traite les paramĂštres de la commande.
La fonction dĂ©corĂ©e doit prendre en premier paramĂštre un API Handler (soit un BaseHandler soit un Handler), et doit retourner un dict contenant les paramĂštres Ă envoyer Ă l’API.
Le paramĂštre command est optionnel. S’il est omis, alors le nom de la fonction dĂ©corĂ©e est utilisĂ© Ă la place.
Lors de l’appel de la fonction dĂ©corĂ©e, elle est appelĂ©e avec les paramĂštres fournis, retourne un dictionnaire, et un appel Ă l’API du STAR est effectuĂ©.
Le retour est alors un objet Response du module requests. Voir aussi la documentation de request
Utilisation :
@api_command(KEOLIS_VERSION_1)
def getdistrict(self):
"""
Get districts
See: http://data.keolis-rennes.com/fr/les-donnees/api-version-1/getdistrict.html
"""
return {}
Classe de base de client handler. La clĂ© Ă fournir en paramĂštre d’instanciation est la clĂ© fournie Ă l’inscription auprĂšs du site de la Star.
ParamĂštres: |
|
---|
ProcĂšde Ă un appel HTTP GET de la commande command Ă l’API dans la version version.
Classe qui sert de client handler Ă l’API. C’est elle qui gĂšre l’ensemble des commandes Ă envoyer Ă l’API.
Pour fonctionner, le handler a besoin de la clĂ© de l’application inscrite auprĂšs du site de la Star comme application.
Les mĂ©thodes de cette classe implĂ©mentent les diffĂ©rentes commandes de l’API et fait un usage intensif du dĂ©corateur api_command().
ParamĂštres: |
|
---|
Référence : getstation
Exemple de réponse :
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<opendata>
<request><!-- snip --></request>
<answer>
<status code="0" message="OK"/>
<data>
<station>
<id>42</id>
<number>42</number>
<name>PONT DE STRASBOURG</name>
<state>1</state>
<latitude>48.109756</latitude>
<longitude>-1.656451</longitude>
<slotsavailable>11</slotsavailable>
<bikesavailable>0</bikesavailable>
<pos>0</pos>
<district>Thabor - St HĂ©lier</district>
<lastupdate>2012-11-27T19:32:02+01:00</lastupdate>
</station>
<!-- another "station" tags -->
</data>
</answer>
</opendata>
Référence : getdistrict
Exemple de réponse :
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<opendata>
<request><!-- snip --></request>
<answer>
<status code="0" message="OK"/>
<data>
<district>
<id>34</id>
<name>Sud-Gare</name>
</district>
<!-- another "district" tags -->
</data>
</answer>
</opendata>
ParamĂštres: |
|
---|
Référence : getbikestations
Exemple de réponse :
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<opendata>
<request><!-- snip --></request>
<answer>
<status code="0" message="OK"/>
<data>
<station>
<number>54</number>
<name>PONTCHAILLOU (TER)</name>
<address>26 AVENUE DU 41ĂME RĂGIMENT D'INFANTER </address>
<state>1</state>
<latitude>48.119316</latitude>
<longitude>-1.691517</longitude>
<slotsavailable>23</slotsavailable>
<bikesavailable>1</bikesavailable>
<pos>0</pos>
<district>Villejean-Beauregard</district>
<lastupdate>2012-12-02T18:15:03+01:00</lastupdate>
</station>
<!-- another "station" tags -->
</data>
</answer>
</opendata>
ParamĂštres: | network (string) – ‘levelostar’ par dĂ©faut (aucune autre valeur connue) |
---|
Référence : getbikedistricts
Exemple de réponse :
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<opendata>
<request><!-- snip --></request>
<answer>
<status code="0" message="OK"/>
<data>
<district>
<id>34</id>
<name>Sud-Gare</name>
</district>
<!-- another "district" tags -->
</data>
</answer>
</opendata>
ParamĂštres: |
|
---|
Référence : getlinesalerts
Exemple de réponse :
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<opendata>
<request><!-- snip --></request>
<answer>
<status code="0" message="OK"/>
<data>
<alert>
<title>Travaux Bd Villebois Mareuil</title>
<starttime>2012-12-01T00:00:00+01:00</starttime>
<endtime>2012-12-12T00:00:00+01:00</endtime>
<lines>
<line>32</line>
</lines>
<majordisturbance>0</majordisturbance>
<detail>A partir du lundi 3 décembre, dÚs le premier départ et pendant la durée des travaux Boulevard Villebois Mareuil.
Ligne 32 vers Triangle
L'arrĂȘt CimetiĂšre de l'Est est reportĂ© Ă l'arrĂȘt CimetiĂšre de l'Est de la ligne 11 vers Saint-SaĂ«ns situĂ© rue Auguste Pavie.
L'arrĂȘt Villebois Mareuil est reportĂ© Ă l'arrĂȘt provisoire situĂ© boulevard LĂ©on Bourgeois.
Ligne 32 vers Beaulieu Atalante
L'arrĂȘt Villebois Mareuil est reportĂ© Ă l'arrĂȘt Villebois Mareuil de la ligne 1 vers Cesson-SĂ©vignĂ© situĂ© rue de ChĂąteaugiron.
L'arrĂȘt CimetiĂšre de l'Est est reportĂ© Ă l'arrĂȘt CimetiĂšre de l'Est de la ligne 11 vers Stade Rennais situĂ© rue Auguste Pavie. </detail>
<link></link>
</alert>
<!-- another "alert" tags -->
</data>
</answer>
</opendata>
ParamĂštres: |
|
---|
Référence getlines
Exemple de réponse :
<opendata>
<request><!-- snip --></request>
<answer>
<status code="0" message="OK"/>
<data>
<baseurl>http://data.keolis-rennes.com/fileadmin/documents/Picto_lignes/Pictos_lignes_100x100/</baseurl>
<line>
<name>1</name>
<picto>L1.png</picto>
</line>
<!-- another "line" tags -->
</data>
</answer>
</opendata>
ParamĂštres: |
|
---|
Référence getequipments
Exemple de réponse :
<opendata>
<request><!-- snip --></request>
<answer>
<status code="0" message="OK"/>
<data>
<equipment>
<id>ASC_VU_2</id>
<station>VU</station>
<type>ASCENSEUR</type>
<fromfloor>-1</fromfloor>
<tofloor>0</tofloor>
<platform>2</platform>
<lastupdate>2012-12-02 07:16:13</lastupdate>
</equipment>
<!-- another "equipment" tags -->
</data>
</answer>
</opendata>
ParamĂštres: |
|
---|
Référence getequipmentsstatus
Exemple de réponse :
<opendata>
<request><!-- snip --></request>
<answer>
<status code="0" message="OK"/>
<data>
<equipment>
<id>ASC_VU_2</id>
<state>1</state>
<lastupdate>2012-12-02 07:16:13</lastupdate>
</equipment>
<!-- another "equipment" tags -->
</data>
</answer>
</opendata>
ParamĂštres: |
|
---|
Référence getmetrostations
Exemple de réponse :
<opendata>
<request><!-- snip --></request>
<answer>
<status code="0" message="OK"/>
<data>
<station>
<id>VU</id>
<name>Villejean-Université</name>
<latitude>48.12125000</latitude>
<longitude>-1.703950000</longitude>
<hasPlatformDirection1>1</hasPlatformDirection1>
<hasPlatformDirection2>1</hasPlatformDirection2>
<rankingPlatformDirection1>14</rankingPlatformDirection1>
<rankingPlatformDirection2>16</rankingPlatformDirection2>
<floors>-1</floors>
<lastupdate>2012-12-02T18:29:54+01:00</lastupdate>
</station>
<!-- another "station" tags -->
</data>
</answer>
</opendata>
ParamĂštres: |
|
---|
Référence : getmetrostationsstatus
Exemple de réponse :
<opendata>
<request><!-- snip --></request>
<answer>
<status code="0" message="OK"/>
<data>
<station>
<id>JFK</id>
<status>1</status>
<lastUpdate>2012-12-02T18:28:32+01:00</lastUpdate>
</station>
<!-- another "station" tags -->
</data>
</answer>
</opendata>
ParamĂštres: |
|
---|
Référence : getrelayparks
Exemple de réponse :
<opendata>
<request><!-- snip --></request>
<answer>
<status code="0" message="OK"/>
<data>
<relaypark>
<name>Henri Freville</name>
<latitude>48.0886255</latitude>
<longitude>-1.670222</longitude>
<carparkavailable>201</carparkavailable>
<carparkcapacity>406</carparkcapacity>
<lastupdate>2010-09-27T08:30:49+02:00</lastupdate>
<state>0</state>
</relaypark>
<!-- another "relaypark" tags -->
</data>
</answer>
</opendata>
ParamĂštres: |
|
---|
Référence : getpos
Exemple de réponse :
<opendata>
<request><!-- snip --></request>
<answer>
<status code="0" message="OK"/>
<data>
<pos>
<name>Relais H / Gare SNCF</name>
<type>Tabac Presse</type>
<address>Place de la gare</address>
<zipcode>35000</zipcode>
<city>RENNES</city>
<district>Gares</district>
<phone>02 99 41 91 44</phone>
<schedule />
<latitude>48.1041574</latitude>
<longitude>-1.6726879</longitude>
</pos>
<!-- another "pos" tags -->
</data>
</answer>
</opendata>
ParamĂštres: |
|
---|
Référence : getcities
Exemple de réponse :
<opendata>
<request><!-- snip --></request>
<answer>
<status code="0" message="OK"/>
<data>
<city>
<name>RENNES</name>
<district>26</district>
<id>1</id>
</city>
<!-- another "city" tags -->
</data>
</answer>
</opendata>
ParamĂštres: |
|
---|
Référence : getcitydistricts
Exemple de réponse :
<opendata>
<request><!-- snip --></request>
<answer>
<status code="0" message="OK"/>
<data>
<district>
<name>Beauregard</name>
<id>1</id>
</district>
<!-- another "district" tags -->
</data>
</answer>
</opendata>
ParamĂštres: |
|
---|
Référence : getbusnextdepartures
Exemple de réponse :
<opendata>
<request><!-- snip --></request>
<answer>
<status code="0" message="OK"/>
<data>
<stopline>
<stop>856</stop>
<route>965</route>
<direction>0</direction>
<departures>
<departure accurate="1" headsign="Champs Blancs">2012-08-25T15:01:35+02:00</departure>
<departure accurate="0" headsign="Champs Blancs">2012-08-25T15:16:00+02:00</departure>
</departures>
</stopline>
<!-- another "stopline" tags -->
</data>
</answer>
</opendata>
La STAR (société qui gÚre les transports en commun de Rennes Métropole) fournit des données sur son service de transport, dont des données temps réels.
Lors de l’ouverture de donnĂ©es temps rĂ©el en Open-Data, il Ă©tait plus que temps de se pencher dessus, et de proposer un client en python pour interroger l’API Open-Data de la STAR.
Cette documentation propose de décrire le fonctionnement de ce client.
Amusez-vous bien, et bon voyage.
Ce client est développé sous licence LGPL, par un développeur du Collectif Open-Data Rennes, association indépendante de Kéolis, de la STAR, et de Rennes Métropole.
Ce n’est donc pas un client “officiel”, mais nous espĂ©rons qu’il sera satisfaisant.