How to Add GPS to Your iOS App – Part 1

June 4th, 2012 Posted by: - posted under:Tutorials

CoreLocation Graphic

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.

Link Binary With Libraries
  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”
Add Core Location Framework

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 &lt;UIKit/UIKit.h&gt;
 
//Add Location Framework
#import &lt;CoreLocation/CoreLocation.h&gt;
 
//Specify this app delegate complies with the location manager delegate
@interface CFAAppDelegate : UIResponder &lt;UIApplicationDelegate, CLLocationManagerDelegate&gt;
 
@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).

EnableLocationServicesPrompt

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) &lt; 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.

horizontalAccuracy

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&lt;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) &lt; 15.0)
    {
        //Location timestamp is within the last 15.0 seconds, let's use it!
        if(newLocation.horizontalAccuracy&lt;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:

Simulate Location

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

Simulator Location Services

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

Location In Console

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