Reference Documentation

Taxi

A taxi is the conjunction of a vehicle, a driver and a license (aka ADS). It may be geolocated by one or several operators and hailed by a client.

Taxi Structure

{
  "data": [
    {
     "vehicle": {
        "characteristics": [
          "air_con",
          "amex_accepted",
          "baby_seat",
          "bank_check_accepted",
          "bike_accepted",
          "credit_card_accepted",
          "dvd_player"
          "electronic_toll",
          "every_destination",
          "fresh_drink",
          "gps",
          "luxury"
          "nfc_cc_accepted",
          "pet_accepted",
          "special_need_vehicle",
          "tablet",
          "wifi"
        ],
        "color": "orange",
        "constructor": "Toyota",
        "licence_plate": "WM-220-VP",
        "model": "Prius",
        "nb_seats": 4
      },
      "ads": {
        "insee": "75056",
        "numero": "20997"
      },
      "driver": {
        "departement": "75",
        "professional_licence": "091402"
      },
      "id": "9cf0ebfa-dd37-45c4-8a80-60db584535d8",
      "operator": "neotaxi",
      "rating": 4.65,
      "status": "free",
      "position": {
         "lat": 48.82689259,
         "lon": 2.34191983
       },
       "last_update": 1440169929,
       "crowfly_distance": 4.29
    }
  ]
}
Key Value Type Description
vehicle vehicle A partial vehicle object with only the fields: characteristics, color, constructor, licence_plate, model, nb_seats.
Warning: some of those fields might not be returned (or be returned with a null value) if they were not provided by the taxi operator.
ads ADS A partial ADS object with only the fields: insee, numero.
driver driver A partial driver object with only the fields: departement, professionnal_licence.
id string A long-lived identifier generated for this vehicle/ads/driver triplet by the TXP.
This field should be omitted by operators when declaring a new taxi through a POST request; The newly generated id will be returned in the taxi object sent back as the response.
operator string The name of the operator
rating float The mean of the ratings of last rides of the taxi.
It is calculated by the TXP and falls between 0 and 5.
status status Status of the taxi.
The possible values are described in the Taxi Status section
position {lat,lon} The latitude and longitude of the taxi.
Warning: those values are only returnedi by the TXP in the response to a GET request on the /taxis/ API looking for taxis around a client. They will be nulled when returned in the response to a GET request on the /taxis/{taxi_id}/ API looking for information on a specific taxi.
last_update integer Timestamp of the last geolocation update of the taxi. The format is the usual Unix time (IEEE P1003.1 POSIX) and as such is UTC (no timezone).
crowfly_distance float Distance between the location of the client and the location of the taxi.
This value will only be returned in the response to a GET request on the /taxis/ API looking for taxis around a client. It will be nulled when returned in the response to a GET request on the /taxis/{taxi_id}/ API looking for information on a specific taxi. When not null, the number is in JavaScript double precision floating-point format, with decimal separator ".". It represents the number of km between the client and the taxi measured in a straight line

Taxi Status

This table describes the different values the taxi status can take

Value Description
free The taxi can be hailed
answering The taxi is currently answering to a hail
oncoming The taxi is on its way to meet a customer
occupied The taxi has a customer on board
off The taxi is not logged in or did not update its location recently enough.

License (ADS)

The French taxi license are named "Autorisation De Stationner (ADS)". They are attributed by local authorities (usually municipalities, but also in some cases larger areas like départements.)

Structure

{
  "data": [
    {
      "insee": "75056",
      "numero": "4567",
      "owner_name": "Jean Dupont",
      "owner_type": "individual",
      "category": "perpetual",
      "doublage": false,
      "vehicle_id": 0
    }
  ]
}
Key Value Type Description
insee string Identifier of the local authority who attributed the license (ADS).
In France, the INSEE code of the entity as specified in the Code Officiel Géographique is used.
It is composed of 5 characters (usually 5 digits, except for Corsica where the second character can be "A" or "B") and uniquely identify each municipality (or just two digits for the rare special case of license attributed by départements usually for airports). There are three special cases for Paris (insee code: 75056, the codes of the subdivisions -aka arrondissements- are not used), Lyon (insee code: 69123, idem) and Marseille (insee code: 13055, idem).
Warning: the INSEE code is different from the zipcode (there are very often several municipalities in a single zipcode and in some cases several zipcodes in a single municipality.) The zipcode/INSEE code correspondence can be found in the Base officielle des codes postaux. The usual way to get an INSEE code from a user is to ask for a zipcode, then offer to chose the municipality in a list of the municipalities of the zipcode.
numero string This is the taxi license number (ADS number).
It is often a string of digits but it might for some municipalities contain letters or other characters like dash or slashes.
Warning: This identifier is not unique at the national level: two local authorities can each assign the same number to different licensees.
The couple of this license number (numero) and the licensing authority (insee) is used as the license identifier when declaring a taxi as a vehicle/driver/license triplet.
owner_name string Name of the holder of the license.
Warning: It might be either an individual or a company.
owner_type string The two possible values are company or individual.
category string This field is used for administrative purpose.
When a new license (aka ADS) is created by an Operator, an empty string has to be passed (not a null value)
doublage boolean Some regulation specific to the Paris area limits the working hours of the driver to 10 hours a day. Some licenses (ADS) can be used for 2 shifts a day (by two different drivers) and this field should then be set to true. Others can only be operated 10 hours a day and this field should be set to false.
When a new license (aka ADS) is created by an Operator, this field should always be set to false if the local authority in the insee field is not 75056 (i.e. Paris)
vehicle_id integer This field is used for administrative purpose.
When a new license (aka ADS) is created by an Operator, a 0 or null has to be passed

Driver

Taxi drivers in France have to be registered. They hold a professional licence issued by a local authority (in France the département). This professional license of taxi driver is different from the taxi license (aka ADS).

Structure

{
  "data": [
     {
      "departement": {
        "numero": "54"
        "nom": "Meurthe-et-Moselle",
      },
      "professional_licence": "234567",
      "first_name": "Pierre",
      "last_name": "Durand",
      "birth_date": "1985-12-24"
    }
  ]
}
Key Value Type Description
departement department object The departement object is constituted of the identifier numero and the name nom of the local authority.
For France the list of possible départements is available in the Code Officiel Géographique (columns DEP for the identifier and NCCENR for the name)
Warning: the identifier numero might contain some non-digits characters (2A or 2B for Corsica for instance)
When a new driver is created by an Operator, an empty string or null can be passed instead of the name nom: only the identifier numero is used by the TXP.
professional_licence string Professional license number of the driver.
It is often a string of digits but it might for some départments contain letters or other characters like dash or slashes.
Warning: This identifier is not unique at the national level: two local authorities can each assign the same number to different drivers.
Warning: the typo "licence" (French writing) instead of "license" (English writing) is still in the API (as of version 2).
The couple of this professional license number (professional_licence) and the licensing local authority (departement) is used as the driver identifier when declaring a taxi as a vehicle/driver/license triplet.
last_name string Last name of the driver
first_name string First name of the driver
birth_date string, RFC3339 Birth date of the driver in "YYYY-MM-DD" format.

Vehicle

Vehicles are identified by their license plate. License plates are unique at the national level. License plates are different from the taxi license (aka ADS) and the driver professional license.

Structure

{
  "data": [
    {
      "licence_plate": "WM-220-VP",
      "constructor": "Toyota",
      "model": "string",
      "color": "orange",
      "type_": "sedan",
      "nb_seats": 0,
      "air_con": true,
      "amex_accepted": true,
      "baby_seat": true,
      "bank_check_accepted": true,
      "bike_accepted": true,
      "cpam_conventionne": true,
      "credit_card_accepted": true,
      "dvd_player": true,
      "electronic_toll": true,
      "every_destination": true,
      "fresh_drink": true,
      "gps": true,
      "luxury": true,
      "nfc_cc_accepted": true,
      "pet_accepted": true,
      "special_need_vehicle": true,
      "tablet": true,
      "wifi": true,
      "date_dernier_ct": "2015-12-23",
      "date_validite_ct": "2017-12-23",
      "engine": "string",
      "horse_power": 0,
      "model_year": 0,      
      "relais": true,
      "taximetre": "string",
      "horodateur": "string",
      "id": 0,
    }
  ]
}
Key Value Type Description
licence_plate string License plate of the vehicle.
Warning: the typo "licence" (French writing) instead of "license" (English writing) is still in the API (as of version 2).
The licence_plate is used as the vehicle identifier to declare a taxi as a vehicle/driver/license triplet.
constructor string Constructor of the vehicle
model string Model of the vehicle
color string Color of the vehicle
type_ string Type of the vehicle
The possible values are sedan, station_wagon or mpv
Warning: the name of this key is type_ with the final underscore.
nb_seats integer Number of seating positions available for passengers in the vehicle (not counting the seat of the driver).
As per European Regulation EU/678/2011 the following requirements apply for the counting of the seating positions:
(a) each individual seat shall be counted as one seating position;
(b) in the case of a bench seat, any space having a width of at least 400 mm measured at the seat cushion level shall be counted as one seating position.
(c) however, a space as referred to in point (b) shall not be counted as one seating position where:
(i) the bench seat includes features that prevent the bottom of the manikin from sitting in a natural way - for example: the presence of a fixed console box, an unpadded area or an interior trim interrupting the nominal seating surface;
(ii) the design of the floor pan located immediately in front of a presumed seating position (for example the presence of a tunnel) prevents the feet of the manikin from being positioned in a natural way.
When available, the area intended for an occupied wheelchair shall be regarded as one seating position.
air_con boolean This vehicle is equipped with air conditioning
amex_accepted boolean This vehicle accepts American Express card for any amount (no minimum).
baby_seat boolean This vehicle is equipped with a baby seat
bank_check_accepted boolean This vehicle accepts national bank checks (foreign bank checks might still be refused).
bike_accepted boolean This vehicle can transport a bicycle
credit_card_accepted boolean This vehicle accepts credit card payments for any amount (no minimum).
This should be true for vehicle accepting at least Visa and MasterCard. There is a different boolean amex_accepted for American Express.
dvd_player boolean This vehicle has a dvd player at the disposal of clients during the ride
electronic_toll boolean This vehicle is equipped with an electronic device letting them use express toll booths on toll roads.
every_destination boolean As per the French regulation, taxis can refuse service to clients whose destination is not within their zone. Some taxis do accept any destination outside of their zone. The every_destination boolean should be false by default, and true for taxis who renounce their right to refuse service to clients depending on their destination.
fresh_drink boolean This taxi offers refreshments
gps boolean This vehicle is equipped with GPS navigation.
luxury boolean This is a luxury vehicle
nfc_cc_accepted boolean This vehicle accepts NFC credit card payments.
pet_accepted boolean This vehicle can accommodate pets (understood as cats or small dogs ; other large or unusual pets might still be refused)
special_need_vehicle boolean Wheelchair accessible vehicle as defined in EU/678/2011 (which amends 2007/46/EC).
Vehicle constructed or converted specifically so that they accommodate one or more persons seated in their wheelchairs when travelling on the road.
tablet boolean This vehicle has a digital tablet at the disposal of the clients during the ride.
wifi boolean This vehicle has complimentary WiFi aboard.
cpam_conventionne boolean This vehicle has a convention with social security to transport patients.
This field is used for administrative purpose only.
When a new vehicle is created by an Operator, this field can be omitted or passed with a null value.
date_dernier_ct string, RFC3339 Date of the latest compulsory roadworthiness tests in "YYYY-MM-DD" format.
This field is used for administrative purpose only.
When a new vehicle is created by an Operator, this field can be omitted or passed with a null value.
date_validite_ct string, RFC3339 Expiration date of the latest compulsory roadworthiness tests in "YYYY-MM-DD" format.
This field is used for administrative purpose only.
When a new vehicle is created by an Operator, this field can be omitted or passed with a null value.
engine string Engine type of the vehicle.
This field is used for administrative purpose only.
When a new vehicle is created by an Operator, this field can be omitted or passed with a null value.
horse_power integer Fiscal power of the vehicle.
This field is used for administrative purpose only.
When a new vehicle is created by an Operator, this field can be omitted or passed with a null value.
model_year integer Model year of the vehicle.
This field is used for administrative purpose only.
When a new vehicle is created by an Operator, this field can be omitted or passed with a null value.
relais boolean True if this vehicle is a temporary replacement vehicle for a fully licensed one.
This field is used for administrative purpose only.
When a new vehicle is created by an Operator, this field can be omitted or passed with a null value.
taximetre string Brand and model of the taximeter.
This field is used for administrative purpose only.
When a new vehicle is created by an Operator, this field can be omitted or passed with a null value.
horodateur string Brand and model of the time clock.
This field is used for administrative purpose only.
When a new vehicle is created by an Operator, this field can be omitted or passed with a null value.
id integer This field is used for administrative purpose only.
When a new vehicle is created by an Operator, this field can be omitted or passed with a null value.
There is no need for Operators or Search Engine to store the value returned by the TXP: the field used to uniquely identify vehicles in all transactions with the TXP is the licence_plate.

Hail

After the taxis available around the client have been retrieved, the chosen taxi can be hailed.

Hail Structure

{
  "data": [
    {
      "customer_lat": 48.83245752348135,
      "customer_lon": 2.34375347582593,
      "customer_address": "13 rue des Fossés Saint-Jacques, 75005 Paris",
      "customer_id": "2ca43f3d5351664b0d80c43367fbd2711e6b4c7c",
      "customer_phone_number": "+33662228405",
      "taxi": {
         "id": "Rjk4dTV",
         "last_update": 1440757794,
         "position": {
           "lat": 48.8286262,
           "lon": 2.3263804
         }
      },
      "operateur": "neotaxi",
      "status": "emitted",
      "id": "sDfGh3K",
      "taxi_phone_number": "+33800123456",
      "creation_datetime": "Fri, 28 Aug 2015 12:29:46 -0000",
      "last_status_change": "Fri, 28 Aug 2015 12:29:54 -0000",
      "incident_customer_reason": null,
      "incident_taxi_reason": null,
      "rating_ride": null,
      "rating_ride_reason": null,
      "reporting_customer": null,
      "reporting_customer_reason": null
    }
  ]
}
Key Value Type Description
customer_lat float Latitude of the position of the client.
This should be in JavaScript double precision floating-point format, with decimal separator "."
customer_lon float Longitude of the position of the client.
This should be in JavaScript double precision floating-point format, with decimal separator "."
customer_address string Address of the position of the client.
This address will be used by the taxi driver to find the client.
It should be displayed and validated by the client.
Warning: In some cases, a POI might be more meaningful than a postal address.
customer_id string identifier of the customer.
This identifier is an identifier the Search Engine uses to uniquely identify the client. It can be a database id, an IMEI, a cookie identifier, a hash of a phone number, or any long lived identifier which will stay the same when the same client comes back.
It does not need to carry any signification for the TXP: the TXP does not need the identity of the client.
customer_phone_number string Phone number of the client.
This phone number might be used by the Operator of the taxi in case it proves difficult to find the client.
taxi_id string Identifier of the taxi the client is hailing.
This identifier was returned by the TXP in the Taxi object.
Warning: for historical reasons, when a search engine sends a new hail to the TXP, the taxi id should be passed as a taxi_id field directly in the hail object.
In all subsequent exchanges, including when the TXP forwards the hail to the operator, the taxi id appears instead as a id field in an embedded taxi JSON object inside the hail.
operateur string Identifier of the Operator of the taxi the client is hailing.
This identifier was returned by the TXP in the Taxi object.
status status status of the hail.
All possible values are described here
id string Identifier of the hail.
This identifier should be null or omitted when a search engine sends a new hail to the TXP. The newly generated id will be in the hail object returned by the TXP as a response.
taxi_phone_number string Phone number the client should call in case of problem.
This phone number can be either the number of the call center of the operator or the mobile phone number of the taxi driver. It has to be reachable at the time of the ride: call center numbers should only be transmitted during opening times.
incident_customer_reason string Reason of the incident that prompted the client to cancel the ride.
This is reserved for future use. The only accepted value as per version 2 of the API is an empty string. This field should be used by search engines when setting the status of the ride to incident_customer.
incident_taxi_reason string Reason of the incident that prompted the taxi to cancel the ride.
This field should be used by operators when setting the status of the ride to incident_taxi.
The possible reasons are: no_show (when the client cannot be found), address (when the address cannot be found), traffic (when a traffic jam prevents the taxi to arrive at the location in a reasonable time) and breakdown (in case of a mechanical problem on the vehicle preventing the taxi to continue operating). This information will be visible too the search engine querying the hail.
rating_ride integer
(from 1 to 5)
Rating of the ride by the client.
This field should be used by search engines during or after the ride to let customers rate the ride between 1 and 5 stars. A ride can be rated multiple times, but only the latest rating will be considered.
rating_ride_reason string Explanation of the rating of the ride by the client.
This field should be used by search engines during or after the ride to let the client explain low ratings of the ride. It is recommended to ask customers for their rating_ride_reason when their rating_ride is 3 stars or less. This information will not be individually transmitted to the taxi driver.
The possible values are ko (the taxi never showed and/or the ride did not happen), payment (credit card refused, etc), courtesy (general attitude problems, loud radio, etc), route (subpar itinerary, etc) and cleanliness (dirty car, cigarette smell, etc).
reporting_customer boolean Reporting of a problem encountered with a customer by a driver.
This field should be used by operators during or after the ride to let the taxi driver inform the search engine that a problem happened with the client. In that case, the hail should be update with a reporting_customer set to True and a reporting_customer_reason should be provided.
reporting_customer_reason string Explanation of the problem encountered with a customer by a driver.
This field should be used by operators during or after the ride to let taxi drivers explain the type of problem they encountered with a client. It is only required if reporting_customer is set to True.
The possible values are ko (the client was nowhere to be seen and/or the ride did not happen), payment (unpaid ride, bargaining, etc), courtesy (general attitude problems, etc), route (non existing destination address, etc) and cleanliness (dirty luggages, cigarette, etc).

Hail status

This section describes the different values a hail status can take.
Value Description Interaction
emitted The initial status of hail when created by a search engine This is the status that should be used in the payload of the POST request on the /hails/ API when a search engine creates a new hail.
received The hail is received from the search engine by the TXP The TXP changes the status to received after having sent back the complete hail (with the newly grenerated id) to the search engine and before forwarding the hail to the operator.
sent_to_operator The hail has been sent from the TXP to the operator The TXP changes the status to sent_to_operator after forwarding the hail to the operator endpoint.
received_by_operator The operator has acknowladged receiving the hail from the TXP The TXP changes the status to received_by_operator after receiving a HTTP 200 response from the operator endpoint.
received_by_taxi The hail has been received by the taxi The operator should set the status of the hail to received_by_taxi by doing a PUT request on the /hails/{hail_id} API when the hail has been presented to the taxi driver.
accepted_by_taxi The hail has been accepted by the taxi driver The operator should set the status of the hail to accepted_by_taxi by doing a PUT request on the /hails/{hail_id} API when the hail has been accepted by the taxi driver.
declined_by_taxi The hail has been declined by the taxi driver The operator should set the status of the hail to declined_by_taxi by doing a PUT request on the /hails/{hail_id} API when the hail has been rejected by the taxi driver.
timeout_taxi The taxi driver did not accept nor reject the hail after 30s The TXP changes the status to timeout_taxi automatically after 30s have passed since the status was set to received_by_taxi.
accepted_by_customer The hail has been confirmed by the client The search engine should set the status of the hail to accepted_by_customer by doing a PUT request on the /hails/{hail_id} API when the hail has been confirmed by the client.
Warning: this confirmation can only happen after the status has been set to accepted_by_taxi by the operator.
declined_by_customer The hail has been canceled by the client The search engine should set the status of the hail to declined_by_customer by doing a PUT request on the /hails/{hail_id} API when the hail has been canceled by the client.
Warning: this cancellation can happen at any moment (including before the taxi driver accepts the hail).
timeout_customer The client did not confirm nor cancel the hail after 20s The TXP changes the status to timeout_customer automatically after 20s have passed since the status was set to accepted_by_taxi.
incident_customer An event of force majeure prevents the client to wait for the taxi The search engine should set the status of the hail to incident_customer by doing a PUT request on the /hails/ API when the client cancels the hail after having reconfirmed it.
incident_taxi An event of force majeure prevents the taxi to serve the client The operator should set the status of the hail to incident_taxi by doing a PUT request on the /hails/ API when the taxi cancels the hail after having accepted it.
failure A technical problem happened. The TXP changes the status to failure when:
  • the operator endpoint is unreachable
  • or when receiving a HTTP 4xx or 5xx response from the operator endpoint
  • or if the operator endpoint does not return a hail JSON object containing a valid taxi_phone_number.
  • or if the operator does not set the status of the hail to received_by_taxi in the 10s after the status has been set to received_by_operator