Le module starapi

Le module starapi est le seul import dont vous avez besoin. Il contient plusieurs classes qui permettent d’interroger l’API de la Star.

Les clients

Il n’existe qu’un seul client pour le moment, pour le réseau Le Vélo Star, mais un second est prévu pour les Bus, et un troisième pour le Métro.

Constantes, fonctions et décorateurs

starapi.levelostar(key)
Paramètres:key (string) – La clé d’API fournie par Kéolis.
Type retourné:LeveloStar

Cette fonction retourne un client pour le réseau de vélo, configuré avec le handler par défaut, prêt à l’emploi. Il requiert simplement la clé d’API fournie par Kéolis pour se connecter à son API.

It just works.

starapi.networkstar(key)
Paramètres:key (string) – La clé d’API fournie par Kéolis.
Type retourné:NetworkStar

Cette fonction retourne un client pour le réseau de bus et de métro, configuré avec le handler par défaut, prêt à l’emploi. Il requiert simplement la clé d’API fournie par Kéolis pour se connecter à son API.

Again, it just works.

Classe de client de base

Un client de base existe, il permet de fournir les méthodes utilitaires communes aux différents clients spécifiques.

class starapi.StarClient

Classe de client de base.

__init__([handler=None])
Paramètres:handler (Handler) – starapi handler (optionnel)

Initialise une instance de StarClient.

set_handler(handler)
Paramètres:handler (Handler) – starapi handler

Défini le handler qui permet d’effectuer les requêtes à l’API du Star.

xml_data_from_response(response)
Paramètres:response – Un objet response fourni par le module requests.
Type retourné:Un noeud xml représentant le noeud ‘/opendata/answer/data’.
Lève:StarException – En cas d’erreur, avec le code d’erreur fourni par la réponse.

Retourne le noeud xml /opendata/answer/data après transformation en noeuds XML de la réponse texte.

node_to_dict(node)
Paramètres:node (un noeud xml tel qu’il est représenté par lxml ou par ElementTree.) – Le noeud xml à transformer en dictionnaire.

Retourne l’équivalent en dictionnaire d’un noeud xml.

Exemple avec le XML suivant :

<district>
    <id>34</id>
    <name>Sud-Gare</name>
</district>

Le résultat d’un appel à cette méthode sera :

{'id': '34', 'name': 'Sud-Gare'}

Le Vélo Star

class starapi.LeveloStar

Cette classe étend la classe de client de base StarClient.

get_stations_in_district(district)
Paramètres:district (string) – Le nom du district.
Type retourné:une liste de dictionnaires représentant des stations.

Retourne la liste des stations du district appelé district.

Chaque élément de la liste est un dictionnaire représentant une station.

get_stations_near_position(longitude, latitude)
Paramètres:
  • longitude (string) – La longitude de la position à proximité.
  • latitude (string) – La latitude de la position à proximité.
Type retourné:

une liste de dictionnaires représentant des stations.

Retourne la liste des stations à proximité de la position définie par sa longitude et sa latitude. Jusqu’à 3 stations sont ainsi retournées.

Chaque élément de la liste est un dictionnaire représentant une station.

get_stations_near_station(number):
Paramètres:number (string) – L’identifiant de la station à proximité.
Type retourné:une liste de dictionnaires représentant des stations.

Retourne la liste des stations à proximité de la station identifiée par station_number. Jusqu’à 3 stations sont ainsi retournées.

Chaque élément de la liste est un dictionnaire représentant une station.

get_station(number)
Paramètres:number (string) – L’identifiant de la station à recherché.
Type retourné:dict représentant la station (si elle existe), None sinon.

Retourne la station recherchée par son numéro d’identifiant.

get_stations(*args, **kwargs)

Retourne la liste des stations filtrée en fonction des paramètres.

Chaque élément de la liste est un dictionnaire représentant une station.

get_districts()

Retourne la liste des districts.

Chaque élément de la liste est un dictionnaire avec les clés id et name.

Le Réseau de bus et de métro Star

class starapi.NetworkStar

Cette classe étend la classe de client de base StarClient.

get_cities()
Type retourné:list

Retourne la liste des villes sur lequel est déployé le réseau de transport.

Chaque élément de la liste est un dictionnaire de la forme suivante :

{
    'id': '1',
    'name': 'RENNES',
    'district': '26'
}
get_districts_in_city(city)
Paramètres:city (string) – Nom ou identifiant de la ville.
Type retourné:list

Retourne la liste des quartiers d’une ville. Au moment de l’écriture de cette documentation, seule la ville de Rennes (id 1, name RENNES) dispose de quartier identifié, et retournera donc du contenu.

Chaque élément de la liste est un dictionnaire de la forme suivante :

{
    'id': '1',
    'name': 'Beauregard'
}
get_lines([size=21])
Paramètres:size (string) – La taille des vignettes souhaitées.
Type retourné:list

Retourne une liste de ligne de bus, avec une url de base pour la vignette en fonction de la taille demandée.

Chaque élément de la liste est un dictionnaire de la forme suivante :

{
    'name': '1',
    'picto': 'L1.png',
    'baseurl': 'http://data.keolis-rennes.com/fileadmin/documents/Picto_lignes/Pictos_lignes_21x21/'
}

Au moment de l’écriture de cette documentation, les quatres urls de base sont les suivantes :

get_lines_small()
Type retourné:list

Retourne le résultat de l’appel à la méthode get_lines() pour la taille de vignette 21.

get_lines_medium()
Type retourné:list

Retourne le résultat de l’appel à la méthode get_lines() pour la taille de vignette 100.

get_lines_normal()
Type retourné:list

Retourne le résultat de l’appel à la méthode get_lines() pour la taille de vignette 300.

get_lines_big()
Type retourné:list

Retourne le résultat de l’appel à la méthode get_lines() pour la taille de vignette 1000.

get_alert_for_line(line)
Paramètres:line (string) – Le nom de la ligne.
Type retourné:list

Retourne la liste des alertes qui touche une ligne.

get_lines_alerts(*args, **kwargs)
Type retourné:list

Retourne la liste des alertes sur le réseau de transport.

Chaque élément de la liste est un dictionnaire de la forme suivante :

{
    'title': u'Marché de Corps Nuds',
    'majordisturbance': '0',
    'lines': ['59'],
    'detail': u"Le dimanche matin, jusqu'à 14h environ : Marché à Corps Nuds.\r\nLigne 59  dans les deux sens\r\nL'arrêt Place de Kildare est reporté à l'arrêt Corps Nuds Mairie.\r\nLe Star vous remercie de votre compréhension.\r\nPour plus d'information contactez INFOSTAR  au 09 70 821 800 (Appel non surtaxé)",
    'link': None,
    'starttime': '2010-09-27T09:33:30+02:00',
    'endtime': '2013-01-31T00:00:00+01:00'
}

Les Handlers

Constantes, fonctions et décorateurs

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 :

starapi.KEOLIS_VERSION_1
starapi.KEOLIS_VERSION_2
starapi.KEOLIS_VERSION_2_1

Respectivement ayant pour valeur 1.0, 2.0 et 2.1.

starapi.api_command(version, command=None)
Paramètres:
  • version (string) – La version de l’API ciblée.
  • command (string) – Le nom de la commande ciblée.
Type retourné:

function

Cette fonction est un décorateur qui permet d’encapsuler l’envoi 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 {}

Base Handler

class starapi.BaseHandler(key)

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.

call_api(command, version, params)
Paramètres:
  • command (string) – Le nom de la commande.
  • version (string) – Le numéro de version de l’API.
  • params (dict) – Le dictionnaire des paramètres à fournir.

Procède à un appel HTTP GET de la commande command à l’API dans la version version.

Handler

class starapi.Handler(key)

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().

getstation(network=None, request=None, **kwargs)
Paramètres:
  • network (string) – ‘levelostar’ par défaut (aucune autre valeur connue)
  • request (string) – ‘all’, ‘proximity’, ‘district’ ou ‘number’
  • mode (string) – Request ‘proximity’, valeur ‘id’ ou ‘coord’
  • id (string) – Request ‘proximity’ mode ‘id’, identifiant de la station.
  • lat (string) – Request ‘proximity’ mode ‘coord’, latitude du point autour duquel chercher
  • long (string) – Request ‘proximity’ mode ‘coord’, longitude du point autour duquel chercher.
  • value (string) – Request ‘district’ ou ‘number’, valeur de recherche.

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>
getdistrict()

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>
getbikestations(network=None, station=None, **kwargs)
Paramètres:
  • network (string) – ‘levelostar’ par défaut (aucune autre valeur connue)
  • station (string) – ‘all’ (défaut), ‘district’, ‘number’ ou ‘proximity’
  • mode (string) – Station ‘proximity’ : mode de proximité : ‘id’ ou ‘coord’.
  • number (string) – Station ‘proximity’, mode ‘id’ : identifiant de la station autour de laquelle chercher.
  • lat (string) – Station ‘proximity’, mode ‘coord’ : latitude du point autour duquel chercher.
  • long (string) – Station ‘proximity’, mode ‘coord’ : longitude du point autour duquel chercher.
  • value (string) – Station ‘district’ ou ‘number’ : valeur sur laquelle filtrer.

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>
getbikedistricts(network=None)
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>
getlinesalerts(network=None, mode=None, **kwargs)
Paramètres:
  • network (string) – ‘star’ par défaut (aucune autre valeur connue)
  • mode (string) – ‘all’ (défaut) ou ‘line’
  • line (string) – Mode ‘line’, la ligne sur laquelle chercher.

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.&#13;
Ligne 32  vers Triangle&#13;
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. &#13;
L'arrêt Villebois Mareuil est reporté à l'arrêt provisoire situé boulevard Léon Bourgeois.&#13;
Ligne 32  vers Beaulieu Atalante&#13;
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. &#13;
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>
getlines(self, network=None, mode=None, size=None)
Paramètres:
  • network (string) – ‘star’ par défaut (aucune autre valeur connue)
  • mode (string) – ‘all’ par défaut (aucune autre valeur connue)
  • size (string) – Taille en pixel dans ‘21’ (défaut), ‘100’, ‘300’ ou ‘1000’

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>
getequipments(network=None, mode=None, **kwargs)
Paramètres:
  • network (string) – ‘star’ par défaut (aucune autre valeur connue)
  • mode (string) – ‘all’ (defaut), ‘station’ ou ‘id’
  • station (string) – Mode ‘station’ : nom de la station
  • id (string) – Mode ‘id’ : id de l’équipement.

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>
getequipmentsstatus(network=None, mode=None, **kwargs)
Paramètres:
  • network (string) – ‘star’ par défaut (aucune autre valeur connue)
  • mode (string) – ‘all’ (defaut), ‘station’ ou ‘id’
  • station (string) – Mode ‘station’ : nom de la station
  • id (string) – Mode ‘id’ : id de l’équipement

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>
getmetrostations(network=None, mode=None, **kwargs)
Paramètres:
  • network (string) – ‘star’ par défaut (aucune autre valeur connue)
  • mode (string) – ‘all’ (defaut), ‘proximity’ ou ‘station’
  • proximity_type (string) – Mode ‘proximity’ : ‘station’ ou ‘coords’
  • lat (string) – Mode ‘proximity’, type ‘coords’ : latitude du point autour duquel chercher.
  • long (string) – Mode ‘proximity’, type ‘coords’ : longitude du point autour duquel chercher.
  • station (string) –

    Mode ‘proximity’, type ‘station’: La station autour de laquelle chercher.

    Mode ‘station’ : La station à chercher.

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>
getmetrostationsstatus(network=None, mode=None, **kwargs)
Paramètres:
  • network (string) – ‘star’ par défaut (aucune autre valeur connue)
  • mode (string) – ‘all’ (défaut), ‘proximity’ ou ‘station’
  • proximity_type (string) – Mode ‘proximity’ : ‘station’ ou ‘coords’
  • lat (string) – Mode ‘proximity’, type ‘coords’ : latitude du point autour duquel chercher.
  • long (string) – Mode ‘proximity’, type ‘coords’ : longitude du point autour duquel chercher.
  • station (string) –

    Mode ‘proximity’ : La station autour de laquelle chercher.

    Mode ‘station’ : La station de métro à chercher.

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>
getrelayparks(network=None, latitude=None, longitude=None)
Paramètres:
  • network (string) – ‘star’ par défaut (aucune autre valeur connue)
  • latitude (string) – latitude du point autour duquel chercher.
  • longitude (string) – longitude du point autour duquel chercher.

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>
getpos(network=None, mode=None, **kwargs)
Paramètres:
  • network (string) – ‘star’ par défaut (aucune autre valeur connue)
  • mode (string) – ‘all’ (défaut), ‘proximity’ ou ‘zone’
  • latitude (string) – Mode ‘proximity’ : latitude du point autour duquel chercher.
  • longitude (string) – Mode ‘proximity’ : longitude du point autour duquel chercher.
  • city (string) – Mode ‘zone’ : la ville sur laquelle filtrer.
  • district (string) – Mode ‘zone’ (optionnel) : le district sur lequel filtrer.

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>
getcities(network=None, mode=None)
Paramètres:
  • network (string) – ‘star’ par défaut (aucune autre valeur connue)
  • mode (string) – ‘all’ par défaut (aucune autre valeur connue)

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>
getcitydistricts(network=None, mode=None, city=None)
Paramètres:
  • network (string) – ‘star’ par défaut (aucune autre valeur connue)
  • mode (string) – ‘city’ par défaut (aucune autre valeur connue)
  • city (string) – Le nom de la ville dont on veut les districts.

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>
getbusnextdepartures(mode=None, **kwargs)
Paramètres:
  • mode (string) – Mode parmis ‘stop’, ‘line’, et ‘stopline’
  • route (string|list) –

    Mode ‘line’ : la route sur laquelle rechercher.

    Mode ‘stopline’ : liste de route sur lesquelles chercher (10 maximum).

  • direction (string|list) –

    Mode ‘line’ : la direction sur laquelle rechercher.

    Mode ‘stopline’ : liste des directions sur lesquelles chercher (10 maximum).

  • stop (list) –

    Mode ‘stop’ : liste d’identifiant d’arrêt (5 maximum).

    Mode ‘stopline’ : liste d’identifiant d’arrêt (10 maximum)

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>