Le module starapi
=================

.. py:module:: starapi

.. toctree::
   :maxdepth: 2

Le module :mod:`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
....................................

.. py:function:: levelostar(key)

   :param string key: La clé d'API fournie par Kéolis.
   :rtype: :class:`~starapi.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.*

.. py:function:: networkstar(key)

   :param string key: La clé d'API fournie par Kéolis.
   :rtype: :class:`~starapi.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.

.. py:class:: StarClient

   Classe de client de base.

   .. py:method:: __init__([handler=None])

      :param handler: starapi handler (optionnel)
      :type handler: :class:`Handler`

      Initialise une instance de :class:`StarClient`.

   .. py:method:: set_handler(handler)

      :param handler: starapi handler
      :type handler: :class:`Handler`
 
      Défini le handler qui permet d'effectuer les requêtes à l'API du Star.

   .. py:method:: xml_data_from_response(response)

      :param response: Un objet response fourni par le module `requests`.
      :rtype: Un noeud xml représentant le noeud '/opendata/answer/data'.
      :raise 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.

   .. py:method:: node_to_dict(node)

      :param node: Le noeud xml à transformer en dictionnaire.
      :type node: un noeud xml tel qu'il est représenté par `lxml` ou par `ElementTree`. 

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

.. py:class:: LeveloStar

   Cette classe étend la classe de client de base :class:`StarClient`.

   .. py:method:: get_stations_in_district(district)

      :param string district: Le nom du district.
      :rtype: 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.

   .. py:method:: get_stations_near_position(longitude, latitude)

      :param string longitude: La longitude de la position à proximité.
      :param string latitude: La latitude de la position à proximité.
      :rtype: 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.

   .. py:method:: get_stations_near_station(number):

      :param string number: L'identifiant de la station à proximité.
      :rtype: 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.

   .. py:method:: get_station(number)

      :param string number: L'identifiant de la station à recherché.
      :rtype: dict représentant la station (si elle existe), `None` sinon.

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

   .. py:method:: 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.

   .. py:method:: 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
.................................

.. py:class:: NetworkStar

   Cette classe étend la classe de client de base :class:`StarClient`.

   .. py:method:: get_cities

      :rtype: 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'
        }

   .. py:method:: get_districts_in_city(city)

      :param string city: Nom ou identifiant de la ville.
      :rtype: 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'
        }

   .. py:method:: get_lines([size=21])

      :param string size: La taille des vignettes souhaitées.
      :rtype: 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 :

      * Taille 21x21 pixel : http://data.keolis-rennes.com/fileadmin/documents/Picto_lignes/Pictos_lignes_21x21/
      * Taille 100x100 pixel : http://data.keolis-rennes.com/fileadmin/documents/Picto_lignes/Pictos_lignes_100x100/
      * Taille 300x300 pixel : http://data.keolis-rennes.com/fileadmin/documents/Picto_lignes/Pictos_lignes_300x300/
      * Taille 100x100 pixel : http://data.keolis-rennes.com/fileadmin/documents/Picto_lignes/Pictos_lignes_1000x1000/

   .. py:method:: get_lines_small

      :rtype: list

      Retourne le résultat de l'appel à la méthode :meth:`get_lines` pour la
      taille de vignette `21`.

   .. py:method:: get_lines_medium

      :rtype: list

      Retourne le résultat de l'appel à la méthode :meth:`get_lines` pour la
      taille de vignette `100`.

   .. py:method:: get_lines_normal

      :rtype: list

      Retourne le résultat de l'appel à la méthode :meth:`get_lines` pour la
      taille de vignette `300`.

   .. py:method:: get_lines_big

      :rtype: list

      Retourne le résultat de l'appel à la méthode :meth:`get_lines` pour la
      taille de vignette `1000`.

   .. py:method:: get_alert_for_line(line)

      :param string line: Le nom de la ligne.
      :rtype: list

      Retourne la liste des alertes qui touche une ligne.

   .. py:method:: get_lines_alerts(*args, **kwargs)

      :rtype: 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
:class:`Handler` sont décorées avec le décorateur :func:`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 :

.. py:data:: KEOLIS_VERSION_1
.. py:data:: KEOLIS_VERSION_2
.. py:data:: KEOLIS_VERSION_2_1

Respectivement ayant pour valeur `1.0`, `2.0` et `2.1`.

.. function:: api_command(version, command=None)

   :param string version: La version de l'API ciblée.
   :param string command: Le nom de la commande ciblée.
   :rtype: 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 :class:`BaseHandler` soit un :class:`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 {}

   __ http://docs.python-requests.org/en/latest/user/quickstart/#response-content

Base Handler
............

.. py:class:: 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.

   .. py:method:: call_api(command, version, params)

      :param string command: Le nom de la commande.
      :param string version: Le numéro de version de l'API.
      :param dict params: Le dictionnaire des paramètres à fournir.

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

Handler
.......

.. py:class:: 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 :func:`api_command`.

   .. py:method:: getstation(network=None, request=None, **kwargs)

      :param string network: 'levelostar' par défaut (aucune autre valeur connue)
      :param string request: 'all', 'proximity', 'district' ou 'number'
      :param string mode: Request 'proximity', valeur 'id' ou 'coord'
      :param string id: Request 'proximity' mode 'id', identifiant de la station.
      :param string lat: Request 'proximity' mode 'coord', latitude du point autour duquel chercher
      :param string long: Request 'proximity' mode 'coord', longitude du point autour duquel chercher.
      :param string value: Request 'district' ou 'number', valeur de recherche.

      Référence : getstation__

      __ http://data.keolis-rennes.com/fr/les-donnees/api-version-1/getstation.html

      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>

   .. py:method:: getdistrict()

      Référence : getdistrict__

      __ http://data.keolis-rennes.com/fr/les-donnees/api-version-1/getdistrict.html

      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>

   .. py:method:: getbikestations(network=None, station=None, **kwargs)

      :param string network: 'levelostar' par défaut (aucune autre valeur connue)
      :param string station: 'all' (défaut), 'district', 'number' ou 'proximity'
      :param string mode: Station 'proximity' : mode de proximité : 'id' ou 'coord'.
      :param string number: Station 'proximity', mode 'id' : identifiant de la station autour de laquelle chercher.
      :param string lat: Station 'proximity', mode 'coord' : latitude du point autour duquel chercher.
      :param string long: Station 'proximity', mode 'coord' : longitude du point autour duquel chercher.
      :param string value: Station 'district' ou 'number' : valeur sur laquelle filtrer.

      Référence : getbikestations__

      __ http://data.keolis-rennes.com/fr/les-donnees/api-version-2/getbikestations.html

      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>

   .. py:method:: getbikedistricts(network=None)

      :param string network: 'levelostar' par défaut (aucune autre valeur connue)
      
      Référence : getbikedistricts__

      __ http://data.keolis-rennes.com/fr/les-donnees/api-version-2/getbikedistricts.html

      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>

   .. py:method:: getlinesalerts(network=None, mode=None, **kwargs)

      :param string network: 'star' par défaut (aucune autre valeur connue)
      :param string mode: 'all' (défaut) ou 'line'
      :param string line: Mode 'line', la ligne sur laquelle chercher.

      Référence : getlinesalerts__

      __ http://data.keolis-rennes.com/fr/les-donnees/api-version-2/getlinesalerts.html

      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>

   .. py:method:: getlines(self, network=None, mode=None, size=None)

      :param string network: 'star' par défaut (aucune autre valeur connue)
      :param string mode: 'all' par défaut (aucune autre valeur connue)
      :param string size: Taille en pixel dans '21' (défaut), '100', '300' ou
                          '1000'

      Référence getlines__

      __ http://data.keolis-rennes.com/fr/les-donnees/api-version-2/getlines.html

      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>

   .. py:method:: getequipments(network=None, mode=None, **kwargs)

      :param string network: 'star' par défaut (aucune autre valeur connue)
      :param string mode: 'all' (defaut), 'station' ou 'id'
      :param string station: Mode 'station' : nom de la station
      :param string id: Mode 'id' : id de l'équipement.

      Référence getequipments__

      __ http://data.keolis-rennes.com/fr/les-donnees/api-version-2/getequipments.html

      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>

   .. py:method:: getequipmentsstatus(network=None, mode=None, **kwargs)

      :param string network: 'star' par défaut (aucune autre valeur connue)
      :param string mode: 'all' (defaut), 'station' ou 'id'
      :param string station: Mode 'station' : nom de la station
      :param string id: Mode 'id' : id de l'équipement

      Référence getequipmentsstatus__

      __ http://data.keolis-rennes.com/fr/les-donnees/api-version-2/getequipmentsstatus.html

      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>

   .. py:method:: getmetrostations(network=None, mode=None, **kwargs)

      :param string network: 'star' par défaut (aucune autre valeur connue)
      :param string mode: 'all' (defaut), 'proximity' ou 'station'
      :param string proximity_type: Mode 'proximity' : 'station' ou 'coords'
      :param string lat: Mode 'proximity', type 'coords' : latitude du point autour duquel chercher.
      :param string long: Mode 'proximity', type 'coords' : longitude du point autour duquel chercher.
      :param string station: Mode 'proximity', type 'station': La station autour de laquelle chercher.
                             
                             Mode 'station' : La station à chercher.

      Référence getmetrostations__

      __ http://data.keolis-rennes.com/fr/les-donnees/api-version-2/getmetrostations.html

      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>

   .. py:method:: getmetrostationsstatus(network=None, mode=None, **kwargs)

      :param string network: 'star' par défaut (aucune autre valeur connue)
      :param string mode: 'all' (défaut), 'proximity' ou 'station'
      :param string proximity_type: Mode 'proximity' : 'station' ou 'coords'
      :param string lat: Mode 'proximity', type 'coords' : latitude du point autour duquel chercher.
      :param string long: Mode 'proximity', type 'coords' : longitude du point autour duquel chercher.
      :param string station: Mode 'proximity' : La station autour de laquelle chercher.
                             
                             Mode 'station' : La station de métro à chercher.

      Référence : getmetrostationsstatus__

      __ http://data.keolis-rennes.com/fr/les-donnees/api-version-2/getmetrostationsstatus.html

      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>

   .. py:method:: getrelayparks(network=None, latitude=None, longitude=None)

      :param string network: 'star' par défaut (aucune autre valeur connue)
      :param string latitude: latitude du point autour duquel chercher.
      :param string longitude: longitude du point autour duquel chercher.

      Référence : getrelayparks__

      __ http://data.keolis-rennes.com/fr/les-donnees/api-version-2/getrelayparks.html

      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>

   .. py:method:: getpos(network=None, mode=None, **kwargs)

      :param string network: 'star' par défaut (aucune autre valeur connue)
      :param string mode: 'all' (défaut), 'proximity' ou 'zone'
      :param string latitude: Mode 'proximity' : latitude du point autour duquel chercher.
      :param string longitude: Mode 'proximity' : longitude du point autour duquel chercher.
      :param string city: Mode 'zone' : la ville sur laquelle filtrer.
      :param string district: Mode 'zone' (optionnel) : le district sur lequel filtrer.

      Référence : getpos__

      __ http://data.keolis-rennes.com/fr/les-donnees/api-version-2/getpos.html

      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>

   .. py:method:: getcities(network=None, mode=None)

      :param string network: 'star' par défaut (aucune autre valeur connue)
      :param string mode: 'all' par défaut (aucune autre valeur connue)

      Référence : getcities__

      __ http://data.keolis-rennes.com/fr/les-donnees/api-version-2/getcities.html

      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>

   .. py:method:: getcitydistricts(network=None, mode=None, city=None)

      :param string network: 'star' par défaut (aucune autre valeur connue)
      :param string mode: 'city' par défaut (aucune autre valeur connue)
      :param string city: Le nom de la ville dont on veut les districts.

      Référence : getcitydistricts__

      __ http://data.keolis-rennes.com/fr/les-donnees/api-version-2/getcitydistricts.html

      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>

   .. py:method:: getbusnextdepartures(mode=None, **kwargs)

      :param string mode: Mode parmis 'stop', 'line', et 'stopline'
      :param string|list route: Mode 'line' : la route sur laquelle rechercher.
                                
                                Mode 'stopline' : liste de route sur lesquelles chercher (10 maximum).
      :param string|list direction: Mode 'line' : la direction sur laquelle rechercher.
                                    
                                    Mode 'stopline' : liste des directions sur lesquelles chercher (10 maximum).
      :param list stop: Mode 'stop' : liste d'identifiant d'arrêt (5 maximum).
                        
                        Mode 'stopline' : liste d'identifiant d'arrêt (10 maximum)

      Référence : getbusnextdepartures__

      __ http://data.keolis-rennes.com/fr/les-donnees/api-version-21/getbusnextdepartures.html

      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>