Introduction

Cette page est destinée aux moteurs de recherche qui souhaitent s'intégrer à l'API le.taxi. En suivant cette documentation, vous saurez lister les taxis d'une zone, puis les réserver.

Prérequis
  • Prendre connaissance de la documentation d'introduction.
  • Avoir un compte sur l'environnement de développement dev.api.taxi.

Lister les taxis

L'endpoint GET /taxis permet de lister les taxis autour d'une coordonnée géographique. Les paramètres attendus sont :

Nom du paramètre Valeur
lon (requis) longitude autour de laquelle rechercher un taxi
lat (requis) latitude autour de laquelle rechercher un taxi
count (opt) nombre maximum de taxis à retourner
favorite_operator (opt) si un taxi a plusieurs opérateurs actifs, l'opérateur renseigné sera préféré
Exemple d'appel
$> curl 'https://dev.api.taxi/taxis/?lon=2.35&lat=48.85' \
      -H 'Accept: application/json' \
      -H 'X-Version: 3' \
      -H 'X-API-KEY: XXX'

Aucun taxi ne sera retourné si aucun taxi n'est libre autour de ce point.

Créer une course

L'endpoint POST /hails permet de créer une course :

$> curl 'https://dev.api.taxi/hails/' \
      -X POST \
      -H "X-VERSION: 3" \
      -H "Content-Type: application/json" \
      -H "Accept: application/json" \
      -H "X-API-KEY: XXX \" \
      -d '
{
  "data": [
    {
      "customer_lat": 48.85,
      "customer_lon": 2.35,
      "customer_address": "52 boulevard Saint-Germain, Paris 75005",
      "taxi_id": "taxi_id",
      "customer_phone_number": "0673457191",
      "operateur": "neotaxi",
      "customer_id": "internal_customer_id"
    }
  ]
}'

Ces points sont à noter :

Nouveau : session_id

L'API considère maintenant les créations de course d'un même client comme faisant partie de la même session utilisateur quand elles sont assez proches dans le temps (moins de 5 minutes entre deux requêtes).

La première requête se fait sans session_id et initie la session utilisateur. C'est l'API qui assigne le session_id en le fournissant dans la réponse. L'application fournit ensuite ce session_id dans les requêtes suivantes de la même session utilisateur. l'API vérifiera que cet ID existe et correspond bien à ce client, mais il est à la discrétion de l'application de déterminer la durée de validité de cette session.

Il suffit de faire une requête sans session_id pour initier une nouvelle session. L'API détecte automatiquement les requêtes espacées de moins de 5 minutes pour les assigner automatiquement à la même session, mais ce champ pourrait être rendu obligatoire dans une future version de l'API.

Exemple de champ session_id dans la requête ou la réponse&nbps;:

"session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"

Déroulement de la course

Le suivi d'une course se fait par des appels successifs à l'endpoint GET /hails/:hail_id. Le schéma ci-dessous montre les différents statuts d'une course, et leurs enchainements possibles.

Il est nécessaire de faire des requêtes régulièrement sur l'endpoint GET /hails/:hail_id afin d'informer votre client de l'évolution de la course, de lui permettre de passer au statut suivant lorsque c'est nécessaire, ou de l'informer d'une erreur. Faisons un zoom sur les actions que vous devez exécuter :

Lorsque l'API reçoit une demande de course, celle-ci est transmise à l'opérateur du taxi. Dans le cas où le taxi accepte la course, vous avez une vingtaine de secondes pour demander à votre client de confirmer une dernière fois la course. Deux statuts sont alors disponibles :

Vous devez à tout moment permettre au client d'annuler la course en passant au statut incident_customer.

Exemple d'appel
$> curl 'https://dev.api.taxi/hails/:hail_id/' \
      -X PUT \
      -H 'X-VERSION: 3' \
      -H 'Content-Type: application/json' \
      -H "Accept: application/json" \
      -H 'X-API-KEY: XXX' \
      -d '
{
  "data": [
    {
      "status": "accepted_by_customer"
    }
  ]
}'

Notation de la course

Un client a la possibilité d'attribuer une note comprise entre 1 et 5 à la course en fournissant le paramètre rating_ride à l'endpoint PUT /hails/:id. Le paramètre optionnel rating_ride_reason peut aussi être renseigné, et doit avoir une des valeurs suivantes :

Exemple d'appel
$> curl 'https://dev.api.taxi/hails/:hail_id/'
      \ -X PUT \
      -H 'X-VERSION: 3' \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'X-API-KEY: XXX" \
      -d '
{
  "data": [
    {
      "rating_ride": 1,
      "rating_ride_reason": "no_credit_card"
    }
  ]
}'