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 :

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"
    }
  ]
}'