Taxi cars dispatcher

Intro

This tutorial shows you how to create a web application for a taxi company using version 6 of the TomTom Maps SDK for Web.

It's not easy to identify which taxi can get the fastest to the customer by just looking at the map. Using the Calculate Route service you can obtain the travel time of each individual taxi to a particular point, in this case, a passenger. In this application you will use this service so that the dispatcher will pick the taxi that reaches the customer the fastest way.

In this tutorial you will create a map with markers pointing at taxis and passenger's locations. The application calculates each route and chooses the fastest one.

Prerequisites:

To start using the TomTom Maps SDK for Web, you need an API Key. If you don't have it, please visit a How to get a TomTom API key site and create one.

Map initialization

To display a TomTom map use the following code. You can just copy and paste it to your favorite code editor.

1<!DOCTYPE html>
2<html>
<head>
  <title>Taxi cars dispatcher</title>
  <meta charset="UTF-8" />
  <!-- Replace version in the URL with desired library version -->
  <link
    rel="stylesheet"
    type="text/css"
    href="https://api.tomtom.com/maps-sdk-for-web/cdn/6.x/<version>/maps/maps.css"
  />
  <script src="https://api.tomtom.com/maps-sdk-for-web/cdn/6.x/<version>/maps/maps-web.min.js"></script>
  <script src="https://api.tomtom.com/maps-sdk-for-web/cdn/6.x/<version>/services/services-web.min.js"></script>
  <style>
    body {
      margin: 0
    }
    #map {
      height: 100vh;
      width: 100vw;
    }
  </style>
</head>
24
<body>
  <div id="map"></div>
  <script>
    const apiKey = "<your-api-key>"
    const map = tt.map({
      key: apiKey,
      container: "map",
      center: [4.876935, 52.360306],
      zoom: 13,
    })
  </script>
</body>
37</html>

Note that the container parameter of tt.map constructor requires the same value as the id of a HTML <div> element where the map will be embedded. Replace <your-api-key> placeholder with your API Key.

You can find the custom markers used for this tutorial on GitHub.

Passenger

Add a passenger marker to the map.

To add the passenger marker into the map:

First: You need to add variables to the JavaScript section: passengerInitCoordinates , passengerMarker, and a createPassengerMarker(markerCoordinates, popup) function.
Second: The passengerInitCoordinates variable needs to be declared before the map initialization.

1const passengerInitCoordinates = [4.876935, 52.360306]
2let passengerMarker
3
4function createPassengerMarker(markerCoordinates, popup) {
5  const passengerMarkerElement = document.createElement("div")
6  passengerMarkerElement.innerHTML =
7    "<img src='img/man-waving-arm_32.png' style='width: 30px; height: 30px';>"
8  return new tt.Marker({ element: passengerMarkerElement })
9    .setLngLat(markerCoordinates)
10    .setPopup(popup)
11    .addTo(map)
12}

To center the map on the passenger, replace the map definition like the one in the following example:

1const map = tt.map({
2  key: apiKey,
3  container: "map",
4  center: passengerInitCoordinates,
5  zoom: 13,
6})

Ensure that the placeholder has been replaced by your API Key.

The following code puts the passenger marker on the map and opens a popup.

1passengerMarker = createPassengerMarker(
2  passengerInitCoordinates,
3  new tt.Popup({ offset: 35 }).setHTML(
4    "Click anywhere on the map to change passenger location."
5  )
6)
7
8passengerMarker.togglePopup()

Change the passenger marker position.

Now you can add a feature that allows users to click on the map to move a passenger. To do so, add an event listener on map click.

In the handler function, call the reverseGeocode method with a position parameter from the event’s property geoResponse.
In the then method define a callback that executes a drawPassengerMarkerOnMap function.

Add a conditional statement in the drawPassengerMarkerOnMap function: if the Reverse Geocoding Response contains an address, then a marker with the previous position is removed and a new one is created at the indicated location.

1function drawPassengerMarkerOnMap(geoResponse) {
if (
  geoResponse &&
  geoResponse.addresses &&
  geoResponse.addresses[0].address.freeformAddress
) {
  passengerMarker.remove()
  passengerMarker = createPassengerMarker(
    geoResponse.addresses[0].position,
    new tt.Popup({ offset: 35 }).setHTML(
      geoResponse.addresses[0].address.freeformAddress
    )
  )
  passengerMarker.togglePopup()
}
16}

Now you can add an event that draws the passenger marker each time you click on the map area.

1map.on("click", function (event) {
const position = event.lngLat
tt.services
  .reverseGeocode({
    key: apiKey,
    position: position,
  })
  .then(function (results) {
    drawPassengerMarkerOnMap(results)
  })
11})

Taxi cabs

Add the taxi markers definition, where the coordinates for taxi cabs are fixed for simplicity.

1let taxiConfig
2function setDefaultTaxiConfig() {
taxiConfig = [
  createTaxi("CAR #1", "#006967", [4.902642, 52.373627], "img/cab1.png"),
  createTaxi("CAR #2", "#EC619F", [4.927198, 52.365927], "img/cab2.png"),
  createTaxi("CAR #3", "#002C5E", [4.893488, 52.347878], "img/cab3.png"),
  createTaxi("CAR #4", "#F9B023", [4.858433, 52.349447], "img/cab4.png"),
]
9}
10
11function createTaxi(
name,
color,
coordinates,
iconFilePath,
iconWidth = 55,
iconHeight = 55
18) {
return {
  name: name,
  color: color,
  icon:
    "<img src=" +
    iconFilePath +
    " style='width: " +
    iconWidth +
    "px; height: " +
    iconHeight +
    "px;'>",
  coordinates: coordinates,
}
32}

Add the taxi cabs into the map and an initialization of the setDefaultTaxiConfig function.

1setDefaultTaxiConfig()
2
3taxiConfig.forEach(function (taxi) {
4  const carMarkerElement = document.createElement("div")
5  carMarkerElement.innerHTML = taxi.icon
6  new tt.Marker({ element: carMarkerElement, offset: [0, 27] })
7    .setLngLat(taxi.coordinates)
8    .addTo(map)
9})

Submit button

To add the Submit button, the map <div> tag needs to be updated with the following code:

1<div id="map"></div>
2<div id="labels-container">
3  <label>Find the taxi that will arrive fastest</label>
4  <div id="route-labels"></div>
5  <input type="button" id="submit-button" value="Submit" />
6</div>

To see the button on the map, you need to add CSS styles.

1#submit-button {
2  background: #df1b12;
3  padding: 10px;
4  margin-top: 10px;
5  width: 100%;
6  color: white;
7  font-weight: bold;
8  transition: background-color 0.15s ease-in-out;
9  text-transform: uppercase;
10  border: none;
11  outline: none;
12}
13
14#submit-button:hover {
15  cursor: pointer;
16  background: #b1110e;
17}
18
19#labels-container {
20  font-family: "Helvetica Neue", Arial, Helvetica, sans-serif;
21  position: fixed;
22  top: 10px;
23  right: 10px;
24  width: 400px;
25  padding: 10px;
26  margin: 10px;
27  background-color: white;
28  box-shadow: rgba(0, 0, 0, 0.45) 2px 2px 2px 0px;
29}
30
31#labels-container label {
32  line-height: 2;
33  font-size: 1.2em;
34  font-weight: bold;
35}
36
37#labels-container #route-labels div {
38  border-left: 6px solid;
39  padding-left: 5px;
40  margin-top: 3px;
41}
42
43#route-labels div:hover {
44  cursor: pointer;
45  box-shadow: 0px 2px #888888;
46}

Clear routes

To clear routes we need to first declare a variable.

let routes = []

The clear function:

Removes routes from the map.
Clears the routes array.
Calls setDefaultTaxiConfig.

1function clear() {
routes.forEach(function (child) {
  map.removeLayer(child[0])
  map.removeLayer(child[1])
  map.removeSource(child[0])
  map.removeSource(child[1])
})
routes = []
setDefaultTaxiConfig()
passengerMarker.togglePopup()
11}

Next, the clear function can be embedded into submitButtonHandler.

1function submitButtonHandler() {
2  clear()
3}

Don’t forget to assign the submitButtonHandler listener to the button in the HTML document.

1document
2  .getElementById("submit-button")
3  .addEventListener("click", submitButtonHandler)

Now you can go to the next chapter where the clear function can be used.

Draw routes

The variables: routeWeight and routeBackgroundWeight need to be initialized as in the following example.

const routeWeight = 9
const routeBackgroundWeight = 12

For convenience, let's also create a taxiPassengerBatchCoordinates array and a updateTaxiBatchLocations(passengerCoordinates) function which will be helpful with preparing data for a Batch Routing call later.

1let taxiPassengerBatchCoordinates = []
2
3function updateTaxiBatchLocations(passengerCoordinates) {
4  taxiPassengerBatchCoordinates = []
5  taxiConfig.forEach((taxi) => {
6    taxiPassengerBatchCoordinates.push(
7      taxi.coordinates + ":" + passengerCoordinates
8    )
9  })
10}

Call the updateTaxiBatchLocations(passengerCoordinates) function right after the setDefaultTaxiConfig();.

setDefaultTaxiConfig()
updateTaxiBatchLocations(passengerInitCoordinates)

The drawAllRoutes function uses the calculateRoute method to get JSON objects with that route’s geometry coordinates for each four taxi locations inside the taxiPassengerBatchCoordinates array and a current passenger location.

The JSON is used to create GeoJSON route layers by calling a buildStyle function.
Created layers are then added to the map.

1let bestRouteIndex
2
3function drawAllRoutes() {
tt.services
  .calculateRoute({
    batchMode: "sync",
    key: apiKey,
    batchItems: [
      { locations: taxiPassengerBatchCoordinates[0] },
      { locations: taxiPassengerBatchCoordinates[1] },
      { locations: taxiPassengerBatchCoordinates[2] },
      { locations: taxiPassengerBatchCoordinates[3] },
    ],
  })
  .then(function (results) {
    results.batchItems.forEach(function (singleRoute, index) {
      const routeGeoJson = singleRoute.toGeoJson()
      const route = []
      const route_background_layer_id = "route_background_" + index
      const route_layer_id = "route_" + index
21
      map
        .addLayer(
          buildStyle(
            route_background_layer_id,
            routeGeoJson,
            "black",
            routeBackgroundWeight
          )
        )
        .addLayer(
          buildStyle(
            route_layer_id,
            routeGeoJson,
            taxiConfig[index].color,
            routeWeight
          )
        )
39
      route[0] = route_background_layer_id
      route[1] = route_layer_id
      routes[index] = route
43
      if (index === bestRouteIndex) {
        const bounds = new tt.LngLatBounds()
        routeGeoJson.features[0].geometry.coordinates.forEach(function (
          point
        ) {
          bounds.extend(tt.LngLat.convert(point))
        })
        map.fitBounds(bounds, { padding: 150 })
      }
53
      map.on("mouseenter", route_layer_id, function () {
        map.moveLayer(route_background_layer_id)
        map.moveLayer(route_layer_id)
      })
58
      map.on("mouseleave", route_layer_id, function () {
        bringBestRouteToFront()
      })
    })
    bringBestRouteToFront()
  })
65}
66
67function bringBestRouteToFront() {
map.moveLayer(routes[bestRouteIndex][0])
map.moveLayer(routes[bestRouteIndex][1])
70}
71
72function buildStyle(id, data, color, width) {
return {
  id: id,
  type: "line",
  source: {
    type: "geojson",
    data: data,
  },
  paint: {
    "line-color": color,
    "line-width": width,
  },
  layout: {
    "line-cap": "round",
    "line-join": "round",
  },
}
89}

The route layer is drawn twice to create an outline:

route[0] (route_background_layer_id) in black, with a thick stroke.
route[1] (route_layer_id) using the color from config and a normal stroke.

Add a processMatrixResponse function. It extracts 3 elements from each Response and uses them to populate 3 separate arrays:

travel times
route lengths
traffic delays

1function processMatrixResponse(result) {
const travelTimeInSecondsArray = []
const lengthInMetersArray = []
const trafficDelayInSecondsArray = []
result.matrix.forEach(function (child) {
  travelTimeInSecondsArray.push(
    child[0].response.routeSummary.travelTimeInSeconds
  )
  lengthInMetersArray.push(child[0].response.routeSummary.lengthInMeters)
  trafficDelayInSecondsArray.push(
    child[0].response.routeSummary.trafficDelayInSeconds
  )
})
drawAllRoutes()
15}

Next, add the functions: convertToPoint, buildDestinationsParameter, and buildOriginsParameter.

1function convertToPoint(lat, long) {
2  return {
3    point: {
4      latitude: lat,
5      longitude: long,
6    },
7  }
8}
9
10function buildOriginsParameter() {
11  const origins = []
12  taxiConfig.forEach(function (taxi) {
13    origins.push(convertToPoint(taxi.coordinates[1], taxi.coordinates[0]))
14  })
15  return origins
16}
17
18function buildDestinationsParameter() {
19  return [
20    convertToPoint(
21      passengerMarker.getLngLat().lat,
22      passengerMarker.getLngLat().lng
23    ),
24  ]
25}

The callMatrix function uses a matrixRouting method to create a Request for the Matrix Routing API.

The go method then calls the API asynchronously, to allow for service processing time.
Use the then function to define a callback that processes the Response, including travelTime in seconds and distance in meters.

To deal with the volume of route plans that may be required, this implementation uses the Routing API.

In a simple implementation with one passenger and four taxis, the service would calculate a small matrix of 4 x 1 routes.
But in a real life application, there may be many passengers requesting a taxi at the same time and many available taxis.
A scenario with 3 passengers and 20 taxis creates a matrix of 20 x 3 = 60 routes.

For more information on the API, see Matrix Routing.

1function callMatrix() {
const origins = buildOriginsParameter()
const destinations = buildDestinationsParameter()
tt.services
  .matrixRouting({
    key: apiKey,
    origins: origins,
    destinations: destinations,
    traffic: true,
  })
  .then(processMatrixResponse)
12}

Finally, you can add the callMatrix function call and update submitButtonHandler.

1function submitButtonHandler() {
2  clear()
3  callMatrix()
4}

And the winner is …

Create a modal to inform the user which route is the fastest one.

The modal appears when all calculations are done.
Put a <div> with a modal id in the <body> tag, following the map <div> tag.

1<div id="modal">
2  <div id="modal-content"></div>
3</div>

Add the CSS for the modal to your style section:

1#modal {
display: none;
position: fixed;
z-index: 1100;
left: 0;
top: 0;
width: 100%;
height: 100%;
overflow: auto;
background-color: rgba(0, 0, 0, 0.5);
11}
12
13#modal-content {
background-color: lightgray;
color: #555;
font-family: "Helvetica Neue", Arial, Helvetica, sans-serif;
font-weight: bold;
text-align: center;
margin: 15% auto;
padding: 20px;
border: 1px solid #888;
width: 20%;
23}

Next, add the necessary variables.

1const modal = document.getElementById("modal")
2const modalContent = document.getElementById("modal-content")
3const fastestRouteColor = "#65A7A9"

To display and remove the modal from the screen, add the following code:

1modal.addEventListener("click", function () {
2  modal.style.display = "none"
3})
4
5function displayModal() {
6  modalContent.innerText = "Dispatch car number " + String(bestRouteIndex + 1)
7  modal.style.display = "block"
8}

The user can click anywhere to hide the modal.

Now is a time to choose the winner in a modifyFastestRouteColor function.

If it is the fastest route, it is displayed above all other routes.
The function copies the array travelTimeInSecondsArray to a new sortedTab array and sorts it.

Because the default comparison function is alphabetic (meaning that '11' is less than '2'), the function uses a custom comparison function.

The following one takes two values (such as 7 and 9) and subtracts one from the other.
If the result is negative (-2), the function sorts 7 as lower than 9.

1function modifyFastestRouteColor(travelTimeInSecondsArray) {
const sortedTab = travelTimeInSecondsArray.slice()
sortedTab.sort(function (a, b) {
  return a - b
})
bestRouteIndex = travelTimeInSecondsArray.indexOf(sortedTab[0])
taxiConfig[bestRouteIndex].color = fastestRouteColor
8}

What's left is updating the processMatrixResponse, as shown in the following code:

1function processMatrixResponse(result) {
const travelTimeInSecondsArray = []
const lengthInMetersArray = []
const trafficDelayInSecondsArray = []
result.matrix.forEach(function (child) {
  travelTimeInSecondsArray.push(
    child[0].response.routeSummary.travelTimeInSeconds
  )
  lengthInMetersArray.push(child[0].response.routeSummary.lengthInMeters)
  trafficDelayInSecondsArray.push(
    child[0].response.routeSummary.trafficDelayInSeconds
  )
})
modifyFastestRouteColor(travelTimeInSecondsArray)
drawAllRoutes()
displayModal()
17}

Summary

This tutorial has demonstrated:

How to do a Matrix Routing API query.
How to draw a route on the map.
How to work with a route by setting event listeners , setting a style , and bringing the route to the front or back.

All the source code of that application can be found on GitHub.