Every iOS device has the ability to determine where in the world it is using a framework called Core Location. iOS also includes a framework called Map Kit that lets you easily create a live interactive map showing any locations you like, including of course the user’s location. In this chapter we’ll get you started using both of these frameworks.

Core Location can actually leverage three technologies to do this: GPS, cell ID location, and Wi-Fi Positioning Service (WPS). GPS is the most accurate of the three technologies, but it is not available on first-generation iPhones, iPod touches, or Wi-Fi-only iPads. In short, any device with at least a 3G data connection also contains a GPS unit. GPS reads microwave signals from multiple satellites to determine the current location.

Cell ID location lookup gives a rough approximation of the current location based on the physical location of the cellular base station that the device is currently in contact with. Since each base station can cover a fairly large area, there is a fairly large margin of error here. Cell ID location lookup requires a cell radio connection, so it works only on the iPhone (all models, including the very first) and any iPad with a 3G data connection.

The WPS option uses the MAC addresses from nearby Wi-Fi access points to make a guess at your location by referencing a large database of known service providers and the areas they service. WPS is imprecise and can be off by many miles.

All three methods put a noticeable drain on the battery, so keep that in mind when using Core Location. Your application shouldn’t poll for location any more often than is absolutely necessary. When using Core Location, you have the option of specifying a desired accuracy. By carefully specifying the absolute minimum accuracy level you need, you can prevent unnecessary battery drain.

The technologies that Core Location depends on are hidden from your application. We don’t tell Core Location whether to use GPS, triangulation, or WPS. We just tell it how accurate we would like it to be, and it will decide from the technologies available to it which is best for fulfilling our request.

The Location Manager

The Core Location API is actually fairly easy to use. The main class we’ll work with is CLLocationManager, usually referred to as the location manager. To interact with Core Location, you need to create an instance of the location manager, like this:

CLLocationManager *locationManager = [[CLLocationManager alloc] init];

This creates an instance of the location manager, but it doesn’t actually start polling for your location. You must create an object that conforms to the CLLocationManagerDelegate protocol and assign it as the location manager’s delegate. The location manager will call delegate methods when location information becomes available or changes. The process of determining location may take some time—even a few seconds.

locationManager.delegate = self;
locationManager.desiredAccuracy = kCLLocationAccuracyBest;

locationManager.distanceFilter = 1000;

locationManager.distanceFilter = kCLDistanceFilterNone;

[locationManager startUpdatingLocation];

[locationManager stopUpdatingLocation];

The Location Manager Delegate

The location manager delegate must conform to the CLLocationManagerDelegate protocol, which defines several methods, all of them optional. One of these methods is called by the location manager when it has determined the current location or when it detects a change in location. Another method is called when the location manager encounters an error. We’ll implement both of these in our app.

CLLocationDegrees latitude = theLocation.coordinate.latitude;
CLLocationDegrees longitude = theLocation.coordinate.longitude;

CLLocationDistance altitude = theLocation.altitude;

CLLocationDistance distance = [fromLocation distanceFromLocation:toLocation];

Trying Out Core Location

Let’s build a small application to detect the iPhone’s current location and the total distance traveled while the program has been running. You can see what the first version of our application will look like in Figure 19-3.

In Xcode, create a new project using the Single View Application template and call it WhereAmI. Next, set Device Family to iPhone, select BIDViewController.h, and make the following changes:

#import <UIKit/UIKit.h>
#import <CoreLocation/CoreLocation.h>
 
@interface BIDViewController :
    UIViewController <CLLocationManagerDelegate>
 
@end

First, notice that we’ve included the Core Location header files. Core Location is not part of either UIKit or Foundation, so we need to include the header files manually. Next, we conform this class to the CLLocationManagerDelegate method, so that we can receive location information from the location manager.

Now select BIDViewController.m and add these property declarations to the class extension near the top of the file:

#import "BIDViewController.h"
 
@interface BIDViewController ()
 
@property (strong, nonatomic) CLLocationManager *locationManager;
@property (strong, nonatomic) CLLocation *previousPoint;
@property (assign, nonatomic) CLLocationDistance totalMovementDistance;
@property (weak, nonatomic) IBOutlet UILabel *latitudeLabel;
@property (weak, nonatomic) IBOutlet UILabel *longitudeLabel;
@property (weak, nonatomic) IBOutlet UILabel *horizontalAccuracyLabel;
@property (weak, nonatomic) IBOutlet UILabel *altitudeLabel;
@property (weak, nonatomic) IBOutlet UILabel *verticalAccuracyLabel;
@property (weak, nonatomic) IBOutlet UILabel *distanceTraveledLabel;
 
@end

First, we declare a CLLocationManager pointer, which will be used to hold a pointer to the instance of the Core Location Manager we’re going create. We also declare a pointer to a CLLocation, which we will set to the location of the last update we received from the location manager. This way, each time the user moves far enough to trigger update, we’ll be able to add the latest movement distance to our running total.

The remaining properties are all outlets that will be used to update labels on the user interface.

Select Main.storyboard to create the GUI. Using Figure 19-3 as your guide, drag 12 Labels from the library to the View window. Six of them should be placed on the left side of the screen, right-justified, and made bold. Give the six bold labels the values Latitude:, Longitude:, Horizontal Accuracy:, Altitude:, Vertical Accuracy:, and Distance Traveled:. Since the Horizontal Accuracy: label is the longest, you might place that one first, and then Option-drag copies of that label to create the other five left-side labels. The six right-side labels should be left-justified and placed next to each of the bold labels.

Each of the labels on the right side should be connected to the appropriate outlet we defined in the header file earlier. Once you have all six attached to outlets, double-click each one in turn, and delete the text it holds. Save your changes.

Next, select BIDViewController.m and insert the following lines in viewDidLoad to configure the location manager:

- (void)viewDidLoad
{
    [super viewDidLoad];
    // Do any additional setup after loading the view, typically from a nib.
    self.locationManager = [[CLLocationManager alloc] init];
    self.locationManager.delegate = self;
    self.locationManager.desiredAccuracy = kCLLocationAccuracyBest;
    [self.locationManager startUpdatingLocation];
}

In the viewDidLoad method, we allocate and initialize a CLLocationManager instance, assign our controller class as the delegate, set the desired accuracy to the best available, and then tell our location manager instance to start giving us location updates.

Now insert the following new delegate methods at the end of the @implementation block to handle information received from the location manager:

#pragma mark - CLLocationManagerDelegate Methods
- (void)locationManager:(CLLocationManager *)manager
     didUpdateLocations:(NSArray *)locations {
    CLLocation *newLocation = [locations lastObject];
    NSString *latitudeString = [NSString stringWithFormat:@"%gu00B0",
                                newLocation.coordinate.latitude];
    self.latitudeLabel.text = latitudeString;
     
    NSString *longitudeString = [NSString stringWithFormat:@"%gu00B0",
                                 newLocation.coordinate.longitude];
    self.longitudeLabel.text = longitudeString;
     
    NSString *horizontalAccuracyString = [NSString stringWithFormat:@"%gm",
                                          newLocation.horizontalAccuracy];
    self.horizontalAccuracyLabel.text = horizontalAccuracyString;
     
    NSString *altitudeString = [NSString stringWithFormat:@"%gm",
                                newLocation.altitude];
    self.altitudeLabel.text = altitudeString;
     
    NSString *verticalAccuracyString = [NSString stringWithFormat:@"%gm",
                                        newLocation.verticalAccuracy];
    self.verticalAccuracyLabel.text = verticalAccuracyString;
     
    if (newLocation.verticalAccuracy < 0 ||
        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 (self.previousPoint == nil) {
        self.totalMovementDistance = 0;
    } else {
        self.totalMovementDistance += [newLocation
                                  distanceFromLocation:self.previousPoint];
    }
    self.previousPoint = newLocation;
     
    NSString *distanceString = [NSString stringWithFormat:@"%gm",
                                self.totalMovementDistance];
    self.distanceTraveledLabel.text = distanceString;
     
}
 
- (void)locationManager:(CLLocationManager *)manager
       didFailWithError:(NSError *)error {
    NSString *errorType = (error.code == kCLErrorDenied) ?
    @"Access Denied" : @"Unknown Error";
    UIAlertView *alert = [[UIAlertView alloc]
                          initWithTitle:@"Error getting Location"
                          message:errorType
                          delegate:nil
                          cancelButtonTitle:@"Okay"
                          otherButtonTitles:nil];
    [alert show];
}

NSString *latitudeString = [NSString stringWithFormat:@"%gu00B0",
                            newLocation.coordinate.latitude];
self.latitudeLabel.text = latitudeString;
 
NSString *longitudeString = [NSString stringWithFormat:@"%gu00B0",
                             newLocation.coordinate.longitude];
self.longitudeLabel.text = longitudeString;
 
NSString *horizontalAccuracyString = [NSString stringWithFormat:@"%gm",
                                      newLocation.horizontalAccuracy];
self.horizontalAccuracyLabel.text = horizontalAccuracyString;
 
NSString *altitudeString = [NSString stringWithFormat:@"%gm",
                            newLocation.altitude];
self.altitudeLabel.text = altitudeString;
 
NSString *verticalAccuracyString = [NSString stringWithFormat:@"%gm",
                                    newLocation.verticalAccuracy];
self.verticalAccuracyLabel.text = verticalAccuracyString;

if (newLocation.verticalAccuracy < 0 ||
    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 (self.previousPoint == nil) {
    self.totalMovementDistance = 0;
} else {
    self.totalMovementDistance += [newLocation
                              distanceFromLocation:self.previousPoint];
}
self.previousPoint = newLocation;

NSString *distanceString = [NSString stringWithFormat:@"%gm",
                            self.totalMovementDistance];
self.distanceTraveledLabel.text = distanceString;

Visualizing your Movement on a Map

What we’ve done so far is pretty neat, 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 one primary view class representing a map display, and it 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.

Start off by selecting BIDViewController.h in Xcode. Add the following near the top to import the mapping framework headers:

#import <UIKit/UIKit.h>
#import <CoreLocation/CoreLocation.h>
#import <MapKit/MapKit.h>

Next, switch to BIDViewController.m and add a new property declaration below the others in the class extension:

@property (weak, nonatomic) IBOutlet MKMapView *mapView;

Now select Main.storyboard to edit the view. We’d like to keep all of our labels as they are, but we need to make them pop out from the backdrop of the map view in some way. A semitransparent box in the form of a UIView will do nicely. So, select all the labels, and then choose Editor Embed In View from the menu.

Make sure the new view is selected, and then use the attributes inspector to disable the User Interaction Enabled checkbox (so that touching anything in this view will be ignored, passing all touch events to the map view instead) and to set its background color to something partly transparent. Drag the view to the bottom of its superview. Now we need to create some constraints so that this box will keep both its position at the bottom and its vertical size, no matter how the screen size changes. So, click the Pin button at the bottom of the editor area to bring up the constraint creation panel. In the upper section of this panel, click the checkboxes to the left, right, and bottom of the small square. In the middle part, click the Height checkbox. When you find yourself looking at something like Figure 19-4, click the Add 4 Constraints button at the bottom:

Now find an MKMapView in the object library and drag it into your main view. Use the resize handles to make it fill the entire view, and then select Editor Arrange Send to Back to make it appear behind the pre-existing labels. Hook up the map view by control-dragging from the View Controller to the map view and selecting the mapView outlet. Create constraints for the map view using the Pin panel again, this time clicking all four checkboxes surrounding the small box in the upper portion before clicking the Add 4 Constraints button.

Now that these preliminaries are in place, it’s time to write a little code that will make this map do some work for us. Before dealing with the 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 architecture, and 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.

Make a new Objective-C class in Xcode by subclassing from NSObject and naming it BIDPlace. Select BIDPlace.h and modify it as shown here. You need to import the Map Kit header, specify a protocol the new class conforms to, and add some properties:

#import <Foundation/Foundation.h>
#import <MapKit/MapKit.h>
 
 
@interface BIDPlace : NSObject<MKAnnotation>
 
@property (copy, nonatomic) NSString *title;
@property (copy, nonatomic) NSString *subtitle;
@property (assign, nonatomic) CLLocationCoordinate2D coordinate;
 
@end

This is a fairly “dumb” class that acts solely as a holder for these properties. We don’t even need to touch the .m file here! 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 framework lets you add this capability to any class of your own without messing up any existing class hierarchies.

Select BIDViewController.m and get started by importing the header for the new class:

#import "BIDPlace.h"

Now find the viewDidLoad method and add this line to the end of it:

self.mapView.showsUserLocation = YES;

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

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 BIDPlace 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 a new MKCoordinateRegion, a special 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 (self.previousPoint == nil) {
    self.totalMovementDistance = 0;
 
    BIDPlace *start = [[BIDPlace alloc] init];
    start.coordinate = newLocation.coordinate;
    start.title = @"Start Point";
    start.subtitle = @"This is where we started!";
     
    [self.mapView addAnnotation:start];
    MKCoordinateRegion region;
    region = MKCoordinateRegionMakeWithDistance(newLocation.coordinate,
                                                100, 100);
    [self.mapView setRegion:region animated:YES];
} else {
    self.totalMovementDistance += [newLocation
                              distanceFromLocation:self.previousPoint];
}
self.previousPoint = newLocation;

So now we’ve told the map view that we have an annotation (i.e., a visible place-marker) 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 info when touched. Neat!

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!

Wherever You Go, There You Are

You’ve now seen pretty much all there is to Core Location. You’ve also seen the basic operation of Map Kit, as well. Although the underlying technologies are quite complex, Apple has provided simple interfaces that hide most of the complexity, making it quite easy to add location-related and mapping features to your applications so you can tell where the users are, notice when they move, and mark their location (and any other locations) on a map.

And speaking of moving, when you’re ready proceed directly to the next chapter, so we can play with the iPhone’s built-in accelerometer.