Introduction

Cette page est destinée aux opérateurs qui souhaitent s'intégrer à l'API le.taxi. En suivant cette documentation, vous saurez créer un taxi, mettre à jour sa géolocalisation, mettre à jour son statut et recevoir une course.

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

Création d'un taxi

Pour l'API, un taxi est constitué de trois objets : un conducteur (driver), un véhicule (vehicle) et une autorisation de stationnement (ads). Ces objets doivent être créés afin de créer un nouveau taxi.

Il est à votre charge de demander et vérifier les pièces justificatives permettant au taxi d'exercer :

Création du conducteur

L'endpoint POST /drivers est utilisé pour créer un nouveau conducteur.

Exemple d'appel
$> curl 'https://dev.api.taxi/drivers/' \
      -X POST \
      -H 'X-VERSION: 3' \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'X-API-KEY: XXX' \
      -d '
{
  "data": [{
    "birth_date": "2020-03-05",
    "departement": {
      "nom": "string",
      "numero": "string"
    },
    "first_name": "string",
    "last_name": "string",
    "professional_licence": "string"
  }]
}'

Création du véhicule

L'endpoint POST /vehicles permet de créer un nouveau véhicule.

Exemple d'appel
$> curl 'https://dev.api.taxi/vehicles/' \
      -X POST \
      -H 'X-VERSION: 3' \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'X-API-KEY: XXX' \
      -d '
{
  "data": [
    {
      "color": "string",
      "pet_accepted": true,
      "special_need_vehicle": true,
      "cpam_conventionne": true,
      "licence_plate": "string",
      "model_year": 0,
      "type_": "sedan",
      "nb_seats": 0,
      "constructor": "string",
      "model": "string"
    }
  ]
}'

Le seul paramètre requis est licence_plate. Les autres sont optionnels mais permettent au client de retrouver plus facilement le taxi.

Création de l'ADS

L'endpoint POST /ads permet de créer une nouvelle autorisation de stationnement.

$> curl 'https://dev.api.taxi/ads/' \
      -X POST \
      -H 'X-VERSION: 3' \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'X-API-KEY: XXX' \
      -d '
{
  "data": [
    {
      "category": "string",
      "vehicle_id": 0,
      "insee": "string",
      "numero": "string",
      "owner_name": "string",
      "owner_type": "company",
      "doublage": true
    }
  ]
}'

Paramètres :

Il est possible de créer un taxi en faisant un POST /taxis en fournissant les informations sur le chauffeur, le véhicule et l'autorisation de stationnement.

Exemple d'appel
$> curl 'https://dev.api.taxi/taxis/' \
      -X POST \
      -H 'X-VERSION: 3' \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'X-API-KEY: XXX' \
      -d '
{
  "data": [
    {
      "ads": {
        "insee": "string",
        "numero": "string"
      },
      "driver": {
        "departement": "string",
        "professional_licence": "string"
      },
      "vehicle": {
        "licence_plate": "string"
      }
    }
  ]
}'

L'identifiant retourné doit être conservé afin de mettre à jour la position et le statut du taxi.

Géolocalisation

Lorsqu'un taxi est en maraude, vous devez envoyer sa géolocalisation toutes les 5 secondes sur le serveur geoloc.dev.api.taxi en UDP sur le port 80.

La requête de mise à jour de la géolocalisation doit contenir un hash d'identification. Ce hash est un SHA1 de la concaténation des champs suivants, dans l'ordre, et sans séparateur : timestamp, operator, taxi, lat, lon, device, status, version, api_key.

Ci-dessous un exemple en python d'une fonction envoyant au serveur de geolocalisation la position d'un taxi.

from hashlib import sha1
from time import time
import socket
import json


GEOTAXI_HOST = 'geoloc.dev.api.taxi'
GEOTAXI_PORT = 80


def send_position(lon, lat, taxi_id, operator, apikey):
    payload = {
        "timestamp": int(time()),
        "operator": operator,
        "taxi": taxi_id,
        "lat": lat,
        "lon": lon,
        "device": "phone",
        "status": "free",
        "version":"2",
    }
    h = ''.join(
        str(payload[k]) for k in ['timestamp', 'operator', 'taxi', 'lat', 'lon', 'device', 'status', 'version']
    )
    h += apikey
    payload['hash'] = sha1(h.encode('utf-8')).hexdigest()

    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
    sock.sendto(json.dumps(payload).encode(), (GEOTAXI_HOST, GEOTAXI_PORT))

Statut du taxi

Le taxi doit avoir le statut free pour être vu par les clients. La mise à jour de ce statut se fait avec l'endpoint PUT /taxis/:taxi_id.

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

Les statuts possibles sont:

Recevoir une course

Vous devez mettre en place une API REST acceptant les requêtes POST de la part de nos serveurs. Cette API recevra les demandes de courses au format JSON, et devra les faire parvenir au taxi concerné.

Il y a deux méthodes pour faire parvenir la demande au taxi :

Quelle que soit la méthode que vous choisissez, vous aurez un maximum de 10 secondes pour nous indiquer que le chauffeur a bien reçu la notification. Il aura alors 30 secondes pour accepter ou refuser la course. Référez-vous à la section statut de la course pour plus d'informations.

Serveur d'exemple
from flask import Flask, request
from flask_caching import Cache

config = {
    "DEBUG": True,
    "CACHE_TYPE": "filesystem",
    "CACHE_DEFAULT_TIMEOUT": 300,
    "CACHE_DIR": "/tmp/server_cache"
}

app = Flask(__name__)
app.config.from_mapping(config)
cache = Cache(app)

@app.route('/receive_hail', methods=['POST'])
def receive_hail():
    params = request.get_json()
    hail_id = params['data'][0]['id']
    taxi_id = params['data'][0]['taxi']['id']
    cache.set('taxi_current_hail_{}'.format(taxi_id), hail_id)
    return params

@app.route('/current_hail/')
def current_hail(taxi_id):
    return {
        "hail_id": cache.get('taxi_current_hail_{}'.format(taxi_id))
    }

Statut de la course

Ce schéma présente les différents statuts que peut prendre une course.

Les mises à jour effectuables par un opérateur sont matérialisées par des flèches vertes. Faisons un zoom sur cette partie.

Voici textuellement le déroulé de la course :

Une fois que la course a le statut received_by_taxi, trois mises à jour sont possibles : Dans le cas où aucune mise à jour n'est effectuée en 30 secondes, la course passe au statut timeout_taxi.

L'endpoint PUT /hails/:hail_id permet de mettre à jour le statut d'une course.

Exemple d'appel
$> curl 'https://dev.api.taxi/hails/:hail_id/' \
      -X POST \
      -H 'X-VERSION: 3' \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'X-API-KEY: XXX' \
      -d '
{
  "data": [
    {
      "status": "received_by_taxi"
    }
  ]
}'
Cas partuclier pour le statut accepted_by_taxi

Lorsque le taxi accepte la course et que le statut est changé à accepted_by_taxi, il est nécessaire de fournir un numéro de téléphone sur lequel le taxi est joignable dans le champ taxi_phone_number.

$> curl 'https://dev.api.taxi/hails/:hail_id/' \
      -X POST \
      -H 'X-VERSION: 3' \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'X-API-KEY: XXX' \
      -d '
      {
  "data": [
    {
      "status": "accepted_by_taxi",
      "taxi_phone_number": "+33422521010"
    }
  ]
}'
Changements de statut automatiques

Une fois la course acceptée, si le statut du taxi change pour occupied en utilisant l'endpoint PUT /taxis/:taxi_id, le statut de la course passe automatiquement à customer_on_board. Si le taxi passe ensuite en free ou off, la course est considérée terminée et passe donc automatiquement en finished.

Signalement de client

Un problème lors de la course peut être signalé en utilisant l'endpoint PUT /hails/hail_id, en fournissant le paramètre reporting_customer à true et le champ reporting_customer_reason à une des valeurs suivantes :