API : Différence entre versions

De Raildar
Aller à : navigation, rechercher
(+méthode guess_my_train de Turblog pas encore prête)
(Identification des sources)
 
(19 révisions intermédiaires par 2 utilisateurs non affichées)
Ligne 10 : Ligne 10 :
 
* "position extrapolée" signifie que le train est placé sur une ligne droite entre la gare précédente et la gare suivante, donc probablement pas au bon endroit
 
* "position extrapolée" signifie que le train est placé sur une ligne droite entre la gare précédente et la gare suivante, donc probablement pas au bon endroit
 
* "position GPS théorique" signifie que le train est en principe sur ses rails et que sa position est calculée en fonction des heures de passage et du retard annoncé
 
* "position GPS théorique" signifie que le train est en principe sur ses rails et que sa position est calculée en fonction des heures de passage et du retard annoncé
 +
 +
== Identification des sources ==
 +
Raildar s'appuie sur plusieurs sources qui peuvent ou doivent être indiquées dans plusieurs méthodes avec le switch ?id_source=x
 +
* 1 : TER / Intercité / TGV / idTGV / Thalys
 +
* 2 : Eurostar
 +
* 3 : Transilien / RER
 +
* 4 : Tisseo (non implémentée)
 +
* 6 : RATP (non implémentée)
 +
* 7 : IrishRail
 +
* 8 : NetworkRail (Angleterre, non implémentée)
  
 
= Méthodes =
 
= Méthodes =
* Les méthodes sont toutes sous la forme http://www.raildar.fr/xml/methode?param.  
+
* Les méthodes sont toutes sous la forme http://www.raildar.fr/json/methode?param.
* On peut les récupérer en JSON avec http://www.raildar.fr/json/convert?url=methode&param
+
** Les méthodes XML ne sont plus maintenues, préférez les JSON.
 +
* On peut les récupérer en JSON le résultats des méthodes XML non migrées avec http://www.raildar.fr/json/convert?url=methode&param
 
* Les paramètres entre crochets sont optionnels
 
* Les paramètres entre crochets sont optionnels
  
== gares ==
+
== json/gares ==
 
retourne un listing de gares. L'ensemble des gares connues est renvoyée si aucun paramètre n'est indiqué
 
retourne un listing de gares. L'ensemble des gares connues est renvoyée si aucun paramètre n'est indiqué
 
* [lat / lng] : permet de spécifier une position de recherche. Peut être associé à [dist] (défaut 4) pour la distance maximum en kilomètre et/ou [limit] (défaut 20) pour le nombre de gare à retourner
 
* [lat / lng] : permet de spécifier une position de recherche. Peut être associé à [dist] (défaut 4) pour la distance maximum en kilomètre et/ou [limit] (défaut 20) pour le nombre de gare à retourner
** http://www.raildar.fr/xml/gares?lat=45.888&lng=4.8041&dist=20&limit=10
+
** http://www.raildar.fr/json/gares?lat=45.888&lng=4.8041&dist=20&limit=10
 +
* [id_gare] : permet de rechercher une gare par son ID
 +
** http://www.raildar.fr/json/gares?id_gare=60
 
* [search] : permet de faire une recherche sur un morceau de nom de gare
 
* [search] : permet de faire une recherche sur un morceau de nom de gare
** http://www.raildar.fr/xml/gares?search=lyon
+
** http://www.raildar.fr/json/gares?search=lyon
  
 
Les deux méthodes lat/lng et search ne peuvent être associées
 
Les deux méthodes lat/lng et search ne peuvent être associées
  
== get_gare ==
+
== xml/get_gare (deprecated) ==
 
retourne une gare à partir de son ID
 
retourne une gare à partir de son ID
 
* id_gare : id de la gare
 
* id_gare : id de la gare
 
** http://www.raildar.fr/xml/get_gare?id_gare=60
 
** http://www.raildar.fr/xml/get_gare?id_gare=60
  
== get_train ==
+
== json/get_train ==
 
retourne un ou plusieurs trains ainsi que la dernière date ou ils ont été détectes, en fonction de (au choix) :
 
retourne un ou plusieurs trains ainsi que la dernière date ou ils ont été détectes, en fonction de (au choix) :
 
* id_train : l'ID interne dans Raildar
 
* id_train : l'ID interne dans Raildar
 
* num : le numéro de train affecté par la SNCF
 
* num : le numéro de train affecté par la SNCF
 
* code : le code train affecté par la SNCF (par exemple OCESN892372F03002)
 
* code : le code train affecté par la SNCF (par exemple OCESN892372F03002)
** http://raildar.fr/xml/get_train?code=OCESN892368F01001
+
** http://raildar.fr/json/get_train?code=OCESN892368F01001
 +
On peut optionnellement spécifier un champ date=2014-03-02. S'il est ajouté, la mission correspondant à ce jour sera indiquée
  
== next_missions ==
+
== json/next_missions ==
 
retourne les prochains trains circulant dans une gare
 
retourne les prochains trains circulant dans une gare
 
* id_gare : id de la gare récupérée par la méthode "gare"
 
* id_gare : id de la gare récupérée par la méthode "gare"
** http://www.raildar.fr/xml/next_missions?id_gare=83  
+
** http://www.raildar.fr/json/next_missions?id_gare=83  
  
 
(l'id du train est le numéro unique en base associé au train en question, num est son numéro SNCF, time_théorique est l'heure de passage officielle dans la gare, minutes_retard est le retard éventuel, time_reel est l'addition des deux, info est l'éventuel détail sur le retard. Lorsque minutes_retard vaut -1, l'arrêt dans cette gare a été annulé)
 
(l'id du train est le numéro unique en base associé au train en question, num est son numéro SNCF, time_théorique est l'heure de passage officielle dans la gare, minutes_retard est le retard éventuel, time_reel est l'addition des deux, info est l'éventuel détail sur le retard. Lorsque minutes_retard vaut -1, l'arrêt dans cette gare a été annulé)
  
== get_mission ==
+
== json/get_mission ==
retourne la liste des gares d'une mission spécifique
+
retourne les infos détaillées d'une mission et la liste des gares qu'elle dessert
 
* id_mission : id de la mission récupéré par la méthode "next_mission"
 
* id_mission : id de la mission récupéré par la méthode "next_mission"
** http://www.raildar.fr/xml/get_mission?id_mission=135776 (indication du nom et des coordonnées de chaque gares, de l'heure de passage théorique, du retard et de l'info concernée)
+
** http://www.raildar.fr/json/get_mission?id_mission=135776
  
== get_near_missions ==
+
== get_near_missions (deprecated) ==
 
retourne la liste des trains circulant à proximité
 
retourne la liste des trains circulant à proximité
 
* lat / lng : latitude et longitude du point de recherche
 
* lat / lng : latitude et longitude du point de recherche
Ligne 56 : Ligne 70 :
 
** http://www.raildar.fr/xml/get_near_missions?lat=45.888&lng=4.8041&dist=20&limit=10
 
** http://www.raildar.fr/xml/get_near_missions?lat=45.888&lng=4.8041&dist=20&limit=10
  
== guess_my_train ==
+
== json/guess_my_train ==
A venir : savoir dans quel train on est.
+
Permet de tenter de deviner dans quel train on est
 +
* lat & lng : latitude et longitude de la personne
 +
** http://www.raildar.fr/json/guess_my_train?lat=47.5&lng=3.5
  
== get_circulation ==
+
(la réponse contient la liste des trains à proximité, agrémentés, pour chacun, d'une distance à vol d'oiseau, d'une distance par le rail et de la différence des deux. Plus cette différence est faible, plus la probabilité que la personne soit dans ce train est élevée. Lorsque la différence est supérieure à 500, il est probable que les coordonnées ne correspondent à aucune gare ou à aucun tronçon ferré)
 +
 
 +
== json/get_circulation ==
 
retourne la liste des trains en circulation. Voir ci dessous pour la signification des champs.
 
retourne la liste des trains en circulation. Voir ci dessous pour la signification des champs.
* n'importe_quel_nom : chaine arbitraire (epoch courrante, c'est bien) pour bypasser le cache du serveur.
+
* n'importe_quel_nom : chaîne arbitraire (epoch courante, c'est bien) pour bypasser le cache du serveur.
* [id_mission] : permet de ne retourner qu'un seul train (il faut qu'il circule :))
+
* [id_mission] : permet de ne retourner qu'un seul train en fonction de son id_mission
* [regions=yes] : exclusif de id_mission. Permet d'obtenir des statistiques globalisées par régions
+
* [id_gare] : permet de ne retourner que les missions passant ou étant passées par une gare spécifique
* [date] : permet de spécifier une date (format epoch) dans le passé pour récupérer la situation globale de circulation à un instant T. Le serveur retournera la situation connue la plus proche ou une page vide si l'info n'est pas dispo
+
* [regions=yes] : exclusif de id_mission et id_gare. Permet d'obtenir des statistiques globalisées par régions
** http://www.raildar.fr/xml/map_generic?date=1387727478
+
* [date] : exclusif de tous les autres paramètres. Permet de spécifier une date (format epoch) dans le passé pour récupérer la situation globale de circulation à un instant T. Le serveur retournera la situation connue la plus proche ou  
 +
une page vide si l'info n'est pas dispo
 +
* [bbox] : bouding box demandée (format : &bbox=lat_min,lng_min,lat_max,lng_max  )
  
== draw_line ==
+
** http://www.raildar.fr/xml/map_generic?date=1387727478&whatever=_34626236247
retourne la sequence GPS permettant de relier deux gares par leur id
+
* id1 id2 : ids des gares de départ et destination (récupérable par la méthode "gare")
+
** http://www.raildar.fr/xml/draw_line?id1=60&id2=70
+
 
+
== show_trajet ==
+
retourne la sequence GPS d'un train précis
+
* id_train : id du train dans la base, récupérable par get_train, next_missions ou get_circulation
+
** http://raildar.fr/xml/show_trajet?id_train=22120
+
 
+
== map_generic ==
+
déprecated, sera supprimé sous peu
+
  
= Commentaires =
+
=== Signification des champs retournés par get_circulation ===
== Signification des champs retournés par get_circulation ==
+
 
* lat/lng : position du train
 
* lat/lng : position du train
 
* pos_type :  
 
* pos_type :  
Ligne 97 : Ligne 105 :
 
* last_update : heure de la dernière mise à jour de position
 
* last_update : heure de la dernière mise à jour de position
 
* heading : direction de la prochaine gare depuis la position du train
 
* heading : direction de la prochaine gare depuis la position du train
 +
 +
== draw_line ==
 +
retourne la sequence GPS permettant de relier deux gares par leur id
 +
* id1 id2 : ids des gares de départ et destination (récupérable par la méthode "gare")
 +
** http://www.raildar.fr/xml/draw_line?id1=60&id2=70
 +
 +
== json/show_trajet ==
 +
retourne un objet geoJSON contenant la séquence GPS d'un train précis, la liste des gares traversées et les infos sur le train
 +
* id_train : id du train dans la base, récupérable par get_train, next_missions ou get_circulation
 +
** http://raildar.fr/xml/show_trajet?id_train=22120
 +
 +
=Informations=
 +
== liste des sources de données gérées et des brands pour chacune==
 +
http://raildar.fr/json/sources_brands.json

Version actuelle en date du 6 mars 2014 à 21:33

l'API Raildar est encore en développement, vous pouvez demander à peu près tout ce que vous voulez sur le PAD principal.

Un peu de vocabulaire

  • "gare" désigne une station de train
  • "train" désigne un train spécifique (par exemple le Paris-Lyon de 8h23 les jours de semaine)
    • "num_train" est le numéro de circulation du train au sens SNCF
    • "id_train" est l'identifiant du train dans la base raildar
  • "mission" est l'instance spécifique d'un train un jour donné
  • "arret" est l'élément de mission qui correspond à un arrêt d'un train en gare, associé à un retard éventuel et à une raison
  • "position extrapolée" signifie que le train est placé sur une ligne droite entre la gare précédente et la gare suivante, donc probablement pas au bon endroit
  • "position GPS théorique" signifie que le train est en principe sur ses rails et que sa position est calculée en fonction des heures de passage et du retard annoncé

Identification des sources

Raildar s'appuie sur plusieurs sources qui peuvent ou doivent être indiquées dans plusieurs méthodes avec le switch ?id_source=x

  • 1 : TER / Intercité / TGV / idTGV / Thalys
  • 2 : Eurostar
  • 3 : Transilien / RER
  • 4 : Tisseo (non implémentée)
  • 6 : RATP (non implémentée)
  • 7 : IrishRail
  • 8 : NetworkRail (Angleterre, non implémentée)

Méthodes

json/gares

retourne un listing de gares. L'ensemble des gares connues est renvoyée si aucun paramètre n'est indiqué

Les deux méthodes lat/lng et search ne peuvent être associées

xml/get_gare (deprecated)

retourne une gare à partir de son ID

json/get_train

retourne un ou plusieurs trains ainsi que la dernière date ou ils ont été détectes, en fonction de (au choix) :

On peut optionnellement spécifier un champ date=2014-03-02. S'il est ajouté, la mission correspondant à ce jour sera indiquée

json/next_missions

retourne les prochains trains circulant dans une gare

(l'id du train est le numéro unique en base associé au train en question, num est son numéro SNCF, time_théorique est l'heure de passage officielle dans la gare, minutes_retard est le retard éventuel, time_reel est l'addition des deux, info est l'éventuel détail sur le retard. Lorsque minutes_retard vaut -1, l'arrêt dans cette gare a été annulé)

json/get_mission

retourne les infos détaillées d'une mission et la liste des gares qu'elle dessert

get_near_missions (deprecated)

retourne la liste des trains circulant à proximité

json/guess_my_train

Permet de tenter de deviner dans quel train on est

(la réponse contient la liste des trains à proximité, agrémentés, pour chacun, d'une distance à vol d'oiseau, d'une distance par le rail et de la différence des deux. Plus cette différence est faible, plus la probabilité que la personne soit dans ce train est élevée. Lorsque la différence est supérieure à 500, il est probable que les coordonnées ne correspondent à aucune gare ou à aucun tronçon ferré)

json/get_circulation

retourne la liste des trains en circulation. Voir ci dessous pour la signification des champs.

  • n'importe_quel_nom : chaîne arbitraire (epoch courante, c'est bien) pour bypasser le cache du serveur.
  • [id_mission] : permet de ne retourner qu'un seul train en fonction de son id_mission
  • [id_gare] : permet de ne retourner que les missions passant ou étant passées par une gare spécifique
  • [regions=yes] : exclusif de id_mission et id_gare. Permet d'obtenir des statistiques globalisées par régions
  • [date] : exclusif de tous les autres paramètres. Permet de spécifier une date (format epoch) dans le passé pour récupérer la situation globale de circulation à un instant T. Le serveur retournera la situation connue la plus proche ou

une page vide si l'info n'est pas dispo

  • [bbox] : bouding box demandée (format : &bbox=lat_min,lng_min,lat_max,lng_max )

Signification des champs retournés par get_circulation

  • lat/lng : position du train
  • pos_type :
    • 1 pour GPS
    • 2 pour extrapolée
  • retard : minutes de retard du train. Si ='-1', le train a été annulé
  • brand : type de train (TER, TGV, Thalys, ...)
  • num : numéro du train indiqué par le gestionnaire
  • terminus : nom de la gare terminus
  • id_terminus : id de la gare terminus
  • next_gare : nom de la prochaine gare
  • id_next_gare : id de la prochaine gare
  • minutes_to_next_gare : temps en minutes avant la prochaine gare
  • last_check : heure de la dernière vérification auprès d'infolignes
  • last_update : heure de la dernière mise à jour de position
  • heading : direction de la prochaine gare depuis la position du train

draw_line

retourne la sequence GPS permettant de relier deux gares par leur id

json/show_trajet

retourne un objet geoJSON contenant la séquence GPS d'un train précis, la liste des gares traversées et les infos sur le train

Informations

liste des sources de données gérées et des brands pour chacune

http://raildar.fr/json/sources_brands.json