Operator

The Taxi Operator is a technical service provider connecting a taxi to the Taxi Exchange Point (TXP). There are several main interactions between Operators and the TXP: declaring a taxi (including registering the vehicle, driver and license), updating its location and status, receiving a hail issued by a client for a taxi, querying and updating the status of the hail.
Warning: in accordance with the Terms of Service, you are allowed to declare a taxi and update its location and status only within the context of the real-time journey of a real taxi driver: automation, replay and any other form of mass data gathering is expressly forbidden.

Registering a vehicle

Registering a vehicle is done through a HTTPS POST request to the vehicles API.
The structure of the required vehicle object is described in the reference documentation..
Calls to this API are idempotent: you can update a vehicle simply by submitting the updated vehicle object. If the licence_plate is different, a new vehicle will be created; if the licence_plate is unchanged, the vehicle will be updated.

Registering a driver

Registering a driver is done through a HTTPS POST request to the drivers API.
The structure of the required driver object is described in the reference documentation..
Calls to this API are idempotent: you can update a driver simply by submitting the updated driver object. If the department or professional_licence is different, a new driver will be created; if the department and professional_licence are unchanged, the driver will be updated.

Registering a license (ADS)

Registering a license (in French Autorisaton De Stationnement ADS) is done through a HTTPS POST request to the ads API.
The structure of the required ads object is described in the reference documentation..
Calls to this API are idempotent: you can update a license (ADS) simply by submitting the updated ads object. If the insee or numero is different, a new license (ADS) will be created; if the insee and numero are unchanged, the license (ADS) will be updated.

Declaring a taxi

Declaring a taxi is done through a HTTPS POST request to the taxis API.
The structure of the required taxi object is a minimalistic version of the one described in the reference documentation containing only the identifiers of the vehicle, driver and ads and the initial status of the taxi. The vehicle, driver and ads used to compose a taxi need to have been registered first through their respective API.

Taxi declaration

{
  "data": [
    {
      "vehicle": {
         "licence_plate": "WM-220-VP"
       },
      "driver": {
         "departement": "75",
         "professional_licence": "091402"
       },
      "ads": {
        "insee": "75056",
        "numero": "20997"
      },
      "status": "free"
    }
  ]
}
If successful, the API returns the complete taxi object as described in the reference documentation, including the characteristics of the vehicle and most importantly the unique identifier id of the taxi that will be used for subsequent communications.
Calls to this API are idempotent: if you resubmit the same triplet of vehicle, driver and ads, the taxi returned will have the same id.

Updating the location of a taxi

The location of the taxi is updated through a UDP datagram sent to the geolocation server (geoloc subdomain of this server) on port 80.
The JSON payload of the UDP datagram should be as follows.
{
    "timestamp":"1430076493",
    "operator":"neotaxi",
    "taxi":"9cf0ebfa-dd37-45c4-8a80-60db584535d8",
    "lat":"2.38852053",
    "lon":"48.84394873",
    "device":"phone",
    "status":"0",
    "version":"1",
    "hash":"2fd4e1c67a2d28fced849ee1bb76e7391b93eb12"
}
Key Value Type Description
timestamp string Exact time at which the location was determined, formatted as a Unix time (IEEE 1003.1-2008 POSIX)
Warning: as per the POSIX specification, this should be UTC time without any timezone information
Warning: locations in the future (or too old in the past) will be silently discarded.
operator string login of the certified operator
taxi string The id of the taxi is the id that was sent back when the taxi was declared (see Déclaring a taxi)
lat string Latitude of the taxi
This should be in JavaScript double precision floating-point format, with decimal separator ".".
You can truncate the values to 6 decimal places if you want to keep the payload as short as possible (6 decimal places is worth up to 10 cm).
lon string Longitude of the taxi
This should be in JavaScript double precision floating-point format, with decimal separator ".".
You can truncate the values to 6 decimal places if you want to keep the payload as short as possible (6 decimal places is worth up to 10 cm).
device string phone, tablet, taximeter or otherdevice
status string always "0" for now (reserved for future use)
version string either "1" or "2" for now (there is no difference concerning the geolocation between version 1 and 2 of the API)
hash string This field is the SHA-1 message digest of the concatenation (without any separator) of the values of the fields timestamp, operator, taxi, lat, lon, device, status and version (in that order) and the API key of the operator (the same API key used to authenticate the HTTPS REST requests).
sha1(concat(timestamp, operator, taxi, lat, lon, device, status, version, api_key))

Updating the status of a taxi

In most cases, the status of the taxi is automaticaly set by the TXP according to the status of a hail.
Outside of the context of a hail, you still need to indicate if the taxi is free or occupied or off. This is done through a HTTPS PUT request to the /taxis/{taxi_id}/ API.

Querying the status and time of last location update of a taxi

In order to check that the updating of the status or location of the taxi worked properly, you can use a HTTPS GET request to the /taxis/{taxi_id}/ API.
Warning: The GET /taxis/{taxi_id}/ API will return the status and the last_update but the lat and lon will be nulled (for privacy reasons).
Warning: in production, you should almost never need the GET /taxis/{taxi_id}/ API:
all necessary informations about taxis around a location are already in the response of the GET /taxis API
and all necessary informations about the chosen taxi are already in the response of the GET /hails/{hail_id} API

Receiving a hail

In order to receive hails, operators need to implement an endpoint on their servers. The endpoint has to be able to receive HTTPS POST requests from the TXP. This is the only endpoint that needs to be implemented on the operator side.
The hail JSON object which will be transmitted as the payload of the HTTPS POST request is detailed in the Reference Documentation.
Accredited operators can enter the URL of their dev, test and prod endpoints on their My Account page.
The endpoint should return one of the valid HTTP status code in the 2xx Success range in case of success, and in the 4xx Client Error or 5xx Server Error in case of error. If the status code is in the 2xx Success range, the response payload can be a JSON hail object, in which case the hail will be updated on the TXP. This response payload can for instance be used to transmit the taxi_phone_number to the TXP.
After the hail has been acknowledged by the operator to the TXP, it should be communicated by the operator to the taxi driver ASAP.

Querying the status of a Hail

In order to keep track of the status of the hail, you can do a HTTPS GET request to the /hails/{hail_id}/ API.
The list of all possible statuses is available in the Reference Documentation.

Updating a Hail

In order to finalise the transaction, the taxi has to acknowledge the hail. It is done through a HTTPS PUT request to the /hails/{hail_id}/ API.
The status of the hail has to be received_by_taxi before the taxi driver is asked to confirm the ride. If you don't send a PUT request with either the accepted_by_taxi or the declined_by_taxi status in the next 30 seconds, the hail will automatically be updated to timeout_taxi and the whole transaction be considered cancelled. You do have to check when you do a PUT with the status accepted_by_taxi that the status in the response is accepted_by_taxi (the taxi is arriving) and not timeout_taxi (your reconfirmation arrived too late, the whole transaction had to be canceled).