Setting the Desired Accuracy

After you set the delegate, you also want to set the desired accuracy. As mentioned, don’t specify a degree of accuracy any greater than you absolutely need. If you’re writing an application that just needs to know which state or country the phone is in, don’t specify a high level of precision. Remember that the more accuracy you demand of Core Location, the more power you’re likely to use. Also, keep in mind that there is no guarantee that you will get the level of accuracy you have requested. Listing 19-1 shows an example of setting the delegate and requesting a specific accuracy.

Listing 19-1. Setting the Delegate and Desired Accuracy

locationManager.delegate = self
locationManager.desiredAccuracy = kCLLocationAccuracyBest

The accuracy is set using a CLLocationAccuracy value, a type that’s defined as a Double. The value is in meters, so if you specify a desiredAccuracy of 10, you’re telling Core Location that you want it to try to determine the current location within 10 meters, if possible. Specifying kCLLocationAccuracyBest (as we did previously) or specifying kCLLocationAccuracyBestForNavigation (where it uses other sensor data as well) tells Core Location to use the most accurate method that’s currently available. In addition, you can also use: kCLLocationAccuracyNearestTenMeters, kCLLocationAccuracyHundredMeters, kCLLocationAccuracy Kilometer, and kCLLocationAccuracyThreeKilometers.

Setting the Distance Filter

By default, the location manager will notify the delegate of any detected change in the device’s location. By specifying a distance filter, you are telling the location manager not to notify you of every change, but instead to notify you only when the location changes by more than a certain amount. Setting up a distance filter can reduce the amount of polling your application does. Distance filters are also set in meters. Specifying a distance filter of 1000 tells the location manager not to notify its delegate until the iPhone has moved at least 1,000 meters from its previously reported position as in  locationManager.distanceFilter = 1000.

If you ever want to return the location manager to the default setting, which applies no filter, you can use the constant kCLDistanceFilterNone, like this:

locationManager.distanceFilter = kCLDistanceFilterNone.

Just as when specifying the desired accuracy, you should take care to avoid getting updates any more frequently than you really need them; otherwise, you waste battery power. A speedometer app that’s calculating the user’s velocity based on location changes will probably want to have updates as quickly as possible, but an app that’s going to show the nearest fast-food restaurant can get by with a lot fewer updates.

Getting Permission to Use Location Services

Before your application can use location services, you need to get the user’s permission to do so. Core Location offers several different services, some of which can be used when your application is in the background—in fact, you can even request to have your application launched when certain events happen while it is not running. Depending on your application’s functionality, it may be enough to request permission to access location services only while the user is using your application, or it might need to always be able to use the service. When writing an application, you need to decide which type of permission you require and make the request before initiating the services that you need. You’ll see how to do this in the course of creating the example application for this chapter.

Starting the Location Manager

When you’re ready to start polling for location, and after you request from the user to access location services, you tell the location manager to start. It will go off and do its thing, and then call a delegate method when it has determined the current location. Until you tell it to stop, it will continue to call your delegate method whenever it senses a change that exceeds the current distance filter. Here’s how you start the location manager:

locationManager.startUpdatingLocation()                                                  

Using the Location Manager Wisely

If you need to determine the current location only and you don’t need continuous updates, you can use the requestLocation() method instead of startUpdatingLocation().This method automatically stops location polling as soon as the user’s position has been determined. On the other hand, if you need to poll, make sure you stop polling as soon as you possibly can. Remember that as long as you are getting updates from the location manager, you are putting a strain on the user’s battery. To tell the location manager to stop sending updates to its delegate, call stopUpdatingLocation(),like this:

locationManager.stopUpdatingLocation()

It’s not necessary to call this method if you use requestLocation() instead of startUpdatingLocation().

Getting Location Updates

When the location manager wants to inform its delegate of the current location, it calls the locationManager(_:didUpdateLocations:) method. This method takes two parameters :

• The first parameter references the location manager that called the method.

• The second parameter contains an array of CLLocation objects representing the current location of the device and perhaps a few previous locations. If several location updates occur in a short period of time, they may be reported all at once with a single call to this method. In any case, the most recent location is always the last item in this array.

Getting Latitude and Longitude Using CLLocation

Location information gets passed from the location manager using instances of the CLLocation class. This class provides seven properties that might be of interest to your application:

• coordinate

• horizontalAccuracy

• altitude

• verticalAccuracy

• floor

• timestamp

• description

The latitude and longitude are stored in a property called coordinate. To get the latitude and longitude in degrees, use the code in Listing 19-2.

Listing 19-2. Getting Latitude and Longitude

let latitude = theLocation.coordinate.latitude
let longitude = theLocation.coordinate.longitude

The latitude and longitude variables will be inferred to be of type CLLocationDegrees. The CLLocation object can also tell you how confident the location manager is in its latitude and longitude calculations. The horizontalAccuracy property describes the radius of a circle (in meters, like all Core Location measurements) with the coordinate as its center. The larger the value in horizontalAccuracy, the less certain Core Location is of the location. A very small radius indicates a high level of confidence in the determined location.

You can see a graphic representation of horizontalAccuracy in the Maps application, as shown in Figure 19-1. The circle shown in Maps uses horizontalAccuracy for its radius when it detects your location. The location manager thinks you are at the center of that circle. If you’re not, you’re almost certainly somewhere inside the circle. A negative value in horizontalAccuracy is an indication that you cannot rely on the values in coordinate for some reason.

Figure 19-1. The Maps application uses Core Location to determine your current position. The outer circle is a visual representation of the horizontal accuracy.

The CLLocation object also has a property called altitude, of type CLLocationDistance, that tells you how many meters above (or below) sea level you are:

let altitude = theLocation.altitude

Each CLLocation object maintains a property called verticalAccuracy that is an indication of how confident Core Location is in its determination of altitude. The value in altitude could be off by as many meters as the value in verticalAccuracy. If the verticalAccuracy value is negative, Core Location is telling you it could not determine a valid altitude.

The floor property gives the floor within the building in which the user is located. This value is only valid in buildings that are able to provide the information, so you should not rely on its availability.

CLLocation objects include a timestamp that tells when the location manager made the location determination.

In addition to these properties, CLLocation has a useful instance method that will let you determine the distance between two CLLocation objects. The method is called distanceFromLocation() and it returns a value of type CLLocationDistance, which is just a Double, so you can use it in arithmetic calculations, as you’ll see in the application we’re about to create. Here’s how you use this method:

let distance = fromLocation.distanceFromLocation(toLocation)

The preceding line of code returns the distance between two CLLocation objects: fromLocation and toLocation. This distance value returned contains the result of a great-circle distance calculation that ignores the altitude property and calculates the distance as if both points were at sea level. For most purposes, a great-circle calculation provides more than sufficient information; however, if you do want to take altitude into account when calculating distances, you’ll need to write your own code to do it.

Error Notifications

If Core Location needs to report an error to your application, it will call a delegate method named locationManager(_:didFailWithError:). One possible cause of an error is that the user denied access to location services, in which case the method will be called with the error code CLError.Denied. Another commonly encountered error code supported by the location manager is CLError.LocationUnknown, which indicates that Core Location was unable to determine the location but that it will keep trying. While a CLError.LocationUnknown error indicates a problem that may be temporary, CLError.Denied and other errors may indicate that your application will not be able to access Core Location any time during the remainder of the current session.

Using Location Manager Updates

Now that we’ve dealt with getting permission to use the user’s location, let’s do something with that information. Insert this implementation (see Listing 19-3), of the delegate’s locationManager(_:didUpdateLocations:) method in ViewController.swift.

Listing 19-3. Our didUpateLocations Location Manager Delegate Method

    func locationManager(_ manager: CLLocationManager, didUpdateLocations
                            locations: [CLLocation]) {
        if let newLocation = locations.last {
            let latitudeString = String(format: "%gu{00B0}",
                            newLocation.coordinate.latitude)
            latitudeLabel.text = latitudeString

            let longitudeString = String(format: "%gu{00B0}",
                            newLocation.coordinate.longitude)
            longitudeLabel.text = longitudeString

            let horizontalAccuracyString = String(format:"%gm",
                            newLocation.horizontalAccuracy)
            horizontalAccuracyLabel.text = horizontalAccuracyString

            let altitudeString = String(format:"%gm", newLocation.altitude)
            altitudeLabel.text = altitudeString

            let verticalAccuracyString = String(format:"%gm",
                            newLocation.verticalAccuracy)
            verticalAccuracyLabel.text = verticalAccuracyString

            if newLocation.horizontalAccuracy < 0 {
                // invalid accuracy
                return
            }

            if newLocation.horizontalAccuracy > 100 ||
                    newLocation.verticalAccuracy > 50 {
                // accuracy radius is so large, we don't want to use it
                return
            }

            if previousPoint == nil {
                totalMovementDistance = 0
            } else {
                print("movement distance: " +
                    "(newLocation.distance(from: previousPoint!))")
                totalMovementDistance +=
                    newLocation.distance(from: previousPoint!)
            }
            previousPoint = newLocation

            let distanceString = String(format:"%gm", totalMovementDistance)
            distanceTraveledLabel.text = distanceString                              
        }
    }

The first thing we do in the delegate method is to update the first five labels in the second column of Figure 19-3 with values from the CLLocation objects passed in the locations argument. The array could contain more than one location update, but we always use the last entry, which represents the most recent information.

Next, we check the accuracy of the values that the location manager gives us. High accuracy values indicate that the location manager isn’t quite sure about the location, while negative accuracy values indicate that the location is actually invalid. Some devices do not have the hardware required to determine vertical position. On these devices, and on the simulator, the verticalAccuracy property will always be –1, so we don’t exclude position reports that have this value. The accuracy values are in meters and indicate the radius of a circle from the location we’re given, meaning that the true location could be anywhere in that circle. Our code checks to see whether these values are acceptably accurate; if not, it simply returns from this method rather than doing anything more with garbage data:

            if newLocation.horizontalAccuracy < 0 {
                // invalid accuracy
                return
            }

            if newLocation.horizontalAccuracy > 100 ||
                    newLocation.verticalAccuracy > 50 {
                // accuracy radius is so large, we don't want to use it
                return
            }

Next, we check whether previousPoint is nil. If it is, then this update is the first valid one we’ve gotten from the location manager, so we zero out the distanceFromStart property. Otherwise, we add the latest location’s distance from the previous point to the total distance. In either case, we update previousPoint to contain the current location:

            if previousPoint == nil {
                totalMovementDistance = 0
            } else {
                print("movement distance: " +
                    "(newLocation.distance(from: previousPoint!))")
                totalMovementDistance +=
                    newLocation.distance(from: previousPoint!)
            }
            previousPoint = newLocation

After that, we populate the final label with the total distance that we’ve traveled from the start point. While this application runs, if the user moves far enough for the location manager to detect the change, the Distance Traveled: field will be continually updated with the distance the user has moved since the application started:

  let distanceString = String(format:"%gm", totalMovementDistance)
  distanceTraveledLabel.text = distanceString

And there you have it. Core Location is fairly straightforward and easy to use. Compile and run the application, and then try it. If you have the ability to run the application on your iPhone or iPad, try going for a drive, having someone else doing the driving, with the application running and watch the values change as you move around.

Visualizing Your Movement on a Map

What we’ve done so far is pretty interesting, but wouldn’t it be nice if we could visualize our travel on a map? Fortunately, iOS includes the Map Kit framework to help us out here. Map Kit utilizes the same back-end services that Apple’s Maps app uses, which means it’s fairly robust and improving all the time. It contains a view class that presents a map, which responds to user gestures just as you’d expect of any modern mapping app. This view also lets us insert annotations for any locations we want to show up on our map, which by default show up as “pins” that can be touched to reveal some more info. We’re going to extend our WhereAmI app to display the user’s starting position and current position on a map.

Select ViewController.swift and add the following line to import the Map Kit framework :

import UIKit
import CoreLocation
import MapKit                

Now add a new property declaration for the Map View that will display the user’s location:

Now select Main.storyboard to edit the view. Drag a Map View from the object library and drop it onto the top half of the user interface. Resize the Map View so that it covers the whole screen, including the view that we added earlier and all of its labels, and then choose Editor ➤ Arrange ➤ Send to Back to move the Map View behind the other view.

In the Document Outline, Control-drag from the Map View to its parent view and, in the context menu, hold down the Shift key and select Leading Space to Container Margin, Trailing Space to Container Margin, Vertical Spacing to Top Layout Guide, and Vertical Spacing to Bottom Layout Guide, and then press the Return key.

The Map View is now locked in place, but the bottom part of it is obscured. We can fix that by making the view at the bottom partly transparent. To do that, select it in the Document Outline, open the Attributes Inspector, click the Background color editor, and, in the pop-up that appears, choose Other… to open a color chooser. Select a white background and move the Opacity slider to about 70%. Finally, Control-drag from the view controller icon in the Document Outline to the Map View and select mapView in the pop-up that appears to connect the map to its outlet.

Now that these preliminaries are in place, it’s time to write a little code that will make the map do some work for us. Before dealing with the code required in the view controller, we need to set up a sort of model class to represent our starting point. MKMapView is built as the View part of an MVC (Model-View-Controller) architecture. It works best if we have distinct classes to represent markers on the map. We can pass model objects off to the map view and it will query them for coordinates, a title, and so on, using a protocol defined in the Map Kit framework.

Press ⌘N to bring up the new file assistant, and in the iOS Source section, choose Cocoa Touch Class. Name the class Place and make it a subclass of NSObject. Open Place.swift and modify it as shown next. You need to import the Map Kit framework, specify a protocol that the new class conforms to, and specify the properties as shown in Listing 19-4.

Listing 19-4. Our New Place Class in the Place.swift File

import UIKit
import MapKit

class Place: NSObject, MKAnnotation {
    let title: String?
    let subtitle: String?
    var coordinate: CLLocationCoordinate2D

    init(title:String, subtitle:String, coordinate:CLLocationCoordinate2D) {
        self.title = title
        self.subtitle = subtitle
        self.coordinate = coordinate
    }
}

This is a fairly “dumb” class that acts solely as a holder for these properties. In a real-world example, you may have real model classes that need to be shown on a map as an annotation, and the MKAnnotation protocol lets you add this capability to any class of your own without messing up any existing class hierarchies. Select ViewController.swift and add the two bold lines to the locationManager(_:didChangeAuthorizationStatus:) method:

    func locationManager(_ manager: CLLocationManager,
                    didChangeAuthorization status: CLAuthorizationStatus) {
        print("Authorization status changed to (status.rawValue)")
        switch status {
        case .authorizedAlways, .authorizedWhenInUse:
            locationManager.startUpdatingLocation()
            mapView.showsUserLocation = true              

        default:
            locationManager.stopUpdatingLocation()
            mapView.showsUserLocation = false              
        }
    }

The Map View’s showsUserLocation property does just what you probably imagine: it saves us the hassle of manually moving a marker around as the user moves by automatically drawing one for us. It uses Core Location to get the user’s location and it works only if your application is authorized for that; so we enable the property when we are told that we have permission to use Core Location and then disable it again if we lose permission.

Now let’s revisit the locationManager(_:didUpdateLocations:) method . We’ve already got some code in there that notices the first valid location data we receive and establishes our start point. We’re also going to allocate a new instance of our Place class. We set its properties, giving it a location. We also add a title and subtitle that we want to appear when a marker for this location is displayed. Finally, we pass this object off to the map view. We also create an instance of MKCoordinateRegion, a struct included in Map Kit that lets us tell the view which section of the map we want it to display. MKCoordinateRegion uses our new location’s coordinates and a pair of distances in meters (100, 100) that specify how wide and tall the displayed map portion should be. We pass this off to the map view as well, telling it to animate the change. All of this is done by adding the bold lines shown here:

if previousPoint == nil {                
   totalMovementDistance = 0            
   let start = Place(title:"Start Point",            
             subtitle:"This is where we started",            
             coordinate:newLocation.coordinate)            
   mapView.addAnnotation(start)            
   let region = MKCoordinateRegionMakeWithDistance(newLocation.coordinate,            
                   100, 100)            
    mapView.setRegion(region, animated: true)            
    } else {            
         print("movement distance: " +            
          "(newLocation.distance(from: previousPoint!))")            
         totalMovementDistance +=            
         newLocation.distance(from: previousPoint!)            
}                

So now we’ve told the map view that we have an annotation (i.e., a visible placemark) that we want the user to see. But how should it be displayed? Well, the map view figures out what sort of view to display for each annotation by asking its delegate. In a more complex app, that would work for us. But in this example we haven’t made ourselves a delegate, simply because it’s not necessary for our simple use case. Unlike UITableView, which requires its data source to supply cells for display, MKMapView has a different strategy: if it’s not provided with annotation views by a delegate, it simply displays a default sort of view represented by a red “pin” on the map that reveals some more information when touched.

There’s one final thing you need to do—enable your application to use Map Kit. To do this, select the project in the Project Navigator and then select the WhereAmI target. At the top of editor area, select Capabilities, locate the Maps section, and move the selector switch on the right from OFF to ON. Now build and run your app, and you’ll see the map view load. As soon as it gets valid position data, you’ll see it scroll to the right location, drop a pin at your starting point, and mark your current location with a glowing blue dot (see Figure 19-5). Not bad for a few dozen lines of code.

Figure 19-5. The red pin marks our starting location, and the blue dot shows how far we’ve gotten—in this case, no distance at all

Changing Location Service Permissions

When your application runs for the first time, you hope the user will give it permission to use location services. Whether you get permission or not, you can’t assume that nothing changes. The user can grant or revoke location permission via the Settings app. You can test this on the simulator. Launch the app and grant yourself permission to use Core Location (if you’ve previously denied permission, you’ll need to remove and reinstall the app first). You should see your location on the map. Now go to the Settings app and choose Privacy ➤ Location Services. At the top of the screen is a switch that turns location services on or off. Turn the switch to OFF and go back to your application. You’ll see that the map no longer shows your position. That’s because the location manager called the locationManager(_:didChangeAuthorizationStatus:) method with authorization code CLAuthorizationStatus.denied, in response to which the application stops receiving position updates and tells Map Kit to stop tracking the user’s position. Now go back to the Settings app, re-enable Core Location in Locations Services, and come back to your application; you’ll find that it’s tracking your position again.

Switching Location Services off is not the only way for the user to change your app’s ability to use Core Location. Go back to the Settings app. Below the switch that enables Location Services, you’ll see a list of all the apps that are using it, including WhereAmI, as shown on the left in Figure 19-6. Clicking the application name takes you to another page where you can allow or deny access to your application, which you can see on the right in Figure 19-6. At the moment, the application can use location services while the user is using the app. If you click Never, that permission is revoked, as you can prove by returning to the application again. This demonstrates that it’s important to code the application so that it can detect and respond properly to changes in its authorization status.

Figure 19-6. Changing Core Location access permission for the WhereAmI app