メインコンテンツまでスキップ

Get started with the Map Matching API

追加の開発者リソース
前提条件
Familiarity with front-end development concepts.

Most turn-by-turn apps assume that users want to take the most efficient route to their destination. But sometimes, users care more about being able to choose a fun or scenic route than they do about getting to their destination quickly. For example: Your user is visiting San Francisco. They visited the Maritime Museum, and now it’s time to get a slice of pizza in North Beach. On the way, they want to drive down Lombard Street, a stretch of road with eight tight hairpin turns that’s popularly known as the “crookedest street in the world”.

Taking Lombard Street isn't the fastest way to get to the user’s destination, but it does offer more photo opportunities than any other route! In most turn-by-turn apps, it’s difficult to pull up a route that includes this stretch of Lombard Street because it’s not the most efficient route. This means a user would be routed elsewhere, regardless of their wish to drive down Lombard Street. But the Mapbox Map Matching API makes it possible to plot custom routes, which opens up different routing possibilities.

In this tutorial, you will create a web application that allows your users to create their own travel routes, regardless of whether those routes are the most efficient routes or not. The app's users will draw their own route on the map using draw tools from the Mapbox GL Draw plugin, then the app will pass the drawn coordinates to the Map Matching API and generate turn-by-turn directions for the new driving route.

The Map Matching API vs. the Directions API

The Mapbox Map Matching API has a lot of similarities to the Directions API. The Map Matching API can be used to generate routes, route durations, and turn-by-turn directions, as the Directions API can. But the Directions API will specifically always generate an optimal route, while the Map Matching API will generate a route on the OpenStreetMap road network that most closely follows the coordinates provided in the request.

Getting started​

To complete this tutorial, you will need:

  • A Mapbox access token. Your Mapbox access tokens are on your Account page.
  • Mapbox GL JS. Mapbox GL JS is a JavaScript API for building web maps.
  • Mapbox GL Draw plugin. The Mapbox GL Draw plugin adds support for drawing and editing features on maps created with Mapbox GL JS.
  • Mapbox Map Matching API. The Map Matching API snaps coordinates onto the OpenStreetMap road network, and can return turn-by-turn directions for the routes it produces.
  • A text editor. Use the text editor of your choice for writing HTML, CSS, and JavaScript.

Create a map​

To start the app, you will create a map using Mapbox GL JS.

Open your text editor and create a new file named index.html. Set up this new HTML file by pasting the following code into your text editor. This code creates the structure of the page. This code also imports Mapbox GL JS in the <head> of the page. The Mapbox GL JS JavaScript and CSS files allow you to use Mapbox GL JS functionality and style.

There is a <div> element with the ID map in the <body> of the page. This <div> is the container in which the map will be displayed on the page.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Get started with the Map Matching API</title>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    {/* Import Mapbox GL JS */}
    <script src="https://api.tiles.mapbox.com/mapbox-gl-js/v3.3.0/mapbox-gl.js"></script>
    <link
      href="https://api.tiles.mapbox.com/mapbox-gl-js/v3.3.0/mapbox-gl.css"
      rel="stylesheet"
    />
    <style>
      body {
        margin: 0;
        padding: 0;
      }

      #map {
        position: absolute;
        top: 0;
        bottom: 0;
        width: 100%;
      }
    </style>
  </head>

  <body>
    {/* Create a container for the map */}
    <div id="map"></div>

    <script>
      // Add your Mapbox access token
      mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN ';
      const map = new mapboxgl.Map({
        container: 'map', // Specify the container ID
        style:
          'mapbox://styles/mapbox/streets-v12', // Specify which map style to use
        center: [-122.42136449, 37.80176523], // Specify the starting position
        zoom: 14.5 // Specify the starting zoom
      });
    </script>
  </body>
</html>

This Mapbox GL JS code sets a style for the map, gives it coordinates on which to center, and sets a zoom level.

Save your changes. Open the HTML file in your browser to see the rendered map, which is centered on the city of San Francisco.

Add the Draw tools​

Options for passing coordinates to the Map Matching API

In this app created in this tutorial, the coordinates that the Map Matching API uses to generate a route are created by the user adding points directly to the map with the Mapbox GL Draw tools. Often, though, you would instead want to add the points used by the Map Matching API programmatically. For example, the Map Matching API could access a data set that contains landmark coordinates to create scenic routes, or a data set with the locations of known parking garages near the end of a route.

The Mapbox GL Draw plugin adds support for drawing features on maps created with Mapbox GL JS. In this step, you will add the Mapbox GL Draw line_tool and trash tools to your app, which will allow your users to draw lines and delete them. To add the draw tools, first add the links to the Mapbox GL Draw plugin's JavaScript and CSS to the head of the HTML file:

<script src="https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-draw/v1.0.9/mapbox-gl-draw.js"></script>
<link
  rel="stylesheet"
  href="https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-draw/v1.0.9/mapbox-gl-draw.css"
  type="text/css"
/>

Once these links have been added, you will be able to use the Draw plugin in your app. When you add the Draw plugin, you can also specify the style of the line that gets drawn on the map when a user uses the draw tool. Add the following code above the closing </script> tag in your HTML file.

const draw = new MapboxDraw({
  // Instead of showing all the draw tools, show only the line string and delete tools.
  displayControlsDefault: false,
  controls: {
    line_string: true,
    trash: true
  },
  // Set the draw mode to draw LineStrings by default.
  defaultMode: 'draw_line_string',
  styles: [
    // Set the line style for the user-input coordinates.
    {
      id: 'gl-draw-line',
      type: 'line',
      filter: ['all', ['==', '$type', 'LineString'], ['!=', 'mode', 'static']],
      layout: {
        'line-cap': 'round',
        'line-join': 'round'
      },
      paint: {
        'line-color': '#438EE4',
        'line-dasharray': [0.2, 2],
        'line-width': 4,
        'line-opacity': 0.7
      }
    },
    // Style the vertex point halos.
    {
      id: 'gl-draw-polygon-and-line-vertex-halo-active',
      type: 'circle',
      filter: [
        'all',
        ['==', 'meta', 'vertex'],
        ['==', '$type', 'Point'],
        ['!=', 'mode', 'static']
      ],
      paint: {
        'circle-radius': 12,
        'circle-color': '#FFF'
      }
    },
    // Style the vertex points.
    {
      id: 'gl-draw-polygon-and-line-vertex-active',
      type: 'circle',
      filter: [
        'all',
        ['==', 'meta', 'vertex'],
        ['==', '$type', 'Point'],
        ['!=', 'mode', 'static']
      ],
      paint: {
        'circle-radius': 8,
        'circle-color': '#438EE4'
      }
    }
  ]
});

// Add the draw tool to the map.
map.addControl(draw);

Save your file, then refresh the page in your browser. You will see icons for the specified Draw plugin controls, line_tool and delete, on the upper right side of the page. Click the line_tool icon. On the map, click once to start the line, then click one or more times to draw a path. When you're done drawing, click again on the last point to finish the path. The map will display a blue dashed line that follows the path you drew. For more information on how to style lines using this plugin, read the Styling Draw section of the Mapbox GL Draw documentation.

In a few steps, you will link the code you wrote in this step with a function that takes this drawn path and gathers the coordinates to use in the Map Matching API call.

Add the sidebar​

Next, add a sidebar to the web app that will display instructions for users on how to use the app. This sidebar will also serve as a place to display turn-by-turn directions, which you will set up in a later step.

In the <body> of your HTML, add a new <div>. This <div> will hold the app's instructions and, later, the directions.

<div class="info-box">
  <p>
    Draw your route using the draw tools on the right. To get the most accurate
    route match, draw points at regular intervals.
  </p>
  <div id="directions"></div>
</div>

To style the new <div>, add the following CSS to the <style> section of your HTML:

.info-box {
  position: absolute;
  margin: 20px;
  width: 25%;
  top: 0;
  bottom: 20px;
  padding: 20px;
  background-color: #fff;
  overflow-y: scroll;
}

Save your work and refresh the page. The new information box will display on the left side of the page.

Add the Map Matching API​

A Map Matching API requires two parameters: the profile the query should use, and the coordinates that need to be matched to the OpenStreetMap road and path network. The profile can be either walking, cycling, driving, or driving-traffic. The coordinates are a semicolon-separated list of {longitude},{latitude} coordinate pairs to visit in order, of which there can be anywhere between two and 100.

https://api.mapbox.com/matching/v5/mapbox/{profile}/{coordinates}.json?access_token=YOUR_MAPBOX_ACCESS_TOKEN

The Map Matching API also accepts several optional parameters that can be used to customize the query. For this app, you will be using two optional parameters:

  • radiuses: A semicolon-separated list that indicates the maximum distance a coordinate can be moved to snap to the road network in meters. Adding a radius tells the Map Matching API how precisely it must match the input coordinates, which may not always represent a location on the OpenStreetMap road network. The number of radiuses must be the same as the number of coordinates in the request.
  • steps: Set to true to return step-by-step instructions.

To learn more about the Map Matching API and its other optional parameters, explore the Map Matching API documentation.

This example query uses the driving profile, has two coordinate pairs and two radiuses, and has the steps parameter set to true:

https://api.mapbox.com/matching/v5/mapbox/driving/-117.17282,32.71204;-117.17288,32.71225?steps=true&radiuses=25;25&access_token=YOUR_MAPBOX_ACCESS_TOKEN

A Map Matching API request that includes the radiuses and steps parameters returns a response that contains matchings, an array of match objects. A match object contains route leg objects, which give detailed information about each leg of the route, including the turn-by-turn directions. You will use the information returned by the Map Matching API to do two things: draw the matched route to the map, and return turn-by-turn directions.

To integrate the Map Matching API into your app, you will write two new functions, updateRoute and getMatch. updateRoute will take the coordinates from the user-generated line and format them so that they can be used in a Map Matching query. getMatch will construct the query string and will use fetch to make the Map Matching API call. Used together, these two functions will make an API call using the coordinates drawn on the screen and will return the data necessary to complete the rest of the app. Add the following code to your JavaScript, before the closing </script> tag:

// Use the coordinates you drew to make the Map Matching API request
function updateRoute() {
  // Set the profile
  const profile = 'driving';
  // Get the coordinates that were drawn on the map
  const data = draw.getAll();
  const lastFeature = data.features.length - 1;
  const coords = data.features[lastFeature].geometry.coordinates;
  // Format the coordinates
  const newCoords = coords.join(';');
  // Set the radius for each coordinate pair to 25 meters
  const radius = coords.map(() => 25);
  getMatch(newCoords, radius, profile);
}

// Make a Map Matching request
async function getMatch(coordinates, radius, profile) {
  // Separate the radiuses with semicolons
  const radiuses = radius.join(';');
  // Create the query
  const query = await fetch(
    `https://api.mapbox.com/matching/v5/mapbox/${profile}/${coordinates}?geometries=geojson&radiuses=${radiuses}&steps=true&access_token=${mapboxgl.accessToken}`,
    { method: 'GET' }
  );
  const response = await query.json();
  // Handle errors
  if (response.code !== 'Ok') {
    alert(
      `${response.code} - ${response.message}.\n\nFor more information: https://docs.mapbox.com/api/navigation/map-matching/#map-matching-api-errors`
    );
    return;
  }
  // Get the coordinates from the response
  const coords = response.matchings[0].geometry;
  console.log(coords);
  // Code from the next step will go here
}

By calling the getMatch function in updateRoute, you can access the user-drawn coordinates and use them as the coordinates in the Map Matching API call. In the next step you will add a new drawn line to show the matched route, but for now you can view the coordinate results using console.log().

To call getMatch when your user draws or updates a line on the map, add the following lines before the closing </script> tag:

map.on('draw.create', updateRoute);
map.on('draw.update', updateRoute);

Save your work, then refresh your browser page and open the browser's developer tools. When you draw a route on the map, your app will print the coordinate data returned by the Map Matching API to the JavaScript console.

Draw the Map Matching route​

Next, you will create an addRoute function that takes the coordinates returned by the Map Matching API and adds them on the map as a new layer. Paste the following code into your JavaScript, above the final </script> tag:

// Draw the Map Matching route as a new layer on the map
function addRoute(coords) {
  // If a route is already loaded, remove it
  if (map.getSource('route')) {
    map.removeLayer('route');
    map.removeSource('route');
  } else {
    // Add a new layer to the map
    map.addLayer({
      id: 'route',
      type: 'line',
      source: {
        type: 'geojson',
        data: {
          type: 'Feature',
          properties: {},
          geometry: coords
        }
      },
      layout: {
        'line-join': 'round',
        'line-cap': 'round'
      },
      paint: {
        'line-color': '#03AA46',
        'line-width': 8,
        'line-opacity': 0.8
      }
    });
  }
}

Call addRoute within your getRoute function so that it can access the coordinates returned by the Map Matching API. getRoute will now look like this:

// Make a Map Matching request
async function getMatch(coordinates, radius, profile) {
  // Separate the radiuses with semicolons
  const radiuses = radius.join(';');
  // Create the query
  const query = await fetch(
    `https://api.mapbox.com/matching/v5/mapbox/${profile}/${coordinates}?geometries=geojson&radiuses=${radiuses}&steps=true&access_token=${mapboxgl.accessToken}`,
    { method: 'GET' }
  );
  const response = await query.json();
  // Handle errors
  if (response.code !== 'Ok') {
    alert(
      `${response.code} - ${response.message}.\n\nFor more information: https://docs.mapbox.com/api/navigation/map-matching/#map-matching-api-errors`
    );
    return;
  }
  // Get the coordinates from the response
  const coords = response.matchings[0].geometry;
  // Draw the route on the map
  addRoute(coords);
}

Save your changes and refresh the browser page. Now when you use the line_draw tool to trace a route, the route generated by the Map Matching API also shows on the map. As you can see, the line drawn by the user won't always match up directly with the route generated by the Map Matching API. This is because the Map Matching API takes the input coordinates, which may not be located directly on the road network, and snaps them to the nearest road within the 25 meter radius that you specified in the radiuses parameter.

Display the turn-by-turn directions​

Now it's time to add the turn-by-turn instructions from the Map Matching API to the sidebar! Doing so requires writing a new function, getInstructions, that will allow you to dig down into the Map Matching API response object to get the information you need: the total time that the route will take, and the maneuver instructions for each step of the route. (Read more about what gets returned in the Map Matching API's route step object in the Map Matching API documentation.) Add the following code to the JavaScript, below the getMatch method:

function getInstructions(data) {
  // Target the sidebar to add the instructions
  const directions = document.getElementById('directions');
  let tripDirections = '';
  // Output the instructions for each step of each leg in the response object
  for (const leg of data.legs) {
    const steps = leg.steps;
    for (const step of steps) {
      tripDirections += `<li>${step.maneuver.instruction}</li>`;
    }
  }
  directions.innerHTML = `<p><strong>Trip duration: ${Math.floor(
    data.duration / 60
  )} min.</strong></p><ol>${tripDirections}</ol>`;
}

Next, call getInstructions within your getRoute function so that it can access the data returned by the Map Matching API. getRoute will now look like this:

// Make a Map Matching request
async function getMatch(coordinates, radius, profile) {
  // Separate the radiuses with semicolons
  const radiuses = radius.join(';');
  // Create the query
  const query = await fetch(
    `https://api.mapbox.com/matching/v5/mapbox/${profile}/${coordinates}?geometries=geojson&radiuses=${radiuses}&steps=true&access_token=${mapboxgl.accessToken}`,
    { method: 'GET' }
  );
  const response = await query.json();
  // Handle errors
  if (response.code !== 'Ok') {
    alert(
      `${response.code} - ${response.message}.\n\nFor more information: https://docs.mapbox.com/api/navigation/map-matching/#map-matching-api-errors`
    );
    return;
  }
  const coords = response.matchings[0].geometry;
  // Draw the route on the map
  addRoute(coords);
  getInstructions(response.matchings[0]);
}

Save your changes and refresh your browser page. Now when you draw a route on the map, you will see the trip duration and the turn-by-turn instructions in the sidebar.

Let users delete a route​

The last step is to add a function that allows your users to delete a route they have drawn on the map.

// If the user clicks the delete draw button, remove the layer if it exists
function removeRoute() {
  if (!map.getSource('route')) return;
  map.removeLayer('route');
  map.removeSource('route');
}

To connect the removeRoute function with the Mapbox GL Draw plugin's delete button, add the following line to your JavaScript:

map.on('draw.delete', removeRoute);

Save your work and refresh the browser page. When you draw a line and then click the Draw plugin's delete button, the line is removed from the page.

Final product​

You have created an app that uses the Mapbox Map Matching API to snap user-provided coordinates to the road network, while at the same time displaying the route on a map and showing users the turn-by-turn instructions for the route.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Demo: Get started with the Map Matching API</title>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <!-- Import Mapbox GL JS  -->
    <script src="https://api.tiles.mapbox.com/mapbox-gl-js/v3.3.0/mapbox-gl.js"></script>
    <link
      href="https://api.tiles.mapbox.com/mapbox-gl-js/v3.3.0/mapbox-gl.css"
      rel="stylesheet"
    />
    <!-- Import Mapbox GL Draw -->
    <script src="https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-draw/v1.0.9/mapbox-gl-draw.js"></script>
    <link
      rel="stylesheet"
      href="https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-draw/v1.0.9/mapbox-gl-draw.css"
      type="text/css"
    />
    <style>
      body {
        margin: 0;
        padding: 0;
        font-family: sans-serif;
      }

      #map {
        position: absolute;
        top: 0;
        bottom: 0;
        width: 100%;
      }

      .info-box {
        position: absolute;
        margin: 20px;
        width: 25%;
        top: 0;
        bottom: 20px;
        padding: 20px;
        background-color: #fff;
        overflow-y: scroll;
      }
    </style>
  </head>

  <body>
    <!-- Create a container for the map -->
    <div id="map"></div>
    <!-- Create a container for the instructions and directions -->
    <div class="info-box">
      <p>
        Draw your route using the draw tools on the right. To get the most
        accurate route match, draw points at regular intervals.
      </p>
      <div id="directions"></div>
    </div>

    <script>
      // Add your Mapbox access token
      mapboxgl.accessToken = '{{MAPBOX_ACCESS_TOKEN}}';
      const map = new mapboxgl.Map({
        container: 'map', // Specify the container ID
        style: 'mapbox://styles/mapbox/streets-v12', // Specify which map style to use
        center: [-122.42136449, 37.80176523], // Specify the starting position
        zoom: 14.5 // Specify the starting zoom
      });

      const draw = new MapboxDraw({
        // Instead of showing all the draw tools, show only the line string and delete tools
        displayControlsDefault: false,
        controls: {
          line_string: true,
          trash: true
        },
        // Set the draw mode to draw LineStrings by default
        defaultMode: 'draw_line_string',
        styles: [
          // Set the line style for the user-input coordinates
          {
            'id': 'gl-draw-line',
            'type': 'line',
            'filter': [
              'all',
              ['==', '$type', 'LineString'],
              ['!=', 'mode', 'static']
            ],
            'layout': {
              'line-cap': 'round',
              'line-join': 'round'
            },
            'paint': {
              'line-color': '#438EE4',
              'line-dasharray': [0.2, 2],
              'line-width': 2,
              'line-opacity': 0.7
            }
          },
          // Style the vertex point halos
          {
            'id': 'gl-draw-polygon-and-line-vertex-halo-active',
            'type': 'circle',
            'filter': [
              'all',
              ['==', 'meta', 'vertex'],
              ['==', '$type', 'Point'],
              ['!=', 'mode', 'static']
            ],
            'paint': {
              'circle-radius': 12,
              'circle-color': '#FFF'
            }
          },
          // Style the vertex points
          {
            'id': 'gl-draw-polygon-and-line-vertex-active',
            'type': 'circle',
            'filter': [
              'all',
              ['==', 'meta', 'vertex'],
              ['==', '$type', 'Point'],
              ['!=', 'mode', 'static']
            ],
            'paint': {
              'circle-radius': 8,
              'circle-color': '#438EE4'
            }
          }
        ]
      });

      // Add the draw tool to the map
      map.addControl(draw);

      // Add create, update, or delete actions
      map.on('draw.create', updateRoute);
      map.on('draw.update', updateRoute);
      map.on('draw.delete', removeRoute);

      // Use the coordinates you just drew to make the Map Matching API request
      function updateRoute() {
        removeRoute(); // Overwrite any existing layers

        const profile = 'driving'; // Set the profile

        // Get the coordinates
        const data = draw.getAll();
        const lastFeature = data.features.length - 1;
        const coords = data.features[lastFeature].geometry.coordinates;
        // Format the coordinates
        const newCoords = coords.join(';');
        // Set the radius for each coordinate pair to 25 meters
        const radius = coords.map(() => 25);
        getMatch(newCoords, radius, profile);
      }

      // Make a Map Matching request
      async function getMatch(coordinates, radius, profile) {
        // Separate the radiuses with semicolons
        const radiuses = radius.join(';');
        // Create the query
        const query = await fetch(
          `https://api.mapbox.com/matching/v5/mapbox/${profile}/${coordinates}?geometries=geojson&radiuses=${radiuses}&steps=true&access_token=${mapboxgl.accessToken}`,
          { method: 'GET' }
        );
        const response = await query.json();
        // Handle errors
        if (response.code !== 'Ok') {
          alert(
            `${response.code} - ${response.message}.\n\nFor more information: https://docs.mapbox.com/api/navigation/map-matching/#map-matching-api-errors`
          );
          return;
        }
        const coords = response.matchings[0].geometry;
        // Draw the route on the map
        addRoute(coords);
        getInstructions(response.matchings[0]);
      }

      function getInstructions(data) {
        // Target the sidebar to add the instructions
        const directions = document.getElementById('directions');
        let tripDirections = '';
        // Output the instructions for each step of each leg in the response object
        for (const leg of data.legs) {
          const steps = leg.steps;
          for (const step of steps) {
            tripDirections += `<li>${step.maneuver.instruction}</li>`;
          }
        }
        directions.innerHTML = `<p><strong>Trip duration: ${Math.floor(
          data.duration / 60
        )} min.</strong></p><ol>${tripDirections}</ol>`;
      }

      // Draw the Map Matching route as a new layer on the map
      function addRoute(coords) {
        // If a route is already loaded, remove it
        if (map.getSource('route')) {
          map.removeLayer('route');
          map.removeSource('route');
        } else {
          map.addLayer({
            'id': 'route',
            'type': 'line',
            'source': {
              'type': 'geojson',
              'data': {
                'type': 'Feature',
                'properties': {},
                'geometry': coords
              }
            },
            'layout': {
              'line-join': 'round',
              'line-cap': 'round'
            },
            'paint': {
              'line-color': '#03AA46',
              'line-width': 8,
              'line-opacity': 0.8
            }
          });
        }
      }

      // If the user clicks the delete draw button, remove the layer if it exists
      function removeRoute() {
        if (!map.getSource('route')) return;
        map.removeLayer('route');
        map.removeSource('route');
      }
    </script>
  </body>
</html>

Next steps​

To build on top of the tools and techniques you used in this tutorial, explore the following resources:

追加の開発者リソース
このpageは役に立ちましたか？