Find a route and directions

Learn how to find a route and directions with the route service.

Routing is the process of finding the path from an origin to a destination in a street network. You can use the Routing service to find routes, get driving directions, calculate drive times, and solve complicated, multiple vehicle routing problems. To create a route, you typically define a set of stops (origin and one or more destinations) and use the service to find a route with directions. You can also use a number of additional parameters such as barriers and mode of travel to refine the results.

In this tutorial, you will define an origin and destination by clicking on the map. These values are used to get a route and directions from the route service. The directions are also displayed on the map.

Prerequisites

You need an ArcGIS Developer or ArcGIS Online account to access the dashboard and create an API key.

Steps

Create a new pen

To get started, either complete the Display a map tutorial or .

Set the API key

To access ArcGIS services, you need an API key.

Go to your dashboard to get an API key.
In CodePen, set the apiKey to your key, so it can be used to access basemap layer and location services.

Use dark colors for code blocks
esriConfig.apiKey = "YOUR_API_KEY";
const map = new Map({
  basemap: "arcgis/topographic" // basemap styles service
});

Add modules

In the require statement, add the Graphic, route, RouteParameters, and FeatureSet modules.

The ArcGIS Maps SDK for JavaScript is available as AMD modules and ES modules, but this tutorial is based on AMD. The AMD require function uses references to determine which modules will be loaded – for example, you can specify "esri/Map" for loading the Map module. After the modules are loaded, they are passed as parameters (e.g. Map) to the callback function where they can be used in your application. It is important to keep the module references and callback parameters in the same order. For more information on the different types of modules, visit the Introduction to Tooling guide topic.

Expand
Use dark colors for code blocks
    require([
      "esri/config",
      "esri/Map",
      "esri/views/MapView",

      "esri/Graphic",
      "esri/rest/route",
      "esri/rest/support/RouteParameters",
      "esri/rest/support/FeatureSet"

    ], function(esriConfig, Map, MapView, Graphic, route, RouteParameters, FeatureSet) {
Expand

Update the map

A streets basemap layer is typically used in routing applications. Update the basemap property to use the arcgis/navigation basemap layer and change the position of the map to center on Los Angeles.

Update the basemap property to arcgis/navigation.

Expand
Use dark colors for code blocks
    ], function(esriConfig, Map, MapView, Graphic, route, RouteParameters, FeatureSet) {

    esriConfig.apiKey = "YOUR_API_KEY";

    const map = new Map({
      basemap: "arcgis/navigation" // basemap styles service
    });
Expand

Update the center property to -118.24532,34.05398 and set the zoom property to 12 to center on Los Angeles.

Expand
Use dark colors for code blocks
    esriConfig.apiKey = "YOUR_API_KEY";

    const map = new Map({
      basemap: "arcgis/navigation" // basemap styles service
    });

    const view = new MapView({
      container: "viewDiv",
      map: map,
      center: [-118.24532,34.05398], //Longitude, latitude
      zoom: 12
    });
Expand

Define the service url

The rest module makes a request to a service and returns the results. Use the route module to access the Routing service.

Create a variable called routeUrl to reference the route service.

Expand
Use dark colors for code blocks
    const view = new MapView({
      container: "viewDiv",
      map: map,
      center: [-118.24532,34.05398], //Longitude, latitude
      zoom: 12
    });

    const routeUrl = "https://route-api.arcgis.com/arcgis/rest/services/World/Route/NAServer/Route_World";
Expand

Get an origin and destination

A route module uses a stops parameter to find a route. Stops are graphics that represent the origin and destination locations for a route. Use a click handler in the View to add graphics when the map is clicked. The graphics will define the stops for the route.

Add a click handler to add graphics to the view.

Expand
Use dark colors for code blocks
    const routeUrl = "https://route-api.arcgis.com/arcgis/rest/services/World/Route/NAServer/Route_World";

    view.on("click", function(event){

    });
Expand

Create an addGraphic function to display a white marker for the origin location and a black marker for the destination. Add the graphic to the view.

Expand
Use dark colors for code blocks
    view.on("click", function(event){

    });

    function addGraphic(type, point) {
      const graphic = new Graphic({
        symbol: {
          type: "simple-marker",
          color: (type === "origin") ? "white" : "black",
          size: "8px"
        },
        geometry: point
      });
      view.graphics.add(graphic);
    }
Expand

Update the click handler to reference the addGraphic function. The first click will create the origin and the second will create the destination. Subsequent clicks will clear the graphics to define a new origin and destination.

Expand
Use dark colors for code blocks
    view.on("click", function(event){

      if (view.graphics.length === 0) {
        addGraphic("origin", event.mapPoint);
      } else if (view.graphics.length === 1) {
        addGraphic("destination", event.mapPoint);

      } else {
        view.graphics.removeAll();
        addGraphic("origin",event.mapPoint);
      }

    });
Expand

Click on the map twice to ensure the graphics are created.

Find the route

To solve the route, add the origin and destination graphics to the stops parameter as a FeatureSet and then use the solve method. The resulting route will be added to the map as a Graphic.

Input parameters are necessary to solve the route. While there are many parameters you can add, such as stops and barriers, at minimum you need to provide an origin and destination point.

Create a getRoute function to add RouteParameters and pass in the point graphics.

Expand
Use dark colors for code blocks
    function addGraphic(type, point) {
      const graphic = new Graphic({
        symbol: {
          type: "simple-marker",
          color: (type === "origin") ? "white" : "black",
          size: "8px"
        },
        geometry: point
      });
      view.graphics.add(graphic);
    }

    function getRoute() {
      const routeParams = new RouteParameters({
        stops: new FeatureSet({
          features: view.graphics.toArray()
        }),

      });

    }
Expand

Call the solve method to get the route. When the method returns, get the route from routeResults and add it to the view as a Graphic with a blue line.

Expand
Use dark colors for code blocks
    function getRoute() {
      const routeParams = new RouteParameters({
        stops: new FeatureSet({
          features: view.graphics.toArray()
        }),

      });

      route.solve(routeUrl, routeParams)
        .then(function(data) {
          data.routeResults.forEach(function(result) {
            result.route.symbol = {
              type: "simple-line",
              color: [5, 150, 255],
              width: 3
            };
            view.graphics.add(result.route);
          });

        })

    }
Expand

Update the click handler with the getRoute function after the second graphic is passed in (destination).

Expand
Use dark colors for code blocks
    view.on("click", function(event){

      if (view.graphics.length === 0) {
        addGraphic("origin", event.mapPoint);
      } else if (view.graphics.length === 1) {
        addGraphic("destination", event.mapPoint);

        getRoute(); // Call the route service

      } else {
        view.graphics.removeAll();
        addGraphic("origin",event.mapPoint);
      }

    });
Expand

Click two locations on the map to display a route.

Get directions

You can get driving directions from the route service with the returnDirections property on RouteParameters. Use this property to return directions and add them to the map as HTML elements.

Go back to the getRoute function and set the returnDirections property to true.

Expand
Use dark colors for code blocks
    function getRoute() {
      const routeParams = new RouteParameters({
        stops: new FeatureSet({
          features: view.graphics.toArray()
        }),

        returnDirections: true

      });

      route.solve(routeUrl, routeParams)
        .then(function(data) {
          data.routeResults.forEach(function(result) {
            result.route.symbol = {
              type: "simple-line",
              color: [5, 150, 255],
              width: 3
            };
            view.graphics.add(result.route);
          });

        })

    }
Expand

After the solve method has resolved, create a directions ordered list element that will display if there are results returned to generate a route.

Expand
Use dark colors for code blocks
      route.solve(routeUrl, routeParams)
        .then(function(data) {
          data.routeResults.forEach(function(result) {
            result.route.symbol = {
              type: "simple-line",
              color: [5, 150, 255],
              width: 3
            };
            view.graphics.add(result.route);
          });

          // Display directions
         if (data.routeResults.length > 0) {
           const directions = document.createElement("ol");
           directions.classList = "esri-widget esri-widget--panel esri-directions__scroller";
           directions.style.marginTop = "0";
           directions.style.padding = "15px 15px 15px 30px";
           const features = data.routeResults[0].directions.features;

         }

        })

Expand

Create a li element for each route feature to generate an ordered list of directions with their distances in miles. Append each direction to the directions element.

Expand
Use dark colors for code blocks
          // Display directions
         if (data.routeResults.length > 0) {
           const directions = document.createElement("ol");
           directions.classList = "esri-widget esri-widget--panel esri-directions__scroller";
           directions.style.marginTop = "0";
           directions.style.padding = "15px 15px 15px 30px";
           const features = data.routeResults[0].directions.features;

           // Show each direction
           features.forEach(function(result,i){
             const direction = document.createElement("li");
             direction.innerHTML = result.attributes.text + " (" + result.attributes.length.toFixed(2) + " miles)";
             directions.appendChild(direction);
           });

         }
Expand

For each new route created, remove all existing HTML elements from the view with the empty method. Add the direction element, with the directions as list items, to the top-right of the view.

Expand
Use dark colors for code blocks
           // Show each direction
           features.forEach(function(result,i){
             const direction = document.createElement("li");
             direction.innerHTML = result.attributes.text + " (" + result.attributes.length.toFixed(2) + " miles)";
             directions.appendChild(direction);
           });

          view.ui.empty("top-right");
          view.ui.add(directions, "top-right");
Expand

Add a catch statement to display any errors in the console.

Expand
Use dark colors for code blocks
      route.solve(routeUrl, routeParams)
        .then(function(data) {
          data.routeResults.forEach(function(result) {
            result.route.symbol = {
              type: "simple-line",
              color: [5, 150, 255],
              width: 3
            };
            view.graphics.add(result.route);
          });

          // Display directions
         if (data.routeResults.length > 0) {
           const directions = document.createElement("ol");
           directions.classList = "esri-widget esri-widget--panel esri-directions__scroller";
           directions.style.marginTop = "0";
           directions.style.padding = "15px 15px 15px 30px";
           const features = data.routeResults[0].directions.features;

           // Show each direction
           features.forEach(function(result,i){
             const direction = document.createElement("li");
             direction.innerHTML = result.attributes.text + " (" + result.attributes.length.toFixed(2) + " miles)";
             directions.appendChild(direction);
           });

          view.ui.empty("top-right");
          view.ui.add(directions, "top-right");

         }

        })

        .catch(function(error){
            console.log(error);
        })
Expand

Run the App

In CodePen, run your code to display the map.

Click on the map twice to display the route directions. The map should support two clicks to create an origin and destination point and then use the route service to display the resulting route and turn-by-turn directions.

What's next?

Learn how to use additional API features and ArcGIS services in these tutorials: