Find a route and directions

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

find a route and directions

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 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

The following are required for this tutorial:

An ArcGIS account to access your API keys. If you don't have an account, sign up for free.
Your system meets the system requirements.

Steps

Open the Xcode project

To start the tutorial, complete the Display a map tutorial or download and unzip the solution.
Open the .xcodeproj file in Xcode.

If you downloaded the solution project, set your API key.

An API Key enables access to services, web maps, and web scenes hosted in ArcGIS Online.

Go to your developer dashboard to get your API key. For these tutorials, use your default API key. It is scoped to include all of the services demonstrated in the tutorials.
In Xcode, in the Project Navigator, click AppDelegate.swift.

In the editor, set the APIKey property on the AGSArcGISRuntimeEnvironment with your API key.

AppDelegate.swift
Expand
Use dark colors for code blocks
Change line
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Note: it is not best practice to store API keys in source code.
        // The API key is referenced here for the convenience of this tutorial.

        AGSArcGISRuntimeEnvironment.apiKey = "YOUR_API_KEY"

        return true
    }
Expand

Update the map

A navigation basemap layer is typically used in routing applications. Update the basemap to use the .arcGISNavigation basemap style, and change the position of the map to center on Los Angeles.

Update the AGSBasemap style property from .arcGISTopographic to .arcGISNavigation and update the latitude and longitude coordinates to center on Los Angeles.

ViewController.swift
Expand
Use dark colors for code blocks
Change lineChange lineChange lineChange lineChange lineChange lineChange lineChange line
    private func setupMap() {

        mapView.map = AGSMap(basemapStyle: .arcGISNavigation)
        mapView.setViewpoint(
            AGSViewpoint(
                latitude: 34.05293,
                longitude: -118.24368,
                scale: 288_895
            )
        )
    }
Expand

Receive map view touch events

The app will use locations derived from a user tapping the map view to generate the stops of a route. Conform the view controller to receive touch events from the map view. The locations derived from a user tapping the map view will be used to generate routes in a later step.

In Xcode, in the Project Navigator, click ViewController.swift.

In the editor, extend ViewController to conform to the AGSGeoViewTouchDelegate protocol and include the geoView:didTapAtScreenPoint:mapPoint:() geoview touch delegate method.

ViewController.swift
Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.Add line.Add line.
// MARK: - GeoView Touch Delegate

extension ViewController: AGSGeoViewTouchDelegate {

    func geoView(_ geoView: AGSGeoView, didTapAtScreenPoint screenPoint: CGPoint, mapPoint: AGSPoint) {

    }

}

In the setupMap() method, assign ViewController to mapView.delegate.

This step bridges mapView user touch interactions with ViewController via the AGSGeoViewTouchDelegate protocol.

ViewController.swift
Expand
Use dark colors for code blocks
Add line.
    private func setupMap() {

        mapView.touchDelegate = self

        mapView.map = AGSMap(basemapStyle: .arcGISNavigation)
        mapView.setViewpoint(
            AGSViewpoint(
                latitude: 34.05293,
                longitude: -118.24368,
                scale: 288_895
            )
        )
    }
Expand

Add graphics to the map view

A graphics overlay is a container for graphics. Graphics are added as a visual means to display the search result on the map.

Create a private AGSGraphic property named startGraphic. This graphic will be used to display the route's start location.

An AGSSimpleMarkerSymbol is used to display a location on the map view.

ViewController.swift
Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.Add line.
    // MARK: - Route Graphics

    private let startGraphic: AGSGraphic = {
        let symbol = AGSSimpleMarkerSymbol(style: .circle, color: .white, size: 8)
        symbol.outline = AGSSimpleLineSymbol(style: .solid, color: .black, width: 1)
        let graphic = AGSGraphic(geometry: nil, symbol: symbol)
        return graphic
    }()

Expand

Create a private AGSGraphic property named endGraphic. This graphic will be used to display the route's end location.

An AGSSimpleMarkerSymbol is used to display a location on the map view.

ViewController.swift
Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.Add line.
    // MARK: - Route Graphics

    private let startGraphic: AGSGraphic = {
        let symbol = AGSSimpleMarkerSymbol(style: .circle, color: .white, size: 8)
        symbol.outline = AGSSimpleLineSymbol(style: .solid, color: .black, width: 1)
        let graphic = AGSGraphic(geometry: nil, symbol: symbol)
        return graphic
    }()

    private let endGraphic: AGSGraphic = {
        let symbol = AGSSimpleMarkerSymbol(style: .circle, color: .black, size: 8)
        symbol.outline = AGSSimpleLineSymbol(style: .solid, color: .black, width: 1)
        let graphic = AGSGraphic(geometry: nil, symbol: symbol)
        return graphic
    }()

Expand

Create a private AGSGraphic property named routeGraphic. This graphic will be used to display the route line.

An AGSSimpleLineSymbol is used to display a line on the map view.

ViewController.swift
Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.
    private let endGraphic: AGSGraphic = {
        let symbol = AGSSimpleMarkerSymbol(style: .circle, color: .black, size: 8)
        symbol.outline = AGSSimpleLineSymbol(style: .solid, color: .black, width: 1)
        let graphic = AGSGraphic(geometry: nil, symbol: symbol)
        return graphic
    }()

    private let routeGraphic: AGSGraphic = {
        let symbol = AGSSimpleLineSymbol(style: .solid, color: .blue, width: 3)
        let graphic = AGSGraphic(geometry: nil, symbol: symbol)
        return graphic
    }()
Expand

Define a private method named addGraphics(). In addGraphics() create an AGSGraphicsOverlay. Append startGraphic, endGraphic, and routeGraphic to the graphics overlay and add the graphics overlay to the map view.

Because startGraphic, endGraphic, and routeGraphic haven't yet specified a geometry, they will not be visible.

ViewController.swift
Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.
    private let routeGraphic: AGSGraphic = {
        let symbol = AGSSimpleLineSymbol(style: .solid, color: .blue, width: 3)
        let graphic = AGSGraphic(geometry: nil, symbol: symbol)
        return graphic
    }()

    private func addGraphics() {
        let routeGraphics = AGSGraphicsOverlay()
        mapView.graphicsOverlays.add(routeGraphics)
        routeGraphics.graphics.addObjects(from: [routeGraphic, startGraphic, endGraphic])
    }
Expand

In the viewDidLoad() method, call addGraphics().

ViewController.swift
Expand
Use dark colors for code blocks
Add line.
    override func viewDidLoad() {
        super.viewDidLoad()
        setupMap()

        addGraphics()

    }
Expand

Define app route builder status

The app will leverage a state-machine design pattern to ensure the contents of the map reflect the state of gathering the route parameters and generating the route result. This design pattern supports wrangling multiple asynchronous requests to the world routing service into a single state variable result, ensuring the reliability of route results.

Define an enum named RouteBuilderStatus with four cases. These four cases are used to gather route parameters and display the route's result, over time.

ViewController.swift
Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.Add line.Add line.
    // MARK: - Route Builder

    private enum RouteBuilderStatus {
        case none
        case selectedStart(AGSPoint)
        case selectedStartAndEnd(AGSPoint, AGSPoint)
        case routeSolved(AGSPoint, AGSPoint, AGSRoute)

    }

Expand

Define a method of RouteBuilderStatus named nextStatusWith:point(). This method is used to step through generating a route, over time.

ViewController.swift
Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.
    // MARK: - Route Builder

    private enum RouteBuilderStatus {
        case none
        case selectedStart(AGSPoint)
        case selectedStartAndEnd(AGSPoint, AGSPoint)
        case routeSolved(AGSPoint, AGSPoint, AGSRoute)

        func nextStatus(with point: AGSPoint) -> RouteBuilderStatus {
            switch self {
            case .none:
                return .selectedStart(point)
            case .selectedStart(let start):
                return .selectedStartAndEnd(start, point)
            case .selectedStartAndEnd:
                return .selectedStart(point)
            case .routeSolved:
                return .selectedStart(point)
            }
        }

    }

Expand

Create a private RouteBuilderStatus property named status. Set the default value .none.

This property maintains the status of route parameters as they are gathered and the route is generated, over time. Updating the status will update the geometry of route graphics and display them in the map view.

ViewController.swift
Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.
    private var status: RouteBuilderStatus = .none {
        didSet {
            switch status {
            case .none:
                startGraphic.geometry = nil
                endGraphic.geometry = nil
                routeGraphic.geometry = nil
            case .selectedStart(let start):
                startGraphic.geometry = start
                endGraphic.geometry = nil
                routeGraphic.geometry = nil
            case .selectedStartAndEnd(let start, let end):
                startGraphic.geometry = start
                endGraphic.geometry = end
                routeGraphic.geometry = nil
            case .routeSolved(let start, let end, let route):
                startGraphic.geometry = start
                endGraphic.geometry = end
                routeGraphic.geometry = route.routeGeometry
            }
        }
    }
Expand

Add a UI to display driving directions

To display the turn-by-turn directions from the route, a UI element is required.

Create a private lazy UIBarButtonItem property named directionsButton. Lazy loading the bar button item guarantees self is created prior to assigning the button's target.

ViewController.swift
Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.
    // MARK: - Directions Button

    private lazy var directionsButton: UIBarButtonItem = {
        let button = UIBarButtonItem(title: "Show Directions", style: .plain, target: self, action: #selector(displayDirections))
        button.isEnabled = false
        return button
    }()

Expand

Define a method named displayDirections:() and assign it the @objc keyword. The @objc method keyword exposes the method to Objective-C, a necessary step for using the UIBarButtonItem API.

This method collates the route maneuvers and presents the directions to the user in an alert.

ViewController.swift
Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.
    // MARK: - Directions Button

    private lazy var directionsButton: UIBarButtonItem = {
        let button = UIBarButtonItem(title: "Show Directions", style: .plain, target: self, action: #selector(displayDirections))
        button.isEnabled = false
        return button
    }()

    @objc
    func displayDirections(_ sender: AnyObject) {
        guard case let .routeSolved(_, _, route) = status else { return }
        let directions = route.directionManeuvers.enumerated()
            .reduce(into: "\n") { $0 += "\($1.offset + 1). \($1.element.directionText).\n\n" }
        let alert = UIAlertController(title: "Directions", message: directions, preferredStyle: .alert)
        let okay = UIAlertAction(title: "Hide Directions", style: .default, handler: nil)
        alert.addAction(okay)
        present(alert, animated: true, completion: nil)
    }
Expand

In the status property's didSet closure, update each state to enable or disable the directionsButton. The directions button should be enabled only if the route is solved.
ViewController.swift
Expand
Use dark colors for code blocks
95 95 95 95 95 95 95 95 95 95 95 95 95 95 95 95 95 95 95 95 95 95 95 95 95 95 94 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109