Search Engines

There are two main interactions between Taxis Search Engines and the Taxi Exchange Point (TXP): looking for taxis around a client, and hailing a taxi for a client.
Warning: in accordance with the Terms of Service, you are allowed to look for a taxi or hail one only within the context of a real-time interactive demand of a real customer: automation, replay and any other form of mass data gathering is expressly forbidden.

Looking for taxis around a client

In order to obtain the list of all taxis available around a client, your application does an HTTPS GET request on the taxis API.
That API sends back all the available taxis around the {lon,lat} location of the client with all their characteristics. Only the taxis that are available and can be hailed by the client are returned (the list is already filtered according to the French taxis regulation).

Favorite operator

The optional favorite_operator parameter allows to specify a prefered operator. It is useful for taxis geolocated by several operators at the same time (which is expressly allowed by the French law). In that case, it is the description of the taxi and the location recently updated by that favorite_operator that will be returned. If no recent position has been updated by the favorite_operator, or if no favorite_operator is specified in the request, the description of the taxi and location returned are those of the operator who updated the position of the taxi most recently.

Hailing a taxi

Once you have received the list of all taxis available around a client, you can hail one of those taxis. That Hail is created by doing a HTTPS POST request to the hails API. The JSON object hail to be created has to be in the data section of the request. The initial status of the Hail should be set to emitted.
In case of success, the response contains the newly created JSON object hail including its newly created id which will then be used to query and update the status of the hail.

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 API.
The identifier of the hail is the id that was returned in the response of the POST request used to create the hail (see Hailing a taxi).
The list of all possible statuses is available in the Reference Documentation.

Updating a Hail

In order to finalise the transaction, the client has to reconfirm the hail after it is acknowledged by the taxi. It is done through a call of the HTTPS PUT request to the hails API.
The status of the hail has to be accepted_by_taxi before the client is asked to reconfirm. If you don't send a PUT request with either the accepted_by_customer or the declined_by_customer status in the next 30 seconds, the hail will automatically be updated to timeout_customer and the whole transaction be considered cancelled. You do have to check when you do a PUT with the status accepted_by_customer that the status in the response is indeed accepted_by_customer (you reconfirmed and the taxi is arriving) and not timeout_customer (your reconfirmation arrived too late, the whole transaction had to be canceled).