In Part 1 of this series, I will introduce you to the very basics of CoreLocation services and getting the location of the device currently being used.

About CoreLocation

The CoreLocation framework provides your app with the ability to get a device’s current location, provided the user of the device has granted your app access to that information.

Location services are provided in two major ways using this framework:

1. Standard Location Services- This service provides the most accurate location information using a variety of methods including celluar, wifi, and GPS.
   • Most accurate.
   • Consumes the most power and can take a longer time to acquire.
   • Can only be used when your application is in the foreground.
2. Significant Change Location Services- This service uses cellular data to determine a general idea of where the device is located.
   • Fastest and uses the least amount of power to determine the location.
   • Can also be used to notify your app when a significant change in the location has occurred even if your app is not in focus.

Project Files:

You can download the project files at this github repository: http://github.com/shawngrimes/Location-and-Map-Sample

Adding Location Frameworks

The first step to adding location services to your project is to add the CoreLocation framework.

1. Select your target and go to the “Build Phases” tab.
2. Click the “+” button under “Link Binary With Libraries”
3. Select the CoreLocation framework and click “Add”

Location Manager

With location services, you create an instance of CLLocationManager. There is usually one instance of this per app so I feel a good place for this is in the App Delegate and then each view can access the current location from the App Delegate.

To start, open your App Delegate header file:

1. Add #import <CoreLocation/CoreLocation.h> to the top
2. Specify that your app delegate complies with the Core Location Delegate protocol by changing your @interface line with @interface CFAAppDelegate : UIResponder <UIApplicationDelegate, CLLocationManagerDelegate>
3. Specify a CLLocationManager property by adding @property (strong, nonatomic) CLLocationManager *locationManager right before the @end statement.

Your App Delegate header file should now look similar to the following:

#import <UIKit/UIKit.h>
 
//Add Location Framework
#import <CoreLocation/CoreLocation.h>
 
//Specify this app delegate complies with the location manager delegate
@interface CFAAppDelegate : UIResponder <UIApplicationDelegate, CLLocationManagerDelegate>
 
@property (strong, nonatomic) UIWindow *window;
 
//Add a location manager property to this app delegate
@property (strong, nonatomic) CLLocationManager *locationManager;
 
@end

Creating The Location Manager Object

Switch over to the App Delegate implementation file (.m), and we are going to create our location manager object. The first thing we should do, since we created it as a property of our app delegate, is synthesize the property so add @synthesize locationManager=_locationManager; under the line that reads @synthesize window = _window;.

#import "CFAAppDelegate.h"
 
@implementation CFAAppDelegate
 
@synthesize window = _window;
@synthesize locationManager=_locationManager;

Now that our property is synthesized, we can create the object. I usually create it in the method application didFinishLaunchingWithOptions:. A Location Manager object is created similar to any other object but there are three important properties you should set after you have alloc’d/init’d.

1. .purpose – The purpose property is displayed to the user of your app when they are prompted to allow your app to use their location. It gives you a chance to explain what your app is going to do with their location information.
2. .desiredAccuracy – The desired accuracy property allows you to tell the device how accurate you would like the location information to be. This should be set based on your application’s needs. Don’t set this property to kCLLocationAccuracyBest if you only need to know what city they are in. NOTE: This is the “desired” accuracy, it is not guaranteed. The device will determine the best available information and provide it to you but you are not, however, guaranteed any level of accuracy.
3. .distanceFilter – The distance filter property tells the location manager how far a device needs to move (horizontally vs. an altitude change) before triggering a new location event. It is measured in meters. You can set the property to kCLDistanceFilterNone to be notified of all events (this is also the default value).

The completed creation of our location manage looks like this:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    self.window = [[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]];
    // Override point for customization after application launch.
    self.window.backgroundColor = [UIColor whiteColor];
    [self.window makeKeyAndVisible];
 
    if(self.locationManager==nil){
        _locationManager=[[CLLocationManager alloc] init];
        //I'm using ARC with this project so no need to release
 
        _locationManager.delegate=self;
        _locationManager.purpose = @"We will try to tell you where you are if you get lost";
        _locationManager.desiredAccuracy=kCLLocationAccuracyBest;
        _locationManager.distanceFilter=500;
        self.locationManager=_locationManager;
    }
 
    return YES;
}

If you run this now, you should not notice any change in the way your application runs, you also won’t start receiving location information just yet. That comes next…

Starting Location Services

Now that we have our location manager configured, we want to start getting the location. To start the standard location service, you should first check to make sure that location services are enabled. This is done with a simple call to [CLLocationManager locationServicesEnabled] so after we set up our location manager above and before the return YES;, add the following code:

    if([CLLocationManager locationServicesEnabled]){
        [self.locationManager startUpdatingLocation];
    }

NOTE: If location services are not enabled and you start updating location services, the user will be prompted to enable location services. This could be annoying to the end user if they have to answer “No” every time your app launches.

If you run your app now, you will notice that the user is prompted to enable location services (and it will include the message from the .prompt property of our location manager object).

Receiving Location Changes

We’ve started location services, but now we need to start receiving updates to location changes. This is all done through the CLLocationManagerDelegate protocol. There are a number of available methods to implement for this delegate but the three most important are probably:

1. – locationManager:didUpdateToLocation:fromLocation:
2. – locationManager:didFailWithError:
3. – locationManager:didChangeAuthorizationStatus:

– locationManager:didUpdateToLocation:fromLocation:

Let’s start with receiving an update in location and how to handle that. In our App Delegate implementation file (.m), add the following method placeholder below the @synthesize … statements and above - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions method:

-(void)locationManager:(CLLocationManager *)manager didUpdateToLocation:(CLLocation *)newLocation fromLocation:(CLLocation *)oldLocation{
 
}

One of the first things I like to do is check the timestamp of the newLocation detected. When you first start updating location services, the location manager will receive the last known location of the device, this could be hours or days old depending on the last time location services were used. In my apps, I like to make sure that I have a recent location. This following code will only use a location that has been found in the last 15.0 seconds:

    NSDate* eventDate = newLocation.timestamp;
    NSTimeInterval howRecent = [eventDate timeIntervalSinceNow];
    if (abs(howRecent) < 15.0)
    {
        //Location timestamp is within the last 15.0 seconds, let's use it!
    }

The next check that I like to perform is to see how accurate the newLocation is. This can be done by looking at the .horizontalAccuracy property. This property tells you how accurate your location information is. As I stated above, you can request to have very accurate locations but you are not guaranteed it. In the illustration below, the newLocation.coordinate is the location the device thinks it is, but in truth the orange circle of the .horizontalAccuracy says that it could be anywhere in that circle.

Your application’s need will determine how accurate of a location you need. Again, if you just need the city the user is in, you won’t need it to be as accurate as if you were trying to find something within walking distance. In the code below, I have set my accuracy threshold to 35.0 meters. This is pretty broad but I have found that it works well indoors as well as out. Insert the following code right after the comment //Location timestamp is within the last 15.0 seconds, let's use it!

        //Location timestamp is within the last 15.0 seconds, let's use it!
        if(newLocation.horizontalAccuracy<35.0){
            //Location seems pretty accurate, let's use it!
            NSLog(@"latitude %+.6f, longitude %+.6f\n",
                  newLocation.coordinate.latitude,
                  newLocation.coordinate.longitude);
            NSLog(@"Horizontal Accuracy:%f", newLocation.horizontalAccuracy);
 
            //Optional: turn off location services once we've gotten a good location
            [manager stopUpdatingLocation];
        }

The code above will print the new location to the console and then turn off location services. This is an optional step but if you don’t need location services anymore, it’s a smart thing to turn them off to conserve your user’s battery.

This is what our complete delegate method looks like:

-(void)locationManager:(CLLocationManager *)manager didUpdateToLocation:(CLLocation *)newLocation fromLocation:(CLLocation *)oldLocation{
    NSDate* eventDate = newLocation.timestamp;
    NSTimeInterval howRecent = [eventDate timeIntervalSinceNow];
    if (abs(howRecent) < 15.0)
    {
        //Location timestamp is within the last 15.0 seconds, let's use it!
        if(newLocation.horizontalAccuracy<35.0){
            //Location seems pretty accurate, let's use it!
            NSLog(@"latitude %+.6f, longitude %+.6f\n",
                  newLocation.coordinate.latitude,
                  newLocation.coordinate.longitude);
            NSLog(@"Horizontal Accuracy:%f", newLocation.horizontalAccuracy);
 
            //Optional: turn off location services once we've gotten a good location
            [manager stopUpdatingLocation];
        }
    }
}

Now we can run the project again. If you didn’t authorize the app to use location services before, go ahead and do that now. We haven’t done anything with the location at this point except print it out to the console. If you don’t know how to see the console, make sure Xcode is the active window (NOT the simulator) and press ⌘⇧C

If you are running the project on the simulator and not a device, you may not see any results in the console window. This is because the simulator does not have location services turned on by default. You can simulate a location by selecting the location services simulation in the console window:

You can also simulate a location in the Simulator by using the Debug menu.

Once a location has been selected, you may need to restart the app to get the new location to show in the console window:

Because we built the location manager into the App Delegate, you can access the device’s current location anywhere in your code by including the AppDelegate header file (.h) in your view controller’s implementation file (.m):

#import "CFAAppDelegate.h"

Then whenever you need to access the location, you can use the following bit of code:

//Make sure location services are enabled before requesting the location
if([CLLocationManager locationServicesEnabled]){
 
    CFAAppDelegate *appDelegate=(CFAAppDelegate *)[UIApplication sharedApplication].delegate;
    CLLocation *currentLocation=appDelegate.locationManager.location;
 
    //Do what you want with the location...
}

About: Shawn Grimes
Shawn is a mobile app developer for ELC Technologies. He is a co-author of the book, iOS 5 Recipes: A Problem-Solution Approach (Recipes Apress). You can follow him on twitter @shawng. Shawn also works with high school students to teach them app development skills through the APPlied Club Program.

UIKit/UIKit.hp

Apple’s done a great job of abstracting GPS, Cellular Triangulation, and Wifi Access Point location lookups into CoreLocation; making it extremely easy to determine the approximate location of your user regardless of their device and network connectivity. Additionally, Apple’s new iPhone Simulator finally supports CoreLocation as well. This significantly eases the process of testing your location code.

The first thing you’ll need to do is add the CoreLocation framework to your project. This is pretty straightforward. Command-Click on ‘Frameworks’ -> Add -> Existing Frameworks

Select ‘CoreLocation.framework’ and click ‘add’.

The class below implements the LocationManager delegate methods required to get the user’s location. You can just as easily implement the LocationManagerDelegate protocol in your AppDelegate or elsewhere in your App. Though I’ve found that having this class makes it super easy to drop in location support into new projects instead of having to cut/paste delegate methods (ugly). Anyway. Take a look:

//
//  LocationGetter.h
//  CoreLocationExample
//
//  Created by Matt on 9/3/10.
//  Copyright 2009 iCodeBlog. All rights reserved.
//
 
#import <uikit/UIKit.h>
#import <coreLocation/CoreLocation.h>
 
@protocol LocationGetterDelegate
@required
- (void) newPhysicalLocation:(CLLocation *)location;
@end
 
@interface LocationGetter : NSObject  {
    CLLocationManager *locationManager;
    id delegate;
}
 
- (void)startUpdates;
 
@property (nonatomic, retain) CLLocationManager *locationManager;
@property(nonatomic , retain) id delegate;
@end

Notice that we’re defining our own protocol with a method that takes the new CLLocation as a parameter. We’ll be implementing that delegate method in a minute. Now for the class

//  LocationGetter.m
//  CoreLocationExample
//
//  Created by Matt on 9/3/10.
//  Copyright 2009 iCodeBlog. All rights reserved.
//
 
#import "LocationGetter.h"
#import <coreLocation/CoreLocation.h>
 
@implementation LocationGetter
 
@synthesize locationManager, delegate;
BOOL didUpdate = NO;
 
- (void)startUpdates
{
    NSLog(@"Starting Location Updates");
 
    if (locationManager == nil)
        locationManager = [[CLLocationManager alloc] init];
 
    locationManager.delegate = self;
 
    // locationManager.distanceFilter = 1000;  // update is triggered after device travels this far (meters)
 
    // Alternatively you can use kCLLocationAccuracyHundredMeters or kCLLocationAccuracyHundredMeters, though higher accuracy takes longer to resolve
    locationManager.desiredAccuracy = kCLLocationAccuracyKilometer;
    [locationManager startUpdatingLocation];
}
 
- (void)locationManager:(CLLocationManager *)manager didFailWithError:(NSError *)error
{
    UIAlertView *alert = [[UIAlertView alloc] initWithTitle:@"Error" message:@"Your location could not be determined." delegate:nil cancelButtonTitle:@"OK" otherButtonTitles: nil];
    [alert show];
    [alert release];
}
 
// Delegate method from the CLLocationManagerDelegate protocol.
- (void)locationManager:(CLLocationManager *)manage didUpdateToLocation:(CLLocation *)newLocation fromLocation:(CLLocation *)oldLocation
{
    if (didUpdate)
        return;
 
    didUpdate = YES;
    // Disable future updates to save power.
    [locationManager stopUpdatingLocation];
 
    // let our delegate know we're done
    [delegate newPhysicalLocation:newLocation];
}
 
- (void)dealloc
{
    [locationManager release];
 
    [super dealloc];
}
 
@end

CoreLocation gives you a few options for the accuracy of the user’s location. The more accurate the measurement, typically the longer it takes LocationManager to call it’s delegate method didUpdateToLocation. It’s just something to keep in mind when deciding what level of accuracy to use.

Next we need to actually invoke this code and start getting location updates. I usually do this in my AppDelegate’s didFinishLaunchingWithOptions, though you could also do it in viewDidLoad somewhere if you didn’t need to know the user’s location on app startup.

 - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
 
    UIActivityIndicatorView *spinner = [[UIActivityIndicatorView alloc] initWithActivityIndicatorStyle:UIActivityIndicatorViewStyleWhiteLarge];
	spinner.center = CGPointMake(self.viewController.view.frame.size.width / 2, self.viewController.view.frame.size.height / 2);
    [spinner startAnimating];
 
    [viewController.view addSubview:spinner];
 
    // get our physical location
    LocationGetter *locationGetter = [[LocationGetter alloc] init];
    locationGetter.delegate = self;
    [locationGetter startUpdates];
 
    // Add the view controller's view to the window and display.
    [window addSubview:viewController.view];
    [window makeKeyAndVisible];
 
    return YES;
}

Notice that I’ve set locationGetter’s delegate to self. So in your .h, make sure to add LocationGetterDelegate to the interface.

//
//  CoreLocationExampleAppDelegate.h
//  CoreLocationExample
//
//  Created by Matt Tuzzolo on 9/3/10.
//  Copyright iCodeBlog 2010. All rights reserved.
//
 
#import <uikit/UIKit.h>
#import "LocationGetter.h"
 
@class CoreLocationExampleViewController;
 
@interface CoreLocationExampleAppDelegate : NSObject  {
    UIWindow *window;
    CoreLocationExampleViewController *viewController;
    CLLocation *lastKnownLocation;
}
 
@property (nonatomic, retain) IBOutlet UIWindow *window;
@property (nonatomic, retain) IBOutlet CoreLocationExampleViewController *viewController;
@property (nonatomic, retain) CLLocation *lastKnownLocation;
 
@end

I’ve also added a CLLocation *lastKnownLocation that we’ll use in our delegate method (which comes next):

# pragma mark -
# pragma mark LocationGetter Delegate Methods
 
- (void)newPhysicalLocation:(CLLocation *)location {
 
    // Store for later use
    self.lastKnownLocation = location;
 
    // Remove spinner from view
    for (UIView *v in [self.viewController.view subviews])
    {
        if ([v class] == [UIActivityIndicatorView class])
        {
            [v removeFromSuperview];
            break;
        }
    }
 
    // Alert user
    UIAlertView *alert = [[UIAlertView alloc] initWithTitle:@"Location Found" message:[NSString stringWithFormat:@"Found physical location.  %f %f", self.lastKnownLocation.coordinate.latitude, self.lastKnownLocation.coordinate.longitude] delegate:nil cancelButtonTitle:@"OK" otherButtonTitles: nil];
    [alert show];
    [alert release];
 
    // ... continue with initialization of your app
}

This last piece takes care of storing the location, removing the spinner, and firing off an alert. If this was your code, you’d probably want to re-enable any UI elements that you’ve disabled and let the user start using your app.

Now build and run your app and you should see:

That’s it!

Here’s the Example Project for the post.

For those of you who don’t know me yet, my name is Matt Tuzzolo (@matt_tuzzolo). This is my first iCodeBlog post. I hope you enjoyed it.