Find a route and directions

Before starting this tutorial:

1. You need an ArcGIS Location Platform or ArcGIS Online account.

2. Your system meets the system requirements.

Option 1: Develop the code

To start the tutorial, complete the Display a map tutorial. This creates a map to display the Santa Monica Mountains in California using the topographic basemap from the ArcGIS Basemap Styles service The ArcGIS Basemap Styles service, also referred to as the Basemap Styles service, is a location service that provides basemap styles and data for the world. It returns styles as Mapbox styles and web maps, and data as vector tiles and/or map tiles. It supports all of the styles in the ArcGIS Basemap style and Open Basemap style family. An ArcGIS Location Platform or ArcGIS Online account is required to use the service. Learn more .

Continue with the following instructions to find a route and directions with the ArcGIS Routing service A routing service is a service that uses network analysis and streets data to calculate the most effective path and turn-by-turn directions on a street network, optimize fleet routing and deliveries, find the closest facilities, calculate service areas, and more. It is hosted by Esri as the ArcGIS Routing service and can also be hosted in ArcGIS Enterprise. Learn more . First, you need to set the develop credentials in your app so that your app users can access the ArcGIS Routing service A routing service is a service that uses network analysis and streets data to calculate the most effective path and turn-by-turn directions on a street network, optimize fleet routing and deliveries, find the closest facilities, calculate service areas, and more. It is hosted by Esri as the ArcGIS Routing service and can also be hosted in ArcGIS Enterprise. Learn more .

Set developer credentials

If you implemented API key authentication API key authentication is a type of authentication that uses an API key to authenticate requests to ArcGIS services and secure portal items. Learn more in the Display a map tutorial, the API key access token will only have the Basemaps privilege. The Find a route and directions tutorial requires the Routing privilege to find a route using the RouteTask. To create an API Key access token that has the Basemaps and Routing privileges, see the Set up authentication step and then follow the instructions below.

Update the map

A navigation basemap layer A basemap layer is the layer in a map or scene that displays basemap data. The data source for a basemap layer is typically a basemap service. Learn more 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.

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

   ContentView.swift

   1
   struct ContentView: View {
   2
   
   3
       @State var map = {
   4
   
   5
           let map = Map(basemapStyle: .arcGISNavigation)
   6
           map.initialViewpoint = Viewpoint(latitude: 34.05293, longitude: -118.24368, scale: 2e5)
   7
   
   8
           return map
   9
       }()

2. Create a private class named Model of type ObservableObject and add a @StateObject variable of the Model to the ContentView. See the programming patterns page for more information on how to manage states.

   ContentView.swift

   1
   import SwiftUI
   2
   
   3
   import ArcGIS
   4
   
   5
   class Model: ObservableObject {
   6
   
   7
   }
   8
   
   9
   struct ContentView: View {
   10
   
   11
       @StateObject private var model = Model()
   12
   
   13
       @State var map = {
   14
   
   15
           let map = Map(basemapStyle: .arcGISNavigation)
   16
           map.initialViewpoint = Viewpoint(latitude: 34.05293, longitude: -118.24368, scale: 2e5)
   17
   
   18
           return map
   19
       }()
   20
   
   21
   }

Add graphics to the map view

A graphics overlay A graphics overlay is a client-side, temporary container of graphics to display on a map view or scene view. Learn more is a container for graphics A graphic is a visual element composed of a geometry, symbol, and attributes that is displayed on a map or scene. Learn more . Graphics are added as a visual means to display the search result on the map A map is a collection of layers that are displayed in 2D. It is typically composed of a basemap layer and data layers. Learn more .

1. In the Model class, create a GraphicsOverlay named graphicsOverlay. In the ContentView, add the graphics overlay A graphics overlay is a client-side, temporary container of graphics to display on a map view or scene view. Learn more to the map view.

   More info

   A graphics overlay A graphics overlay is a client-side, temporary container of graphics to display on a map view or scene view. Learn more is a container for graphics A graphic is a visual element composed of a geometry, symbol, and attributes that is displayed on a map or scene. Learn more . It is used with a map view A map view is a user interface that displays map layers and graphics in 2D. It controls the area (extent) of the map that is visible and supports user interactions such as pan and zoom. Learn more to display graphics on a map A map is a collection of layers that are displayed in 2D. It is typically composed of a basemap layer and data layers. Learn more . You can add more than one graphics overlay to a map view. Graphics overlays are displayed on top of all the other layers A layer is a reference to a collection of geographic data that is used to access and display data. The data for layers are typically provided by the basemap layer service and data services. Learn more .

   ContentView.swift

   1
   import SwiftUI
   2
   
   3
   import ArcGIS
   4
   
   5
   class Model: ObservableObject {
   6
   
   7
       let graphicsOverlay = GraphicsOverlay()
   8
   
   9
   }
   10
   
   11
   struct ContentView: View {
   12
   
   13
       @StateObject private var model = Model()
   14
   
   15
       @State var map = {
   16
   
   17
           let map = Map(basemapStyle: .arcGISNavigation)
   18
           map.initialViewpoint = Viewpoint(latitude: 34.05293, longitude: -118.24368, scale: 2e5)
   19
   
   20
           return map
   21
       }()
   22
   
   23
       var body: some View {
   24
   
   25
           MapView(map: map, graphicsOverlays: [model.graphicsOverlay])
   26
   
   27
       }
   28
   
   29
   }

2. Create a private Graphic property named startGraphic to the Model. Symbolize the graphic with a white circle and black outline. This graphic will be used to display the route’s start location.

   More info

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

   ContentView.swift

   1
   class Model: ObservableObject {
   2
   
   3
       let graphicsOverlay = GraphicsOverlay()
   4
   
   5
       let startGraphic: Graphic = {
   6
           let symbol = SimpleMarkerSymbol(style: .circle, color: .white, size: 8)
   7
           symbol.outline = SimpleLineSymbol(style: .solid, color: .black, width: 1)
   8
           let graphic = Graphic(symbol: symbol)
   9
           return graphic
   10
       }()
   11
   
   12
   }

3. Create a private Graphic property named endGraphic. Symbolize the graphic with a black circle. This graphic will be used to display the route’s end location.

   ContentView.swift

   1
   class Model: ObservableObject {
   2
   
   3
       let graphicsOverlay = GraphicsOverlay()
   4
   
   5
       let startGraphic: Graphic = {
   6
           let symbol = SimpleMarkerSymbol(style: .circle, color: .white, size: 8)
   7
           symbol.outline = SimpleLineSymbol(style: .solid, color: .black, width: 1)
   8
           let graphic = Graphic(symbol: symbol)
   9
           return graphic
   10
       }()
   11
   
   12
       let endGraphic: Graphic = {
   13
           let symbol = SimpleMarkerSymbol(style: .circle, color: .black, size: 9)
   14
           let graphic = Graphic(symbol: symbol)
   15
           return graphic
   16
       }()
   17
   
   18
   }

4. Create a private Graphic property named routeGraphic. Symbolize the graphic with a blue line. This graphic will be used to display the route line A polyline is a type of geometry containing ordered point coordinates and a spatial reference. Learn more .

   More info

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

   ContentView.swift

   1
       let endGraphic: Graphic = {
   2
           let symbol = SimpleMarkerSymbol(style: .circle, color: .black, size: 9)
   3
           let graphic = Graphic(symbol: symbol)
   4
           return graphic
   5
       }()
   6
   
   7
       let routeGraphic: Graphic = {
   8
           let symbol = SimpleLineSymbol(style: .solid, color: .blue, width: 3)
   9
           let graphic = Graphic(symbol: symbol)
   10
           return graphic
   11
       }()

5. Create an init() method in the Model that adds startGraphic, endGraphic, and routeGraphic to the graphics overlay. This method will be called when Model is initialized.

   More info

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

   ContentView.swift

   1
       let routeGraphic: Graphic = {
   2
           let symbol = SimpleLineSymbol(style: .solid, color: .blue, width: 3)
   3
           let graphic = Graphic(symbol: symbol)
   4
           return graphic
   5
       }()
   6
   
   7
       init() {
   8
           graphicsOverlay.addGraphics([routeGraphic, startGraphic, endGraphic])
   9
       }

Create a route task and route parameters

A task makes a request to a service A service, also known as an ArcGIS service, is software that supports an ArcGIS REST API and provides geospatial functionality or data. A service can be hosted by Esri or in ArcGIS Enterprise. Learn more and returns the results. Use the RouteTask class to access a routing service A routing service is a service that uses network analysis and streets data to calculate the most effective path and turn-by-turn directions on a street network, optimize fleet routing and deliveries, find the closest facilities, calculate service areas, and more. It is hosted by Esri as the ArcGIS Routing service and can also be hosted in ArcGIS Enterprise. Learn more .

1. Continuing in the Model, create a private RouteTask property named routeTask with the routing service.

   ContentView.swift

   1
       init() {
   2
           graphicsOverlay.addGraphics([routeGraphic, startGraphic, endGraphic])
   3
       }
   4
   
   5
       private let routeTask = RouteTask(
   6
           url: URL(string: "https://route-api.arcgis.com/arcgis/rest/services/World/Route/NAServer/Route_World")!
   7
       )

2. Create a variable named directions defined as an array of DirectionManeuver objects. This will contain the step by step directions from the start to the end point.

   ContentView.swift

   1
       private let routeTask = RouteTask(
   2
           url: URL(string: "https://route-api.arcgis.com/arcgis/rest/services/World/Route/NAServer/Route_World")!
   3
       )
   4
   
   5
       var directions: [DirectionManeuver] = []

3. Define a private, asynchronous function named solveRoute(start:end:) that takes a start and end Point. This method will be called when both the start and end points have been placed on the map.

   ContentView.swift

   1
       private let routeTask = RouteTask(
   2
           url: URL(string: "https://route-api.arcgis.com/arcgis/rest/services/World/Route/NAServer/Route_World")!
   3
       )
   4
   
   5
       var directions: [DirectionManeuver] = []
   6
   
   7
       func solveRoute(from start: Point, to end: Point) async throws {
   8
   
   9
       }

4. Create default RouteParameters from the routeTask named routeParameters. Configure the parameters by setting two stops (the start and end points) and specify that directions are returned.

   ContentView.swift

   1
       func solveRoute(from start: Point, to end: Point) async throws {
   2
   
   3
           let routeParameters = try await routeTask.makeDefaultParameters()
   4
           routeParameters.returnsDirections = true
   5
           routeParameters.setStops([Stop(point: start), Stop(point: end)])
   6
   
   7
       }

5. Call the solveRoute(using:) function on the routeTask and pass in the routeParameters. To display the solved route, get the first route from the RouteResult and assign its geometry to routeGraphic. To display the directions, assign the directionManeuvers value from the first route to the directions variable.

   ContentView.swift

   1
       func solveRoute(from start: Point, to end: Point) async throws {
   2
   
   3
           let routeParameters = try await routeTask.makeDefaultParameters()
   4
           routeParameters.returnsDirections = true
   5
           routeParameters.setStops([Stop(point: start), Stop(point: end)])
   6
   
   7
           let routeResult = try await routeTask.solveRoute(using: routeParameters)
   8
           if let firstRoute = routeResult.routes.first {
   9
               routeGraphic.geometry = firstRoute.geometry
   10
               directions = firstRoute.directionManeuvers
   11
           }
   12
   
   13
       }

Handle map view touch events

The app will use locations derived from a user tapping the map view A map view is a user interface that displays map layers and graphics in 2D. It controls the area (extent) of the map that is visible and supports user interactions such as pan and zoom. Learn more to generate the stops A stop is a single point along a route: it can be the origin, an intermediate stop, or destination. Learn more on a route A route is a polyline that defines the best path between two or more points in a street network. Learn more . Configure the view to handle 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.

1. In the ContentView struct, create two @State private variables of type Point named startPoint and endPoint. These will contain the start and end locations of the route.

   ContentView.swift

   1
   struct ContentView: View {
   2
   
   3
       @StateObject private var model = Model()
   4
   
   5
       @State private var startPoint: Point?
   6
       @State private var endPoint: Point?
   7
   
   8
       @State var map = {
   9
   
   10
           let map = Map(basemapStyle: .arcGISNavigation)
   11
           map.initialViewpoint = Viewpoint(latitude: 34.05293, longitude: -118.24368, scale: 2e5)
   12
   
   13
           return map
   14
       }()
   15
   
   16
       var body: some View {
   17
   
   18
           MapView(map: map, graphicsOverlays: [model.graphicsOverlay])
   19
   
   20
       }
   21
   
   22
   }

2. Add the onSingleTapGesture method to the map view. If it is the user’s first tap, set the startPoint to the current mapPoint. Otherwise, set the endPoint to the current mapPoint. Assign the geometries for startGraphic and endGraphic accordingly.

   ContentView.swift

   1
       var body: some View {
   2
   
   3
           MapView(map: map, graphicsOverlays: [model.graphicsOverlay])
   4
   
   5
               .onSingleTapGesture { _, mapPoint in
   6
                   if startPoint == nil {
   7
                       startPoint = mapPoint
   8
                       model.startGraphic.geometry = startPoint
   9
                   } else {
   10
                       endPoint = mapPoint
   11
                       model.endGraphic.geometry = endPoint
   12
                   }
   13
               }
   14
   
   15
       }

3. Add a .task modifier to the map view with endPoint as an identifier. This task is called if the value of endPoint changes. Ensure that the start and end points are not nil and pass them into the model’s solveRoute(start:end:) method. This attempts to solve the route using the start and end points.

   ContentView.swift

   1
       var body: some View {
   2
   
   3
           MapView(map: map, graphicsOverlays: [model.graphicsOverlay])
   4
   
   5
               .onSingleTapGesture { _, mapPoint in
   6
                   if startPoint == nil {
   7
                       startPoint = mapPoint
   8
                       model.startGraphic.geometry = startPoint
   9
                   } else {
   10
                       endPoint = mapPoint
   11
                       model.endGraphic.geometry = endPoint
   12
                   }
   13
               }
   14
   
   15
               .task(id: endPoint) {
   16
                   guard let startPoint = startPoint, let endPoint = endPoint else { return }
   17
                   do {
   18
                       try await model.solveRoute(from: startPoint, to: endPoint)
   19
                   } catch {
   20
                       print(error)
   21
                   }
   22
               }
   23
   
   24
       }

Add a UI to display driving directions

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

1. In the ContentView struct, add a Bool variable named isShowingDirections to indicate if the directions are shown or not. Set its initial value to false.

   ContentView.swift

   1
   struct ContentView: View {
   2
   
   3
       @StateObject private var model = Model()
   4
   
   5
       @State private var isShowingDirections = false
   6
   
   7
       @State private var startPoint: Point?
   8
       @State private var endPoint: Point?
   9
   
   10
       @State var map = {
   11
   
   12
           let map = Map(basemapStyle: .arcGISNavigation)
   13
           map.initialViewpoint = Viewpoint(latitude: 34.05293, longitude: -118.24368, scale: 2e5)
   14
   
   15
           return map
   16
       }()

2. Add a .toolbar and ToolbarItemGroup to the bottom of the map view.

   ContentView.swift

   1
       var body: some View {
   2
   
   3
           MapView(map: map, graphicsOverlays: [model.graphicsOverlay])
   4
   
   5
               .onSingleTapGesture { _, mapPoint in
   6
                   if startPoint == nil {
   7
                       startPoint = mapPoint
   8
                       model.startGraphic.geometry = startPoint
   9
                   } else {
   10
                       endPoint = mapPoint
   11
                       model.endGraphic.geometry = endPoint
   12
                   }
   13
               }
   14
   
   15
               .task(id: endPoint) {
   16
                   guard let startPoint = startPoint, let endPoint = endPoint else { return }
   17
                   do {
   18
                       try await model.solveRoute(from: startPoint, to: endPoint)
   19
                   } catch {
   20
                       print(error)
   21
                   }
   22
               }
   23
   
   24
               .toolbar {
   25
                   ToolbarItemGroup(placement: .bottomBar) {
   26
   
   27
                   }
   28
               }
   29
   
   30
       }

3. Add a Button, labeled “Show directions”, to the toolbar. This button indicates that the user wants to show the directions so toggle the isShowingDirections value to true.

   ContentView.swift

   1
               .toolbar {
   2
                   ToolbarItemGroup(placement: .bottomBar) {
   3
   
   4
                       Button("Show directions") {
   5
                           isShowingDirections = true
   6
                       }
   7
   
   8
                   }
   9
               }

4. Add a .popover with a NavigationView to the toolbar. Set the popover’s isPresented parameter to isShowingDirections. The popover will display according to the isShowingDirections value. Customize the navigation view.

   ContentView.swift

   1
               .toolbar {
   2
                   ToolbarItemGroup(placement: .bottomBar) {
   3
   
   4
                       Button("Show directions") {
   5
                           isShowingDirections = true
   6
                       }
   7
   
   8
                       .popover(isPresented: $isShowingDirections) {
   9
                           NavigationView {
   10
   
   11
                           }
   12
                           .navigationViewStyle(.stack)
   13
                           .frame(idealWidth: 320, idealHeight: 428)
   14
                       }
   15
   
   16
                   }
   17
               }

5. Within the NavigationView content, create a List with directions which contains an array of DirectionManeuver objects. Configure the navigation view with a title, display mode, and “Done” button. When the button is tapped, isShowingDirections is set to false which closes the popover.

   ContentView.swift

   1
                       .popover(isPresented: $isShowingDirections) {
   2
                           NavigationView {
   3
   
   4
                               List(model.directions, id: \.text) { directionManeuver in
   5
                                   Text(directionManeuver.text)
   6
                               }
   7
                               .navigationTitle("Directions")
   8
                               .navigationBarTitleDisplayMode(.inline)
   9
                               .toolbar {
   10
                                   ToolbarItem(placement: .confirmationAction) {
   11
                                       Button("Done") {
   12
                                           isShowingDirections = false
   13
                                       }
   14
                                   }
   15
                               }
   16
   
   17
                           }
   18
                           .navigationViewStyle(.stack)
   19
                           .frame(idealWidth: 320, idealHeight: 428)
   20
                       }

Run the solution

Press Command + R to run the app.

The map should support two taps to create an origin and destination point and then use the ArcGIS Routing service A routing service is a service that uses network analysis and streets data to calculate the most effective path and turn-by-turn directions on a street network, optimize fleet routing and deliveries, find the closest facilities, calculate service areas, and more. It is hosted by Esri as the ArcGIS Routing service and can also be hosted in ArcGIS Enterprise. Learn more to display the resulting route.

Option 2: Download the solution

1. Click the Download solution link under Solution and unzip the file to a location on your machine.

2. Open the .xcodeproj file in Xcode.

Since the downloaded solution does not contain authentication credentials, you must add the developer credentials that you created in the Set up authentication section.

Set developer credentials in the solution

To allow your app users to access ArcGIS location services ArcGIS Location Services, also referred to as Location Services, are services hosted by Esri that provide geospatial functionality for developing mapping applications. They include the ArcGIS Basemap Styles service, ArcGIS Static Basemap Tiles service, ArcGIS Places service, ArcGIS Geocoding service, ArcGIS Routing service, ArcGIS GeoEnrichment service, and ArcGIS Elevation service. An ArcGIS Location Platform or ArcGIS Online account is required to use the services. Learn more , use the developer credentials that you created in the Set up authentication step to authenticate requests for resources.

Run the solution

Press Command + R to run the app.

The map should support two taps to create an origin and destination point and then use the ArcGIS Routing service A routing service is a service that uses network analysis and streets data to calculate the most effective path and turn-by-turn directions on a street network, optimize fleet routing and deliveries, find the closest facilities, calculate service areas, and more. It is hosted by Esri as the ArcGIS Routing service and can also be hosted in ArcGIS Enterprise. Learn more to display the resulting route.