Learn how to find a route and directions with the route service
Routing is the process of finding the path from an origin
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
Before starting this tutorial:
-
You need an ArcGIS Location Platform or ArcGIS Online account.
-
Your system meets the system requirements.
Set up authentication
To access the secure ArcGIS location services
You can implement API key authentication or user authentication in this tutorial. Compare the differences below:
API key authentication
- Users are not required to sign in.
- Requires creating an API key credential
API key credentials are an item that contains the parameters used to create and manage long-lived access tokens for API key authentication. They are a type of developer credential. with the correct privileges. - API keys
An API key is a long-lived access token created using API key credentials. They are valid for up to one year and are typically embedded directly into client applications. are long-lived access tokens. - Service usage is billed to the API key owner/developer.
- Simplest authentication method to implement.
- Recommended approach for new ArcGIS developers.
Learn more in API key authentication.
User authentication
- Users are required to sign in with an ArcGIS account
An ArcGIS account is an identity with a user type and set of privileges that can access specific ArcGIS products, tools, APIs, services, and resources. The main account types that can be used for development are an ArcGIS Location Platform account, ArcGIS Online account, and ArcGIS Enterprise account. ArcGIS Location Platform and ArcGIS Online accounts are also associated with a subscription. . - User accounts must have privilege
Privileges are a set of permissions assigned to ArcGIS accounts, developer credentials, and applications that grant access to secure resources and functionality in ArcGIS. to access the ArcGIS servicesA 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. used in application. - Requires creating OAuth credentials
OAuth credentials are an item that contains parameters required to implement user authentication or app authentication, including a .client_id,client_secret, and redirect URIs. They are a type of developer credential. - Application uses a redirect URL and client ID.
- Service usage is billed to the organization of the user signed into the application.
Learn more in User authentication.
To complete this tutorial, click on the tab in the switcher below for your authentication type of choice, either API key authentication or User authentication.
Create a new API key access token
-
Complete the Create an API key tutorial and create an API key with the following privilege(s)
Privileges are a set of permissions assigned to ArcGIS accounts, developer credentials, and applications that grant access to secure resources and functionality in ArcGIS. :- Privileges
- Location services > Basemaps
- Location services > Routing
- Privileges
-
Copy and paste the API key access token into a safe location. It will be used in a later step.
Develop or Download
You have two options for completing this tutorial:
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
Continue with the following instructions to find a route and directions with the ArcGIS Routing service
Set developer credentials
If you implemented API key authenticationRouteTask. 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.
Pass your API Key access token to the ArcGISEnvironment.
-
In the Project Navigator, click MainApp.swift.
-
Set the
ArcGISproperty with your API key access token.Environment.api Key MainApp.swiftUse dark colors for code blocks ArcGISEnvironment.apiKey = APIKey("<#YOUR-ACCESS-TOKEN#>")
Best Practice: The access token is stored directly in the code as a convenience for this tutorial. Do not store credentials directly in source code in a production environment.
Update the map
A navigation basemap layer.arc basemap style, and change the position of the map to center on Los Angeles.
-
Update the
Basemapstyle property from.arctoGIS Topographic .arcand update the latitude and longitude coordinates to center on Los Angeles.GIS Navigation ContentView.swiftUse dark colors for code blocks 69 70 71 72 75 76 77Change line Change line struct ContentView: View { @State var map = { let map = Map(basemapStyle: .arcGISNavigation) map.initialViewpoint = Viewpoint(latitude: 34.05293, longitude: -118.24368, scale: 2e5) return map }() -
Create a private class named
Modelof typeObservableand add aObject @variable of theState Object Modelto theContent. See the programming patterns page for more information on how to manage states.View ContentView.swiftUse dark colors for code blocks 16 17 18 19 23 24 25 27 28 29 30 31 32 33 34 35 36Add line. Add line. Add line. Add line. import SwiftUI import ArcGIS class Model: ObservableObject { } struct ContentView: View { @StateObject private var model = Model() @State var map = { let map = Map(basemapStyle: .arcGISNavigation) map.initialViewpoint = Viewpoint(latitude: 34.05293, longitude: -118.24368, scale: 2e5) return map }() }
Add graphics to the map view
A graphics overlay
-
In the
Modelclass, create aGraphicsOverlaynamedgraphics. In theOverlay Content, add the graphics overlayView A graphics overlay is a client-side, temporary container of graphics to display on a map view or scene view. 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. is a container for graphicsA graphic is a visual element composed of a geometry, symbol, and attributes that is displayed on a map or scene. . It is used with a map viewA 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. to display graphics on a mapA map is a collection of layers that are displayed in 2D. It is typically composed of a basemap layer and data layers. . You can add more than one graphics overlay to a map view. Graphics overlays are displayed on top of all the other layersA 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. .ContentView.swiftUse dark colors for code blocks 16 17 18 19 20 21 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 41 42 43 44Add line. Change line import SwiftUI import ArcGIS class Model: ObservableObject { let graphicsOverlay = GraphicsOverlay() } struct ContentView: View { @StateObject private var model = Model() @State var map = { let map = Map(basemapStyle: .arcGISNavigation) map.initialViewpoint = Viewpoint(latitude: 34.05293, longitude: -118.24368, scale: 2e5) return map }() var body: some View { MapView(map: map, graphicsOverlays: [model.graphicsOverlay]) } } -
Create a private
Graphicproperty namedstartto theGraphic Model. Symbolize the graphic with a white circle and black outline. This graphic will be used to display the route's start location.An
SimpleMarkerSymbolis used to display a location on the map view.ContentView.swiftUse dark colors for code blocks 20 21 22 23 30 31Add line. Add line. Add line. Add line. Add line. Add line. class Model: ObservableObject { let graphicsOverlay = GraphicsOverlay() let startGraphic: Graphic = { let symbol = SimpleMarkerSymbol(style: .circle, color: .white, size: 8) symbol.outline = SimpleLineSymbol(style: .solid, color: .black, width: 1) let graphic = Graphic(symbol: symbol) return graphic }() } -
Create a private
Graphicproperty namedend. Symbolize the graphic with a black circle. This graphic will be used to display the route's end location.Graphic ContentView.swiftUse dark colors for code blocks 20 21 22 23 24 25 26 27 28 29 30 36 37Add line. Add line. Add line. Add line. Add line. class Model: ObservableObject { let graphicsOverlay = GraphicsOverlay() let startGraphic: Graphic = { let symbol = SimpleMarkerSymbol(style: .circle, color: .white, size: 8) symbol.outline = SimpleLineSymbol(style: .solid, color: .black, width: 1) let graphic = Graphic(symbol: symbol) return graphic }() let endGraphic: Graphic = { let symbol = SimpleMarkerSymbol(style: .circle, color: .black, size: 9) let graphic = Graphic(symbol: symbol) return graphic }() } -
Create a private
Graphicproperty namedroute. Symbolize the graphic with a blue line. This graphic will be used to display the route lineGraphic A polyline is a type of geometry containing ordered point coordinates and a spatial reference. .An
SimpleLineSymbolis used to display a line on the map view.ContentView.swiftUse dark colors for code blocks 31 32 33 34 35 36Add line. Add line. Add line. Add line. Add line. let endGraphic: Graphic = { let symbol = SimpleMarkerSymbol(style: .circle, color: .black, size: 9) let graphic = Graphic(symbol: symbol) return graphic }() let routeGraphic: Graphic = { let symbol = SimpleLineSymbol(style: .solid, color: .blue, width: 3) let graphic = Graphic(symbol: symbol) return graphic }() -
Create an
init()method in theModelthat addsstart,Graphic end, andGraphic routeto the graphics overlay. This method will be called whenGraphic Modelis initialized.Because
start,Graphic end, andGraphic routehaven't yet specified aGraphic Geometry, they will not be visible.ContentView.swiftUse dark colors for code blocks 37 38 39 40 41 42Add line. Add line. Add line. let routeGraphic: Graphic = { let symbol = SimpleLineSymbol(style: .solid, color: .blue, width: 3) let graphic = Graphic(symbol: symbol) return graphic }() init() { graphicsOverlay.addGraphics([routeGraphic, startGraphic, endGraphic]) }
Create a route task and route parameters
A task makes a request to a serviceRouteTask class to access a routing service
A routing service with global coverage is part of ArcGIS location services. You can also publish custom routing services using ArcGIS Enterprise.
-
Continuing in the
Model, create a privateRouteTaskproperty namedroutewith the routing service.Task ContentView.swiftUse dark colors for code blocks 43 44 45 46Add line. Add line. Add line. init() { graphicsOverlay.addGraphics([routeGraphic, startGraphic, endGraphic]) } private let routeTask = RouteTask( url: URL(string: "https://route-api.arcgis.com/arcgis/rest/services/World/Route/NAServer/Route_World")! ) -
Create a variable named
directionsdefined as an array ofDirectionManeuverobjects. This will contain the step by step directions from the start to the end point.ContentView.swiftUse dark colors for code blocks 47 48 49 50 52Add line. private let routeTask = RouteTask( url: URL(string: "https://route-api.arcgis.com/arcgis/rest/services/World/Route/NAServer/Route_World")! ) var directions: [DirectionManeuver] = [] -
Define a private, asynchronous function named
solvethat takes a start and endRoute(start :end :) Point. This method will be called when both the start and end points have been placed on the map.ContentView.swiftUse dark colors for code blocks 47 48 49 50 51 52Add line. Add line. Add line. private let routeTask = RouteTask( url: URL(string: "https://route-api.arcgis.com/arcgis/rest/services/World/Route/NAServer/Route_World")! ) var directions: [DirectionManeuver] = [] func solveRoute(from start: Point, to end: Point) async throws { } -
Create default
RouteParametersfrom theroutenamedTask route. Configure the parameters by setting two stops (the start and end points) and specify that directions are returned.Parameters ContentView.swiftUse dark colors for code blocks 53 54 58 59Add line. Add line. Add line. func solveRoute(from start: Point, to end: Point) async throws { let routeParameters = try await routeTask.makeDefaultParameters() routeParameters.returnsDirections = true routeParameters.setStops([Stop(point: start), Stop(point: end)]) } -
Call the
solvefunction on theRoute(using :) routeand pass in theTask route. To display the solved route, get the first route from theParameters RouteResultand assign itsgeometrytoroute. To display the directions, assign theGraphic directionvalue from the first route to theManeuvers directionsvariable.ContentView.swiftUse dark colors for code blocks 53 54 55 56 57 58 64 65Add line. Add line. Add line. Add line. Add line. func solveRoute(from start: Point, to end: Point) async throws { let routeParameters = try await routeTask.makeDefaultParameters() routeParameters.returnsDirections = true routeParameters.setStops([Stop(point: start), Stop(point: end)]) let routeResult = try await routeTask.solveRoute(using: routeParameters) if let firstRoute = routeResult.routes.first { routeGraphic.geometry = firstRoute.geometry directions = firstRoute.directionManeuvers } }
Handle map view touch events
The app will use locations derived from a user tapping the map view
-
In the
Contentstruct, create twoView @private variables of typeState PointnamedstartandPoint end. These will contain the start and end locations of the route.Point ContentView.swiftUse dark colors for code blocks 69 70 71 72 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90Add line. Add line. struct ContentView: View { @StateObject private var model = Model() @State private var startPoint: Point? @State private var endPoint: Point? @State var map = { let map = Map(basemapStyle: .arcGISNavigation) map.initialViewpoint = Viewpoint(latitude: 34.05293, longitude: -118.24368, scale: 2e5) return map }() var body: some View { MapView(map: map, graphicsOverlays: [model.graphicsOverlay]) } } -
Add the
onSingleTapGesturemethod to the map view. If it is the user's first tap, set thestartto the currentPoint map. Otherwise, set thePoint endto the currentPoint map. Assign the geometries forPoint startandGraphic endaccordingly.Graphic ContentView.swiftUse dark colors for code blocks 86 87 88 89 99 100Add line. Add line. Add line. Add line. Add line. Add line. Add line. Add line. Add line. var body: some View { MapView(map: map, graphicsOverlays: [model.graphicsOverlay]) .onSingleTapGesture { _, mapPoint in if startPoint == nil { startPoint = mapPoint model.startGraphic.geometry = startPoint } else { endPoint = mapPoint model.endGraphic.geometry = endPoint } } } -
Add a
.taskmodifier to the map view withendas an identifier. This task is called if the value ofPoint endchanges. Ensure that the start and end points are not nil and pass them into the model'sPoint solvemethod. This attempts to solve the route using the start and end points.Route(start :end :) ContentView.swiftUse dark colors for code blocks 86 87 88 89 90 91 92 93 94 95 96 97 98 99 108 109Add line. Add line. Add line. Add line. Add line. Add line. Add line. Add line. var body: some View { MapView(map: map, graphicsOverlays: [model.graphicsOverlay]) .onSingleTapGesture { _, mapPoint in if startPoint == nil { startPoint = mapPoint model.startGraphic.geometry = startPoint } else { endPoint = mapPoint model.endGraphic.geometry = endPoint } } .task(id: endPoint) { guard let startPoint = startPoint, let endPoint = endPoint else { return } do { try await model.solveRoute(from: startPoint, to: endPoint) } catch { print(error) } } }
Add a UI to display driving directions
To display the turn-by-turn directions from the route, some UI element is required.
-
In the ContentView struct, add a
Boolvariable namedisto indicate if the directions are shown or not. Set its initial value toShowing Directions false.ContentView.swiftUse dark colors for code blocks 69 70 71 72 74 75 76 77 78 79 80 81 82 83 84Add line. struct ContentView: View { @StateObject private var model = Model() @State private var isShowingDirections = false @State private var startPoint: Point? @State private var endPoint: Point? @State var map = { let map = Map(basemapStyle: .arcGISNavigation) map.initialViewpoint = Viewpoint(latitude: 34.05293, longitude: -118.24368, scale: 2e5) return map }() -
Add a
.toolbarandToolbarto the bottom of the map view.Item Group ContentView.swiftUse dark colors for code blocks 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 114 115Add line. Add line. Add line. Add line. Add line. var body: some View { MapView(map: map, graphicsOverlays: [model.graphicsOverlay]) .onSingleTapGesture { _, mapPoint in if startPoint == nil { startPoint = mapPoint model.startGraphic.geometry = startPoint } else { endPoint = mapPoint model.endGraphic.geometry = endPoint } } .task(id: endPoint) { guard let startPoint = startPoint, let endPoint = endPoint else { return } do { try await model.solveRoute(from: startPoint, to: endPoint) } catch { print(error) } } .toolbar { ToolbarItemGroup(placement: .bottomBar) { } } } -
Add a
Button, labeled "Show directions", to the toolbar. This button indicates that the user wants to show the directions so toggle theisvalue toShowing Directions true.ContentView.swiftUse dark colors for code blocks 109 110 111 115 116 117Add line. Add line. Add line. .toolbar { ToolbarItemGroup(placement: .bottomBar) { Button("Show directions") { isShowingDirections = true } } } -
Add a
.popoverwith aNavigationto the toolbar. Set the popover'sView isparameter toPresented is. The popover will display according to theShowing Directions isvalue. Customize the navigation view.Showing Directions ContentView.swiftUse dark colors for code blocks 109 110 111 112 113 114 115 123 124 125Add line. Add line. Add line. Add line. Add line. Add line. Add line. .toolbar { ToolbarItemGroup(placement: .bottomBar) { Button("Show directions") { isShowingDirections = true } .popover(isPresented: $isShowingDirections) { NavigationView { } .navigationViewStyle(.stack) .frame(idealWidth: 320, idealHeight: 428) } } } -
Within the
Navigationcontent, create aView Listwithdirectionswhich contains an array ofDirectionManeuverobjects. Configure the navigation view with a title, display mode, and "Done" button. When the button is tapped,isis set toShowing Directions falsewhich closes the popover.ContentView.swiftUse dark colors for code blocks 116 117 118 131 132 133 134 135Add line. Add line. Add line. Add line. Add line. Add line. Add line. Add line. Add line. Add line. Add line. Add line. .popover(isPresented: $isShowingDirections) { NavigationView { List(model.directions, id: \.text) { directionManeuver in Text(directionManeuver.text) } .navigationTitle("Directions") .navigationBarTitleDisplayMode(.inline) .toolbar { ToolbarItem(placement: .confirmationAction) { Button("Done") { isShowingDirections = false } } } } .navigationViewStyle(.stack) .frame(idealWidth: 320, idealHeight: 428) }
Run the solution
Press Command + R to run the app.
If you are using the Xcode simulator your system must meet these minimum requirements: macOS 14 (Sonoma), Xcode 16, iOS 18. If you are using a physical device, then refer to the system requirements.
The map should support two taps to create an origin and destination point and then use the ArcGIS Routing service
Alternatively, you can download the tutorial solution, as follows.
Option 2: Download the solution
-
Click the
Download solutionlink under Solution and unzip the file to a location on your machine. -
Open the
.xcodeprojfile 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
Pass your API Key access token to the ArcGISEnvironment.
-
In the Project Navigator, click MainApp.swift.
-
Set the
AuthenticationtoMode .api.Key MainApp.swiftUse dark colors for code blocks // Change the `AuthenticationMode` to `.apiKey` if your application uses API key authentication. private var authenticationMode: AuthenticationMode { .apiKey } -
Set the
apiproperty with your API key access token.Key MainApp.swiftUse dark colors for code blocks // Please enter an API key access token if your application uses API key authentication. private let apiKey = APIKey("<#YOUR-ACCESS-TOKEN#>")
Best Practice: The access token is stored directly in the code as a convenience for this tutorial. Do not store credentials directly in source code in a production environment.
Run the solution
Press Command + R to run the app.
If you are using the Xcode simulator your system must meet these minimum requirements: macOS 14 (Sonoma), Xcode 16, iOS 18. If you are using a physical device, then refer to the system requirements.
The map should support two taps to create an origin and destination point and then use the ArcGIS Routing service
What's next?
Learn how to use additional API features, ArcGIS location services, and ArcGIS tools in these tutorials: