Ubikiwi API : documentation

Introduction

Ubikiwi API permet deux choses :

  • le calcul de temps de trajet entre des points de départs (origins) et d'arrivées (destinations)
  • la génération de lignes isochrones au format geojson

Les modes de transport pris en compte sont la marche à pied ainsi que l'ensemble des transports en commun. Le service est destiné aux développeurs qui souhaitent intégrer à leur projet ces fonctionnalités. Des exemples d'utilisation sont disponibles ici et ici.

Lorsque Ubikiwi API calcul des temps de trajet, il peut les enrichir d'informations plus détaillées sur les lignes de transport utilisées.

Couverture

Mise en route

Commencer à utiliser Ubikiwi API est l'affaire de quelques minutes :

  1. créez vous gratuitement un compte
  2. dans votre espace personnel, générez une clef d'authentification (token).
  3. faites vos premières requêtes !

Format général d'une requête

Les requêtes se font indifféremment via les méthodes get ou post. Vous pouvez soit:

  • les taper directement dans votre navigateur en vous loggant avec votre nom d'utilisateur et mot de passe
  • utiliser toute autre méthode (curl, python, javascript,...) en utilisant votre token. Plus de détail à ce sujet ici.

Les requêtes ont le format général suivant:

https://api.ubikiwi.com/v1/?parameters

parameters représente la liste des paramètres passés à l'API. Certains d'entre eux sont obligatoires, d'autres sont facultatifs comme décrit par la suite.

Requêtes de type "temps de trajets"

Ce type de requêtes est utilisé pour obtenir les temps de transport depuis une origine vers de nombreuses destinations.

Exemple de requête simple

Avant de décrire en détail les possibilités offertes par ce type de requêtes, voici un exemple de requête simple :
 https://api.ubikiwi.com/v1/?origins={"crd":"48.8307,2.3436"}&destinations=48.8512812,2.3314782&output={"type":"travelTimes"}
        
qui renvoit la réponse suivante formatée en json:
            {
                "origins": [
                    {
                        "status": "OK",
                        "crd": [
                            48.8307,
                            2.3436
                        ],
                        "w": null,
                        "id": 128788,
                        "l": null
                    }
                ],
                "destinations": [
                    {
                        "status": "OK",
                        "index": 0,
                        "travelTime": 18,
                        "crd": [
                            48.8512812,
                            2.3314782
                        ],
                        "directions": [],
                        "id": 51650
                    }
                ]
            }
  

Bravo ! Vous venez de faire votre première requête et savez maintenat qu'aller du point (48.8307,2.3436) au point (48.8512812,2.3314782) en tranports en commun met 18 minutes. Vous avez remarqué, il y a d'autres champs, nous allons les détailler par la suite.

Paramètres obligatoires

output

Ce paramêtre reçoit un objet JSON et permet de spécifier le type de sortie attendue. Nous souhaitons ici obtenir des temps de trajet, il prend donc la forme:

output={"type":"travelTimes"}


origins

Ce paramêtre contient une ou plusieurs adresses d'origines, correspondants aux points de départs de vos trajets, séparés par des |. Chaque origine prenant la forme d'un objet JSON comportant plusieurs attributs:

  • "crd" : la position du point sous la forme d'un couple de coordonnées latitude,longitude. Attention à ne pas mettre d'espaces après la virgule !
  • "l" : une limite de temps en minutes au delà de laquelle les temps de transports ne sont pas calculés. Cela permet à l'API d'offrir de très bonnes performances lorsque les destinations situées au delà d'une certaine limite doivent être éliminées. Dans ce cas l'API renverra pour les destinations concernées un code d'erreur OUT_OF_BOUNDS.

Exemples

&origins={"crd":"48.855,2.357"}

Avec l'ajout d'une limite temporelle de 60 minutes:

&origins={"crd":"48.855,2.357", "l":60}

Requêtes multi-origines

Si origins contient plusieurs éléments, le temps de transport indiqué au niveau de chaque destination est le temps de transport moyen depuis l'ensemble des origines spécifiées. Par exemple, si origins contient la valeur suivante:

&origins={"crd":"48.855,2.357", l:60}|{"crd":"49.855,2.389", "l":30}
  • les destinations situées à plus de 60 minutes du premier point auront un status OUT_OF_BOUNDS
  • les destinations situées à plus de 30 minutes du second point auront un status OUT_OF_BOUNDS
  • les autres destinations auront un temps de trajet, correspondant au temps moyen pour s'y rendre depuis les deux origines.

destinations

Ce paramêtre contient une ou plusieurs destinations vers lesquelles vous souhaitez obtenir un temps de trajet, séparées par des |. Comme pour les origines, les destinations sont représentées par des couples de coordonnées latitude,longitude.

exemples

&destinations=48.851,2.342
&destinations=48.851,2.342|48.782,2.542

exemple de requête complète vers deux destinations:

 https://api.ubikiwi.com/v1/?origins={"crd":"48.8307,2.3436"}&destinations=48.851,2.342|48.782,2.542&output={"type":"travelTimes"}
  

Paramètres optionnels

directions

Ce paramêtre permet de demander à Ubikiwi API de renvoyer en plus du temps de transport le détail du voyage. Les valeurs possibles sont:

  • none : valeur par défaut, aucun détail n'est affiché
  • basic : affiche les noms des lignes empruntées
Par exemple:
https://api.ubikiwi.com/v1/?origins={"crd":"48.8307,2.3436"}&destinations=48.8512812,2.3314782&output={"type":"travelTimes"}&directions=basic
Ce qui nous donne en sortie :
    "destinations": [
        {
            "status": "OK",
            "index": 0,
            "travelTime": 18,
            "crd": [
                48.8512812,
                2.3314782
            ],
            "directions": [
                {
                    "fromOriginId": 128788,
                    "steps": [
                        "Metro 6",
                        "Metro 4"
                    ],
                    "travelTime": 18
                }
            ],
            "id": 51650
        }
    ]

A l'avenir, il est prévu d'ajouter un nouveau champ aux côtés de "steps" donnant le temps de chaque tronçon de voyage.

Requêtes de type "isochrones"

Ce type de requêtes renvoit la géométrie des lignes isochrones sous la forme de geojson.

Paramètres obligatoires

output

Ce paramêtre reçoit un objet JSON et permet de spécifier le type de sortie attendue.

  • "type" vaut ici "contours"
  • "levels" est la liste des plages d'isochrones désirées. Par exemple [0,10, 20, 30] va permettre de tracer les lignes isochrones 10, 20 et 30 minutes.
  • "averageType" vaut soit "mean" soit "max" et permet de spécifier la sortie désirée lorsque plusieurs origines sont spécifiées. Respectivement un temps moyen ou un temps maximal.

exemples

output={"type":"contours", "levels":[0,10,20], "averageType":"max"}

origins

Paramètre identique à celui décrit pour les requêtes de type "travelTimes".


Sortie

La sortie est un json contenant la variable "contours". Le contenu de cette variable est un geojson directement exploitable. Vous pouvez par exemple le visualiser instantanément sur ce site.


Exemples de requête complètes

Ligne isochrone 10 minutes depuis 49.04259416332075,2.4231719970703125 :
 https://api.ubikiwi.com/v1/?origins=49.04259416332075,2.4231719970703125&output={"type":"contours","levels":[0,10]}
Lignes isochrones 50 et 60 minutes depuis 49.04259,2.4231 et 49.00259,2.42317199. Les lignes correspondants au temps de tranport maximal depuis ces deux destinations :
https://api.ubikiwi.com/v1/?origins=49.04259,2.4231|49.00259,2.42317199&output={"type":"contours","levels":[0,50,60], "averageType":"max"}
idem, avec un temps moyen :
https://api.ubikiwi.com/v1/?origins=49.04259,2.4231|49.00259,2.42317199&output={"type":"contours","levels":[0,50,60], "averageType":"mean"}

Authentification

L'authentification se fait par l'ajout d'un header HTTP Authorization contenant votre token précédé du mot Token. Par exemple :

Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

Codes d'erreur

Si la requête n'a pas pu être traitée, l'API renvoit une erreur http 400. Le corps du message contient un json et des informations supplémentaires sont généralement indiquées dans le champ "error_message".

De plus, pour chacune des origines et destinations un champ "status" donne des informations sur le traitement de ce point en particulier

  • OK : L'origine ou la destination correspondante est valide. Si c'est une destination, le calcul du temps de trajet a été effectué avec succès et le champ travelTime contient une réponse valide.
  • OUT_OF_BOUNDS : S'applique aux destinations uniquement. Signifie que la destination est plus loin que la limite de temps spécifiée dans l'origine correspondante. Si aucune limite n'est spécifiée, la valeur par défaut est de 10h.
  • OUTSIDE_AREA : Signifie que le point est situé en dehors de la zone de couverture du service, ou bien qu'il est à plus de 200m d'une intersection.

exemple

La requete suivante contient une origine en dehors de la zone de couverture et ne peut être traitée :

https://api.ubikiwi.com/v1/?destinations=48.8512812,2.3314782&origins={"crd":"0,0"}&output={"type":"travelTimes"}
La réponse obtenue est erreur 400 contenant:
  {
      "error_message": "error on at least one of the origins",
      "origins": [
          {
              "status": "OUTSIDE_AREA",
              "crd": [
                  0,
                  0
              ],
              "w": null,
              "id": null,
              "l": null
          }
      ],
      "destinations": [
          {
              "status": "OK",
              "index": 0,
              "id": 51650,
              "crd": [
                  48.8512812,
                  2.3314782
              ]
          }
      ]
  } 

Etat du service (béta)

Un état temps réel du service et son historique est disponible à cette adresse. Cette fonctionnalité est encore en test et est susceptible de changer.