Device location

Most devices provide information about their location. Each platform has API interfaces on the device that abstract how the location is retrieved, whether through Wi-Fi, cellular networks, or GPS.

Using the map view's location display and a location data source, the device's location can be displayed on top of a map. You can respond to changes in this location to find nearby points of interest, provide navigation instructions, and so on.

Display the location on a map

You can display the current location of the device in a map view by using its location display (LocationDisplay). The map view location display handles getting the current location from the location data source and displaying it on top of the map.

Additional settings for the location display include:

• Automatic panning to keep the latest point location visible
• Change of symbol based on the status of the device's location
• Display of metadata, for example the estimated accuracy of the location
• Set the zoom scale of the map in automatic panning or navigation modes
• Set opacity for the symbols used to show location and accuracy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
    var body: some View {
        MapView(map: map)
        // Adds the location display modifier.
            .locationDisplay(locationDisplay)
            .task {
                do {
                    // Requests location permission if it has not yet been determined.
                    let locationManager = CLLocationManager()
                    if locationManager.authorizationStatus == .notDetermined {
                        locationManager.requestWhenInUseAuthorization()
                    }
                    // Starts the map view's location display.
                    try await locationDisplay.dataSource.start()
                    locationDisplay.autoPanMode = .recenter
                } catch {
                    print("Error starting location display.")
                }
            }
    }

Current location display

By default, the location display uses a blue, round symbol for the current location. Depending on signal strength, satellite positions, and other factors, the accuracy of the reported location can vary. An additional blue circle around the location symbol indicates the estimated range of accuracy for the current location. As locations are read from the configured data source, this outer circle may contract and expand as accuracy increases or decreases.

As the device moves, the map responds to location updates and appropriately updates the location symbol's position.

Location data sources

The dataSource on LocationDisplay is responsible for providing periodic location updates. By default, the dataSource uses the platform's location service (CLLocationManager). To start and stop displaying location, you need to call start() and stop(). Use the autoPanMode property to change how the map behaves when location updates are received. You can also create custom location data sources to process input from other location providers, such as an external GPS receiver. To simulate location updates with a collection of defined points for testing purposes, use a SimulatedLocationDataSource. For information about working with locations from an indoor positioning system (IPS), see the Indoor positioning topic.

Simulate device location updates

You can use a simulated location data source (SimulatedLocationDataSource) to test or demonstrate functionality that requires a set of locations without having to rely on incoming GPS information. This is especially useful for testing functionality that listens for location changes, such as navigating a route. With a simulated location data source, you can define a collection of mock locations to visit in a few ways:

• Vertices along a polyline — The vertices of a provided polyline define locations and the velocity of each is calculated based on its distance from the previous one. The current time is set as the start time for the first location and each subsequent location's time is incremented by one second.
• Points generated along a polyline — Locations are generated using a provided polyline and a velocity. The specified start time is used for the first location and each subsequent location's time is incremented by one second.
• A defined set of points — Locations are defined explicitly.

After the points are defined, enable the simulated location data source to start the iteration of points in the collection. A location change event is raised for each point. Locations are visited in the order that they appear in the collection, allowing you to simulate travel along a path at a defined rate of speed. You can use the index of the location in the array to get the current location or to move to a specific location in the array. This allows you to skip over or to return to previous locations.

The default rate that the locations are iterated in the simulated location data source is one per second. You can change the frequency of location updates by changing the iteration rate. A rate of 2.0, for example, doubles the frequency of location updates and a rate of 0.5 cuts the frequency of updates by half. Note that this does not change the time stamps on the locations, which are always one second apart.

The following example creates a simulated location data source from a route's geometry. The route polyline is densified to add a vertex at 50 meter intervals.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
        guard let densifiedRoute = GeometryEngine.geodeticDensify(route.geometry!, maxSegmentLength: 50.0, lengthUnit: .meters, curveType: .geodesic) as? Polyline else { return }
        // The mock data source to demo the navigation.
        let mockDataSource = SimulatedLocationDataSource(polyline: densifiedRoute)

Autopan modes

The map provides a number of preset enumerations (LocationDisplay.AutoPanMode) that define how the map behaves when location updates are received:

• Off
• Recenter
• Navigation
• Compass navigation

Off mode

In this mode, the map only updates the position of the location symbol on the map. It does not recenter. Therefore, it is possible that the location symbol may move off the screen in response to location updates.

Recenter mode

In this mode, the map attempts to keep the location symbol on-screen by recentering the location symbol when the symbol moves outside a wander extent. Therefore, the location symbol may move freely within the wander extent, but as soon as the symbol exits the wander extent, the map view pans to recenter itself on the symbol.

By default, the wander extent is half the size of the map's viewable extent, but it can be customized. A value of 1 sets a wander extent equal to the size of the map's viewable extent, and the location symbol may move up to the edge of the map before the map recenters. A value of 0 recenters the map with every location update.

If a user pans the map in this mode, the mode automatically changes its Autopan mode to Off, preventing the map from unwanted recentering based on future location updates.

See the wanderExtentFactor on the LocationDisplay.

Navigation mode

This mode is best for in-vehicle navigation. In this mode, the location symbol is pinned to a point on the screen and always points toward the top edge of the device. The map pans and rotates based on location updates and the direction the device is traveling in. Therefore, the location symbol appears stationary, while the map underneath it appears to be moving and rotating.

The position of the location symbol can be adjusted using LocationDisplay.navigationPointHeightFactor. A value of 0 implies the location symbol should be positioned at the bottom edge of the map, and 1 implies the top edge. A value between 0 and 1 positions the symbol somewhere along the centerline from the bottom edge to the top edge. The default value is 0.125.

If a user pans the map in this mode, the mode automatically changes to Off.

Compass Navigation mode

This mode is better when the user is walking. As in Navigation mode, the location symbol is pinned to a point on the screen and always points toward the top edge of the device. However, the map rotates based on the user's bearing relative to magnetic north, and not based on the direction the device travels in, which is the case in Navigation mode. Therefore, the map reflects what lies ahead of the user as the user pivots around their location.

The location symbol position can be adjusted. A value of 0 positions the location symbol at the bottom edge of the map, and 1 at the top edge. A value between 0 and 1 positions the symbol somewhere between the bottom and top edges.

If a user pans the map in this mode, the mode automatically changes to Off.

Customizing the location symbol

The SDK provides default images that are used for the location symbol. These images are included in ArcGIS.bundle.

• The LocationDisplay.png symbol shows the location only.
• The LocationDisplayCourse.png symbol shows the location and direction of travel.
• The LocationDisplayHeading.png symbol shows the location and compass bearing.

Depending on the autopan mode in use, and the type of information provided by the location updates, one of the default images will be used for the location symbol.

In the off, recenter, and navigation modes, the default image is used only when location information is available. The course symbol is used if both location information and course (direction of travel) information are available. In the off and recenter modes, the course symbol is appropriately rotated by an amount specified by the course to display the direction that the device is traveling; however, in Navigation mode, the map rotates instead.

Tutorials

Display device location