Simple XML to NSDictionary Converter

For the past year or so, I’ve been very lucky. All the data I’ve had to deal with has been packaged in JSON, not XML. And what a glorious year it’s been. Instead of writing complex, single-use XML-parsing code, I’ve had the joy of using Stig Brautaset’s excellent JSON-framework to parse JSON. The framework is dead simple to use. Have some JSON? Throw some JSON at the framework, and viola! You get back an NSDictionary or an NSArray. Just one line of code, and you’re done. Simple, elegant, and completely opposite to the experience of parsing XML.

What’s the problem parsing XML? Well, first you have to set up your NSXMLParser. Then, make sure you’re set as the delegate. Then, override the necessary delegate methods (there are 14 relevant NSXMLParserDelegate methods, so choose wisely!). Then, initialize your NSMutableString to record the strings from the text nodes. Then, initialize your model objects from the XML as elements are pushed and popped in the didStart and didEnd methods. And don’t forget to update your objects with data in the attributes dictionary. And so on, and so on.

XML files, especially small XML files, should be as easy to parse as JSON.

Last week, when faced with the depressing task of writing my first XML parser this year, I wrote a general-purpose XML to NSDictionary parser instead. Throw some XML at it, and it spits out an NSDictionary.

How does it work? Here are the key ideas:

  1. XML elements map to key names in the dictionary
  2. Each element corresponds to a child dictionary
  3. Attribute key-value pairs are added to the element’s child dictionary
  4. Strings from text nodes are assigned to the child dictionary’s “text” key
  5. If an element name is encountered multiple times, the value of the element is set to an array of children dictionaries

This conversion is not without its flaws, but it should work pretty well for most XML files.

The Code

The parser consists of a single class, XMLReader. You can either pass it an XML string or an XML data object, and it will return the NSDictionary version of the XML. If the XML is malformed or the parser fails for any other reason, the NSError pointer you pass in will be populated with an NSError object.

Here’s the header file:

// XMLReader.h

#import <Foundation/Foundation.h>

@interface XMLReader : NSObject
    NSMutableArray *dictionaryStack;
    NSMutableString *textInProgress;
    NSError **errorPointer;

+ (NSDictionary *)dictionaryForXMLData:(NSData *)data error:(NSError **)errorPointer;
+ (NSDictionary *)dictionaryForXMLString:(NSString *)string error:(NSError **)errorPointer;


And the implementation:

// XMLReader.m

#import "XMLReader.h"

NSString *const kXMLReaderTextNodeKey = @"text";

@interface XMLReader (Internal)

- (id)initWithError:(NSError **)error;
- (NSDictionary *)objectWithData:(NSData *)data;


@implementation XMLReader

#pragma mark -
#pragma mark Public methods

+ (NSDictionary *)dictionaryForXMLData:(NSData *)data error:(NSError **)error
    XMLReader *reader = [[XMLReader alloc] initWithError:error];
    NSDictionary *rootDictionary = [reader objectWithData:data];
    [reader release];
    return rootDictionary;

+ (NSDictionary *)dictionaryForXMLString:(NSString *)string error:(NSError **)error
    NSData *data = [string dataUsingEncoding:NSUTF8StringEncoding];
    return [XMLReader dictionaryForXMLData:data error:error];

#pragma mark -
#pragma mark Parsing

- (id)initWithError:(NSError **)error
    if (self = [super init])
        errorPointer = error;
    return self;

- (void)dealloc
    [dictionaryStack release];
    [textInProgress release];
    [super dealloc];

- (NSDictionary *)objectWithData:(NSData *)data
    // Clear out any old data
    [dictionaryStack release];
    [textInProgress release];
    dictionaryStack = [[NSMutableArray alloc] init];
    textInProgress = [[NSMutableString alloc] init];
    // Initialize the stack with a fresh dictionary
    [dictionaryStack addObject:[NSMutableDictionary dictionary]];
    // Parse the XML
    NSXMLParser *parser = [[NSXMLParser alloc] initWithData:data];
    parser.delegate = self;
    BOOL success = [parser parse];
    // Return the stack’s root dictionary on success
    if (success)
        NSDictionary *resultDict = [dictionaryStack objectAtIndex:0];
        return resultDict;
    return nil;

#pragma mark -
#pragma mark NSXMLParserDelegate methods

- (void)parser:(NSXMLParser *)parser didStartElement:(NSString *)elementName namespaceURI:(NSString *)namespaceURI qualifiedName:(NSString *)qName attributes:(NSDictionary *)attributeDict
    // Get the dictionary for the current level in the stack
    NSMutableDictionary *parentDict = [dictionaryStack lastObject];
    // Create the child dictionary for the new element, and initilaize it with the attributes
    NSMutableDictionary *childDict = [NSMutableDictionary dictionary];
    [childDict addEntriesFromDictionary:attributeDict];
    // If there’s already an item for this key, it means we need to create an array
    id existingValue = [parentDict objectForKey:elementName];
    if (existingValue)
        NSMutableArray *array = nil;
        if ([existingValue isKindOfClass:[NSMutableArray class]])
            // The array exists, so use it
            array = (NSMutableArray *) existingValue;
            // Create an array if it doesn’t exist
            array = [NSMutableArray array];
            [array addObject:existingValue];
            // Replace the child dictionary with an array of children dictionaries
            [parentDict setObject:array forKey:elementName];
        // Add the new child dictionary to the array
        [array addObject:childDict];
        // No existing value, so update the dictionary
        [parentDict setObject:childDict forKey:elementName];
    // Update the stack
    [dictionaryStack addObject:childDict];

- (void)parser:(NSXMLParser *)parser didEndElement:(NSString *)elementName namespaceURI:(NSString *)namespaceURI qualifiedName:(NSString *)qName
    // Update the parent dict with text info
    NSMutableDictionary *dictInProgress = [dictionaryStack lastObject];
    // Set the text property
    if ([textInProgress length] > 0)
        // Get rid of leading + trailing whitespace
        [dictInProgress setObject:textInProgress forKey:kXMLReaderTextNodeKey];
        // Reset the text
        [textInProgress release];
        textInProgress = [[NSMutableString alloc] init];
    // Pop the current dict
    [dictionaryStack removeLastObject];

- (void)parser:(NSXMLParser *)parser foundCharacters:(NSString *)string
    // Build the text value
    [textInProgress appendString:string];

- (void)parser:(NSXMLParser *)parser parseErrorOccurred:(NSError *)parseError
    // Set the error pointer to the parser’s error object
    *errorPointer = parseError;


The code works by keeping a stack of dictionaries, one for each level of the XML file. Each time a new tag is encountered, a child dictionary is pushed onto the stack. Each time a tag is closed, the dictionary is popped off the stack.

Arrays of elements are detected when the same key appears twice in the dictionary. For instance, if the XML is “<book><page>1</page><page>2</page></book>”, the first time the “page” element is encountered, a child dictionary will be set as the value for the “page” key. The next time the “page” element is encountered, we detect that there’s already a value for the “page” key, so we put both pages in an array and set the value of the “page” key to the array.

Note: One side effect of detecting arrays in this fashion is that the value for a key (say “page” in the example above), can sometimes be set to an NSArray but other times be set to an NSDictionary. For example, if the book contains a single page, “page” will be set to an NSDictionary. If the book contains 2 or more pages, “page” will be set to an NSArray. You will need to account for this when reading from the dictionary produced by dictionaryFromXMLString:error: and dictionaryFromXMLData:error:.

When the parser comes across a text node in the XML, it inserts a key into the dictionary named “text” and sets the value to the parsed string.

Note: Make sure the XML you’re parsing doesn’t contain a field named “text”! You can change it to a non-conflicting name by editing the kXMLReaderTextNodeKey constant at the top of XMLReader.m.

Using the Code

The conversion is best illustrated by an example. The snippet below defines an XML string that is converted into a dictionary using XMLReader:

// XML string from
NSString *testXMLString = @"<items><item id=\"0001\" type=\"donut\"><name>Cake</name><ppu>0.55</ppu><batters><batter id=\"1001\">Regular</batter><batter id=\"1002\">Chocolate</batter><batter id=\"1003\">Blueberry</batter></batters><topping id=\"5001\">None</topping><topping id=\"5002\">Glazed</topping><topping id=\"5005\">Sugar</topping></item></items>";

// Parse the XML into a dictionary
NSError *parseError = nil;
NSDictionary *xmlDictionary = [XMLReader dictionaryForXMLString:testXMLString error:&parseError];

// Print the dictionary
NSLog(@"%@", xmlDictionary);

// testXMLString =
//    <items>
//        <item id=”0001″ type=”donut”>
//            <name>Cake</name>
//            <ppu>0.55</ppu>
//            <batters>
//                <batter id=”1001″>Regular</batter>
//                <batter id=”1002″>Chocolate</batter>
//                <batter id=”1003″>Blueberry</batter>
//            </batters>
//            <topping id=”5001″>None</topping>
//            <topping id=”5002″>Glazed</topping>
//            <topping id=”5005″>Sugar</topping>
//        </item>
//    </items>
// is converted into
// xmlDictionary = {
//    items = {
//        item = {
//            id = 0001;
//            type = donut;
//            name = {
//                text = Cake;
//            };
//            ppu = {
//                text = 0.55;
//            };
//            batters = {
//                batter = (
//                    {
//                        id = 1001;
//                        text = Regular;
//                    },
//                    {
//                        id = 1002;
//                        text = Chocolate;
//                    },
//                    {
//                        id = 1003;
//                        text = Blueberry;
//                    }
//                );
//            };
//            topping = (
//                {
//                    id = 5001;
//                    text = None;
//                },
//                {
//                    id = 5002;
//                    text = Glazed;
//                },
//                {
//                    id = 5005;
//                    text = Sugar;
//                }
//            );
//        };
//     };
// }

The mapping between XML and NSDictionary is shown in the comments above. Notice how the “batter” and “topping” keys are set to arrays since there were multiple “batter” and “topping” keys in the XML. Also, note how the attributes for elements are available in the element’s child dictionary. For instance, the “id” and “type” attributes for item “item” are keys in the “item” dictionary.


You can download the XMLReader files here:

Done and Done

XMLReader isn’t perfect by any stretch of the imagination, but hopefully it helps save you some pain and misery next time you need to parse an XML file in Objective-C.

Adding firstObject to NSArray

NSArray has a lastObject method. So, of course there is a matching firstObject method, right?


If that oversight annoys you to no end, drop this simple category in your code, and say goodbye to all those ugly [array objectAtIndex:0]‘s.

// NSArray+FirstObject.h

#import <Foundation/Foundation.h>

@interface NSArray (FirstObject)

- (id)firstObject;


// NSArray+FirstObject.m

#import "NSArray+FirstObject.h"

@implementation NSArray (FirstObject)

- (id)firstObject
    if ([self count] > 0)
        return [self objectAtIndex:0];
    return nil;


When you need the first element of an array (a common enough task) just use firstObject:

#import "NSArray+FirstObject.h"

NSArray *shows = [NSArray arrayWithObjects:@"Chuck", @"Caprica", @"LOST", nil];

NSString *firstShow = [shows objectAtIndex:0];
NSString *firstShow = [shows firstObject];

Ah, much better.

Detecting Bad CoreLocation Data

CoreLocation can (and will) give you poor location data. Over the course of developing RunMonster, I have become painfully aware of this fact. It turns out, though, that you can detect and discard the most egregiously bad location data using a few simple tests.

When a new point comes in, it is invalid and can be discarded if it matches any of the following criteria:

  • The location is nil.
  • The location’s horizontalAccuracy is < 0.
  • The timestamp of the new location is earlier than the timestamp of the previous location, indicating the points came in out of order.
  • The timestamp of the new location is set to a time before your app was even initialized.

In regards to the last bullet, the CoreLocation framework seems to cache and report points from the last time the GPS unit was used. For instance, if you last ran the GPS in Montana and then open your app in Georgia, the first point could be the last cached point from Montana. If you are running a distance-tracking application, then your app would merrily add thousands of miles to your total distance.

The Code

The helper method below checks for these four cases to determine if the newly reported location is valid or not:

- (BOOL)isValidLocation:(CLLocation *)newLocation
    withOldLocation:(CLLocation *)oldLocation
    // Filter out nil locations
    if (!newLocation)
        return NO;
    // Filter out points by invalid accuracy
    if (newLocation.horizontalAccuracy < 0)
        return NO;
    // Filter out points that are out of order
    NSTimeInterval secondsSinceLastPoint =
        [newLocation.timestamp timeIntervalSinceDate:oldLocation.timestamp];
    if (secondsSinceLastPoint < 0)
        return NO;
    // Filter out points created before the manager was initialized
    NSTimeInterval secondsSinceManagerStarted =
        [newLocation.timestamp timeIntervalSinceDate:locationManagerStartDate];
    if (secondsSinceManagerStarted < 0)
        return NO;
    // The newLocation is good to use
    return YES;

locationManagerStartDate is an NSDate that records when the CLLocationManager is initialized:

locationManager = [[CLLocationManager alloc] init];
locationManager.delegate = self;
[locationManager startUpdatingLocation];

locationManagerStartDate = [[NSDate date] retain];

That’s a Wrap

If you are developing any kind of distance-tracking application that uses the phone’s GPS, you should definitely consider using the filters above. These particular error cases were discovered through trial and error, and as Apple improves CoreLocation, they may very well fix these problems. However, these filters have helped RunMonster avoid the wacky GPS issues that plague many distance-tracking applications.

MKMapView and Zoom Levels: A Visual Guide

So, how exactly does the code provided in the previous post work? What follows is a visual explanation of Google Maps, zoom levels, and how you go about adding support for zoom levels to the MKMapView class.

Round to Flat

This is planet Earth:

As you may know, it is round.

To create a map of the Earth, the curved surface must be projected onto a flat surface. There are many map projections that attempt to flatten the Earth. There are distortions inherent to every projection, but each map projection aims to preserve at least one quality from the original curved representation.

Some projections preserve area, such as the Mollweide projection:

Equirectangluar projections preserve distance between the meridians:

The Mercator projection stretches out the poles in order to preserve locally measured angles:

Google uses the Mercator projection to render Google Maps:

Mercator Math

The Mercator projection converts latitude (φ) and longitude (λ) coordinates to pixel values. It uses math:

You don’t have to understand the math; just know that it converts latitudes and longitudes to pixels.

But, where are these pixels? Well, it depends on your zoom level.

Zoom Levels

At zoom level 0, Google displays the world in a single 256 pixel by 256 pixel tile:

At zoom level 1, Google doubles the area of the map while keeping the tile size constant. So, the map grows to 512 pixels by 512 pixels and uses four tiles:

At zoom level 2, Google doubles the area again. The map grows to 1024 pixels by 1024 pixels and uses sixteen tiles:

The pixel area continues to double at each zoom level, and when zoom level 20 is reached, the map is 536,870,912 pixels by 536,870,912 pixels. It has so many tiles we won’t bother to count them:

Latitudes and Longitudes to Pixels

As part of the PHP Static Maps project, Mike Tuupola wrote some code that converts latitudes and longitudes to pixels at zoom level 20. The code is easily ported to Objective-C:

// Convert latitude and longitude to pixel values at zoom level 20

#define MERCATOR_OFFSET 268435456 /* (total pixels at zoom level 20) / 2 */
#define MERCATOR_RADIUS 85445659.44705395 /* MERCATOR_OFFSET / pi */

x = round(MERCATOR_OFFSET + MERCATOR_RADIUS * longitude * M_PI / 180.0);
y = round(MERCATOR_OFFSET - MERCATOR_RADIUS * logf((1 + sinf(latitude * M_PI / 180.0)) / (1 - sinf(latitude * M_PI / 180.0))) / 2.0);

To be honest, I haven’t taken the time to wrap my head around how this code works. But, knowing that it does work, we can now take any latitude and longitude and figure out its pixel coordinates at zoom level 20. For instance, here are the pixel coordinates of several cities around the world:

Add an iPhone

Say we place an iPhone on top of Anchorage, Alaska at zoom level 20:

In the iPhone shown above, the map size is 320 pixels by 460 pixels. Since we know the map dimensions and center coordinate in pixels, we can easily compute the pixel coordinates of the top-left corner relative to the center pixel coordinate:

We can find the relative position of the top-right and bottom-left pixel coordinates as well:

The PHP Static Maps code also provides code to go from pixels at zoom level 20 to latitudes and longitudes:

// Convert pixel values at zoom level 20 to latitude and longitude

latitude = (M_PI / 2.0 - 2.0 * atan(exp((round(pixelY) - MERCATOR_OFFSET) / MERCATOR_RADIUS))) * 180.0 / M_PI;
longitude = ((round(pixelX) - MERCATOR_OFFSET) / MERCATOR_RADIUS) * 180.0 / M_PI;

We can use this code to convert the corners from pixel coordinates to latitudes and longitudes:

As shown above, using the corner coordinates, we can compute the latitudinal and longitudinal distances. These distances are exactly what we need to construct an MKCoordinateSpan. That span, in turn, is used to initialize the region property of an MKMapView:

// Create an MKCoordinateSpan to initialize the map’s region

MKCoordinateSpan span = MKCoordinateSpanMake(latitudeDelta, longitudeDelta);
MKCoordinateRegion region = MKCoordinateRegionMake(centerCoordinate, span);
[mapView setRegion:region animated:NO];

And you’re done!…That is, if you want to see zoom level 20. What do you do when your user wants to see the map at zoom level 19 instead of 20?

Scaling using Zoom Levels

Relative to zoom level 20, zooming out one level doubles the area visible on the map.

For example, consider the image below. On the left is Anchorage at zoom level 19, and on the right are the 4 iPhones at zoom level 20 it would take to display the same amount of area:

If we move up another level, the area doubles again. Consider the following image. On the left is Anchorage at zoom level 18, and on the right are the 16 iPhones at zoom level 20 it would take to display the same amount of area:

Since the area doubles at each zoom level, we can define the following exponential relationship between the zoom level and the area covered by the map:

// Compute a scaling factor that will take us from any zoom level to zoom level 20

NSInteger zoomExponent = 20 - zoomLevel;
double zoomScale = pow(2, zoomExponent);

double scaledMapWidth = mapSizeInPixels.width * zoomScale;
double scaledMapHeight = mapSizeInPixels.height * zoomScale;

For instance, here is Anchorage at zoom levels 20, 19, and 18. The map’s width and height in pixels are unaltered:

After computing the zoom scale factor, we can apply it to each map to determine its dimensions at zoom level 20:

After we compute these new dimensions, we plug them into the algorithm for finding the coordinates of the map corners.

An Example: Zoom Level 18

For instance, say we take the map at zoom level 18:

Let’s drop the matrix of phones but keep the scaled width and height:

We find the top-left corner just like we did before, except now we use the scaled width and height:

Similarly, we use the scaled width and height for finding the top-right and bottom-left corners as well:

Using the pixel and latitude and pixel and longitude helper methods, we can compute the coordinates of the corners and the distance between them:

These delta values are used to initialize the map’s region property, and the map zooms to the level you specify.

That’s a Wrap

Be sure to check out the previous post for the full code that adds support for zoom levels to MKMapView.

If you are interested in learning more from someone much smarter than I am, check out these posts from Charlie Savage, a programmer and cartographer extraordinaire:

Much of what I know about maps is from these articles, and I highly recommended checking them out if you want to learn more about how Google Maps works under the hood.

Set the Zoom Level of an MKMapView

If you have ever built a web application using the Google Maps API, you are likely intimately familiar with this line of code:

map.setCenter(new google.maps.LatLng(37.4419, -122.1419), 13);

The setCenter JavaScript method takes in the center coordinate and a zoom level. The zoom level, as you might expect, determines how far the map should zoom in. The zoom level ranges from 0 (all the way zoomed out) to some upper value (all the way zoomed in). The max zoom level for a particular area depends on the location (for instance, you can’t zoom in too far on North Korea) and the map type (default, satellite, hybrid, terrain, etc). Typically, the max zoom level for an area is somewhere between 15 – 21.

Unfortunately, MapKit on the iPhone does not include a way to set the zoom level. Instead, the zoom level is set implicitly by defining the MKCoordinateRegion of the map’s viewport. When initializing the region, you specify the amount of distance the map displays in the horizontal and vertical directions. The zoom level is set implicitly based on these distance values.

Instead of dealing with this region business, I wrote a category that adds support for setting the zoom level of an MKMapView explicitly. In this post, I’ll give you code you can drop into your own projects and start using immediately. My next post will detail exactly how it works.

The Code

Instead of force-feeding you everything I learned while working on this mini-project, I’ll give you the goods up front. The code below defines a category on MKMapView that gives you the ability to set the zoom level for your map:

// MKMapView+ZoomLevel.h

#import <MapKit/MapKit.h>

@interface MKMapView (ZoomLevel)

- (void)setCenterCoordinate:(CLLocationCoordinate2D)centerCoordinate


// MKMapView+ZoomLevel.m

#import "MKMapView+ZoomLevel.h"

#define MERCATOR_OFFSET 268435456
#define MERCATOR_RADIUS 85445659.44705395

@implementation MKMapView (ZoomLevel)

#pragma mark -
#pragma mark Map conversion methods

- (double)longitudeToPixelSpaceX:(double)longitude
    return round(MERCATOR_OFFSET + MERCATOR_RADIUS * longitude * M_PI / 180.0);

- (double)latitudeToPixelSpaceY:(double)latitude
    return round(MERCATOR_OFFSET - MERCATOR_RADIUS * logf((1 + sinf(latitude * M_PI / 180.0)) / (1 - sinf(latitude * M_PI / 180.0))) / 2.0);

- (double)pixelSpaceXToLongitude:(double)pixelX
    return ((round(pixelX) - MERCATOR_OFFSET) / MERCATOR_RADIUS) * 180.0 / M_PI;

- (double)pixelSpaceYToLatitude:(double)pixelY
    return (M_PI / 2.0 - 2.0 * atan(exp((round(pixelY) - MERCATOR_OFFSET) / MERCATOR_RADIUS))) * 180.0 / M_PI;

#pragma mark -
#pragma mark Helper methods

- (MKCoordinateSpan)coordinateSpanWithMapView:(MKMapView *)mapView
    // convert center coordiate to pixel space
    double centerPixelX = [self longitudeToPixelSpaceX:centerCoordinate.longitude];
    double centerPixelY = [self latitudeToPixelSpaceY:centerCoordinate.latitude];
    // determine the scale value from the zoom level
    NSInteger zoomExponent = 20 - zoomLevel;
    double zoomScale = pow(2, zoomExponent);
    // scale the map’s size in pixel space
    CGSize mapSizeInPixels = mapView.bounds.size;
    double scaledMapWidth = mapSizeInPixels.width * zoomScale;
    double scaledMapHeight = mapSizeInPixels.height * zoomScale;
    // figure out the position of the top-left pixel
    double topLeftPixelX = centerPixelX - (scaledMapWidth / 2);
    double topLeftPixelY = centerPixelY - (scaledMapHeight / 2);
    // find delta between left and right longitudes
    CLLocationDegrees minLng = [self pixelSpaceXToLongitude:topLeftPixelX];
    CLLocationDegrees maxLng = [self pixelSpaceXToLongitude:topLeftPixelX + scaledMapWidth];
    CLLocationDegrees longitudeDelta = maxLng - minLng;
    // find delta between top and bottom latitudes
    CLLocationDegrees minLat = [self pixelSpaceYToLatitude:topLeftPixelY];
    CLLocationDegrees maxLat = [self pixelSpaceYToLatitude:topLeftPixelY + scaledMapHeight];
    CLLocationDegrees latitudeDelta = -1 * (maxLat - minLat);
    // create and return the lat/lng span
    MKCoordinateSpan span = MKCoordinateSpanMake(latitudeDelta, longitudeDelta);
    return span;

#pragma mark -
#pragma mark Public methods

- (void)setCenterCoordinate:(CLLocationCoordinate2D)centerCoordinate
    // clamp large numbers to 28
    zoomLevel = MIN(zoomLevel, 28);
    // use the zoom level to compute the region
    MKCoordinateSpan span = [self coordinateSpanWithMapView:self centerCoordinate:centerCoordinate andZoomLevel:zoomLevel];
    MKCoordinateRegion region = MKCoordinateRegionMake(centerCoordinate, span);
    // set the region like normal
    [self setRegion:region animated:animated];


If you’re wondering why this works, check out my next post where I describe in gruesome detail the math behind the code.

On the other hand, if you don’t really care how it works, just that it does work, copy and paste away, my friend.

Test the Code

To test the category, assuming you have a view controller with an MKMapView instance, you can use the following code:

// ZoomLevelTestViewController.m

#import "MKMapView+ZoomLevel.h"

#define GEORGIA_TECH_LATITUDE 33.777328
#define GEORGIA_TECH_LONGITUDE -84.397348

#define ZOOM_LEVEL 14

- (void)viewDidAppear:(BOOL)animated
    [super viewDidAppear:animated];
    CLLocationCoordinate2D centerCoord = { GEORGIA_TECH_LATITUDE, GEORGIA_TECH_LONGITUDE };
    [mapView setCenterCoordinate:centerCoord zoomLevel:ZOOM_LEVEL animated:NO];

And, viola! Your map should zoom in to where you can see the Georgia Tech campus.


To verify that the zoom level is set correctly, I wrote a simple web-based Google Maps application to make sure the web and native zoom levels matched. Both apps were centered at {33.777328, -84.397348} (Georgia Tech). In the images below, the iPhone on the left is running the native app and the iPhone on the right is running the web app:

Zoom Level 2: Native app on the left. Web app on the right.

Zoom Level 10: Native app on the left. Web app on the right.

Zoom Level 18: Native app on the left. Web app on the right.

As you can see, they match.

That’s a Wrap

By using the MKMapView+ZoomLevel category, you won’t have to bother setting the region at all. If you are like me and have no intuition for how to set the map’s region, then hopefully this code will give you a bit more control in setting your map’s zoom level.

Next time, I’ll go over exactly why the code above works. But, for now, enjoy the freedom to set zoom levels!

Invalid Product IDs

Do you have an invalid product ID that won’t go away? Good thing the StoreKit API provides error codes and detailed error information explaining why the ID is invalid.

Oh, what’s that? There are no error codes or error details of any kind when you have an invalid product ID, you say? Bah, silly me.

To save you the pain of exhaustively searching the web for the cause of your error, here is a checklist of everything I have stumbled across that can cause an invalid product ID. Make sure you can answer “Yes” to each of these questions:

  • Have you enabled In-App Purchases for your App ID?
  • Have you checked Cleared for Sale for your product?
  • Have you submitted (and optionally rejected) your application binary?
  • Does your project’s .plist Bundle ID match your App ID?
  • Have you generated and installed a new provisioning profile for the new App ID?
  • Have you configured your project to code sign using this new provisioning profile?
  • Are you building for iPhone OS 3.0 or above?
  • Are you using the full product ID when when making an SKProductRequest?
  • Have you waited several hours since adding your product to iTunes Connect?
  • Are your bank details active on iTunes Connect? (via Mark)
  • Have you tried deleting the app from your device and reinstalling? (via Hector, S3B, Alex O, Joe, and Alberto)
  • Is your device jailbroken? If so, you need to revert the jailbreak for IAP to work. (via oh my god, Roman, and xfze)

If you answered “No” to any one of these questions, there’s your problem.

If you answered “Yes” for each of these questions and you still have an invalid product ID, then you have a problem I haven’t seen before. Check out the links in the next section, several of which are Developer Forum posts that were especially helpful in my hunt for debugging invalid product IDs.

Resources for Debugging an Invalid Product

Here are the docs and resources I used to debug invalid product IDs:

If your solution for invalid product IDs wasn’t mentioned in the checklist above, please leave a comment detailing how you fixed the problem so I can keep the checklist up to date.

In App Purchases: A Full Walkthrough

At first glance, adding in-app purchases seems like it would be a walk in the park. Apple provides plenty of documentation that should get developers up and running in no time.

So, why is adding in-app purchases such a royal pain in the arse?

Because, inevitably, something will go wrong. And when that moment arrives, you’re screwed. Apple provides a beastly amount of documentation on in-app purchases, but they don’t provide the right kind of documentation. Nowhere is there mention of the setup steps you have to take to get in-app purchases to work. Nowhere is there a checklist you can reference if your StoreKit integration doesn’t work. Nowhere is there an NSError object that tell you exactly why your product ID is invalid.

You are left to flounder and flail like a wet noodle as you exhaustively try every possible solution on the web.

Losing days of productivity on this is ridiculous. To save you the pain and suffering I went through, this post details every step you need to take to implement in-app purchases. It’s detailed. It’s long. It’s probably overly-detailed and overly-long. But, unlike the Apple docs, it contains every single step necessary for any developer to implement in-app purchases.

Without further ado, let’s get started.


Ok, folks, here’s the secret to getting in-app purchases working: break it into two distinct steps:

  1. Create and fetch a product description
  2. Purchase a product

The first step is where you will likely run into problems. Once you can successfully fetch a product description in code, writing the code to purchase the product is cake.

We’ll tackle the product description step first.

Create and Fetch a Product Description

Here is a (very) rough overview of each step required to create a new product and fetch its description:

  1. Create a unique App ID
  2. Generate and install a new provisioning profile
  3. Update the bundle ID and code signing profile in Xcode
  4. If you haven’t already, submit your application metadata in iTunes Connect
  5. If you haven’t already, submit your application binary in iTunes Connect

Update: You do NOT need to submit your application binary to get IAP working. See question #4 in Apple’s FAQ (thanks to everyone in the comments who pointed this out)

  1. Add a new product for in-app purchase
  2. Write code for fetching the product description
  3. Wait a few hours

The code for fetching a product description is really simple. The setup steps, on the other hand, are rife with peril.

NOTE: You do NOT need to create an in-app test user in iTunes Connect to fetch a product description.

1. Create a Unique App ID

To support in-app purchases, your App ID cannot include a wildcard character (“*”). To see if your App ID contains a wildcard, log in to, and navigate to the iPhone Developer Program Portal. Select “App IDs” from the menu on the left, and look for your App ID.

This is a unique App ID:

This is not a unique App ID:*

If you don’t have a unique App ID, create one as follows:

  1. On the App IDs tab in the developer portal, select “New App ID”
  2. Fill in the following information:
    • Display name: Pick a different App ID name than you were using before. You can’t edit or delete old App IDs, so just give your App ID a new name to avoid confusion.
    • Prefix: Generate a new one, or choose an existing one if your app is one of a suite of apps that can share data via the Keychain Services API
    • Suffix: com.companyname.appname (this is the usual format – note lack of wildcard)
  3. Click “Save”
  4. Click the “Configure” link next to your App ID
  5. Check box next to “Enable In App Purchase”
  6. Click “Done”

2. Create a New Provisioning Profile

Now that you have a new App ID, you need to generate a new provisioning profile that points to the App ID.

Here’s the painfully detailed step-by-step for generating and installing a new provisioning profile:

  1. In the iPhone Developer Portal, select the Provisioning tab on the left
  2. Make sure you’re on the Development tab, and click “New Profile” in the top-right corner
  3. Fill in the requested information, and point to the unique App ID you just created
  4. If see “Pending” in the Actions column, just click the Development tab title to refresh
  5. Click “Download” to pull down the new profile
  6. Drag the profile onto the Xcode icon in the Dock to install
  7. Alternatively, if you want to preserve the name of the provisioning profile on disk, you can install the profile manually as follows:
    1. In Xcode, select Window > Organizer
    2. Select “Provisioning Profiles” category on the left
    3. Ctrl-click an existing profile > Reveal in Finder
    4. Drag and drop the new profile into the profile Finder window

3. Update Xcode Settings

After the profile is installed in Xcode, you need to make a couple edits to the project to use the provisioning profile:

  1. Edit your project’s .plist file so the Bundle ID entry matches the App ID. Ignore the alphanumeric sequence at the beginning of the ID. For instance, if your App ID is “” in the Developer Portal, just enter “com.runmonster.runmonsterfree” for the Bundle ID.
  2. Edit your project’s target info to use the new provisioning profile:
    1. Select Project > Edit Active Target
    2. Select the “Build” tab at the top
    3. Select the configuration you want (usually Debug)
    4. Select your new provisioning profile for the row labeled Code Signing Identity
    5. Select your new provisioning profile for the row directly underneath the Code Signing Identity row (probably labeled Any iPhone OS Device)

4. Add your Application

If your application is already available on the App Store, you can skip this step.

Before you can add a product in iTunes Connect, you must add the application the product is for. Don’t worry if you aren’t a 100% done with your app. You can still submit your app wtih stub data and add the real details later.

NOTE: Only the SKU and version fields are permanent and cannot be changed later.

  1. Navigate to, and log in
  2. Follow the right-hand link to iTunes Connect
    • NOTE: you MUST be logged in to first, or bad things will happen
  3. On the iTunes Connect homepage, click the “Manage Your Applications” link
  4. In the top-right corner, click “Create New Application”
  5. Fill out all the requested information for your app. When asked for your application binary, check the box indicating you will upload it later.

5. Add the App Binary

Update: This step is NOT required. See question #4 in Apple’s FAQ on IAP (thanks to everyone in the comments who pointed this out)

This detail is not mentioned anywhere in Apple’s documentation, but is a requirement nonetheless. You must submit a binary for your application in order to successfully test in-app purchases. Even if you aren’t 100% done, you need to submit a binary. However, you can immediately reject the binary so it won’t go through the review process.

This was the crucial step I missed that caused me hours of grief and frustration. Follow these steps to add the binary:

  1. Build your application for App Store distribution
    • If you don’t know how, navigate to the iPhone Developer Portal, click on the Distribution tab on the left, and make sure you are in the “Prepare App” tab. Now, follow the instructions in the following blue links:
      • Obtaining your iPhone Distribution Certificate
      • Create and download your iPhone Distribution Provisioning Profile for App Store Distribution
      • Building your Application with Xcode for Distribution
  2. Navigate to your app’s page in iTunes Connect
  3. Select “Upload Binary”
  4. Upload your .zip compressed application
  5. If you aren’t 100% ready for your app to be reviewed, then click the “Reject Binary” link on your app homepage in iTunes Connect. The app’s status should update to “Developer Rejected”.

Have no fear. Apple will not review this version of the app once it is “Developer Rejected”. You can submit a new version of your app at any point, and having the status “Developer Rejected” doesn’t affect the wait time for your future submissions in the slightest.

6. Add the Product

After all that setup, we are finally ready to add the product itself to iTunes Connect.

  1. Make sure you are logged in to
  2. Navigate to the iTunes Connect homepage
  3. Click the “Manage Your in App Purchases” link
  4. Click “Create New”
  5. Select your application
  6. Fill in the production information:
    • Reference Name: common name for the product. I used “Pro Upgrade”. This name is non-editable, and it will not be displayed in the App Store.
    • Product ID: unique id for your app. Typically of the form, but it can be whatever you want. It does not need to have your app’s App ID as a prefix.
    • Type: You have 3 choices:
      • Non-consumable: only pay once (use this if you want a free-to-pro-upgrade product)
      • Consumable: pay for every download
      • Subscription: recurring payment
    • Price Tier: price of the product. See the price matrix for the different tiers.
    • Cleared for Sale: check this now. If you don’t, you will get back an invalid product ID during testing.
    • Language to Add: Pick one. The following two fields will appear:
      • Displayed Name: Name of your product shown to your user. I chose “Upgrade to Pro”.
      • Description: What the product does. The text you enter here is sent along with the Displayed Name and Price when you fetch an SKProduct in code.
    • Screenshot: Your feature in action. Despite the text on the screen about the screenshot submission triggering the product review process (a very sloppy design choice, IMHO), you can safely add the screenshot now without the product being submitted for review. After saving the product, just choose the “Submit with app binary” option. This will tie the product to the app binary, so when you finally submit the 100% complete app binary, the product will be submitted as well.
  7. Click “Save”

7. Write Code

Now, we finally write the code the fetches the product information we just added in iTunes Connect. To access the product data, we need to use the StoreKit framework.

NOTE: StoreKit does not work on the Simulator. You must test on a physical device.

  1. Add the StoreKit framework to your project.
  2. Add a reference to a SKProduct to your .h file:
// InAppPurchaseManager.h

#import <StoreKit/StoreKit.h>

#define kInAppPurchaseManagerProductsFetchedNotification @"kInAppPurchaseManagerProductsFetchedNotification"

@interface InAppPurchaseManager : NSObject <SKProductsRequestDelegate>
    SKProduct *proUpgradeProduct;
    SKProductsRequest *productsRequest;

NOTE: InAppPurchaseManager is a singleton class that handles every in app purchase for our app. It’s used throughout this post as an example implementation.

  1. Request the product, and implement the delegate protocol in the corresponding .m file:
// InAppPurchaseManager.m

- (void)requestProUpgradeProductData
    NSSet *productIdentifiers = [NSSet setWithObject:@"com.runmonster.runmonsterfree.upgradetopro" ];
    productsRequest = [[SKProductsRequest alloc] initWithProductIdentifiers:productIdentifiers];
    productsRequest.delegate = self;
    [productsRequest start];
    // we will release the request object in the delegate callback

#pragma mark -
#pragma mark SKProductsRequestDelegate methods

- (void)productsRequest:(SKProductsRequest *)request didReceiveResponse:(SKProductsResponse *)response
    NSArray *products = response.products;
    proUpgradeProduct = [products count] == 1 ? [[products firstObject] retain] : nil;
    if (proUpgradeProduct)
        NSLog(@"Product title: %@" , proUpgradeProduct.localizedTitle);
        NSLog(@"Product description: %@" , proUpgradeProduct.localizedDescription);
        NSLog(@"Product price: %@" , proUpgradeProduct.price);
        NSLog(@"Product id: %@" , proUpgradeProduct.productIdentifier);
    for (NSString *invalidProductId in response.invalidProductIdentifiers)
        NSLog(@"Invalid product id: %@" , invalidProductId);
    // finally release the reqest we alloc/init’ed in requestProUpgradeProductData
    [productsRequest release];
    [[NSNotificationCenter defaultCenter] postNotificationName:kInAppPurchaseManagerProductsFetchedNotification object:self userInfo:nil];

A couple notes about the code above:

  • When specifying the product identifier, you must use the full product id. For instance, “com.runmonster.runmonsterfree.upgradetopro” is used above. “upgradetopro” alone will not work.
  • If response.products is nil in productsRequest:didReceiveResponse: and your product id shows up in the response.invalidProductIdentifers array, then prepare yourself mentally for a wild goose chase. The StoreKit API offers no help, no indication as to why your identifier was invalid, just that it is. Lovely, isn’t it?
  • The SKProduct class conveniently offers localized versions of your app title and description, but not price. To handle this omission, here’s a category that will provide a localized price string for the product as well:
// SKProduct+LocalizedPrice.h

#import <Foundation/Foundation.h>
#import <StoreKit/StoreKit.h>

@interface SKProduct (LocalizedPrice)

@property (nonatomic, readonly) NSString *localizedPrice;


// SKProduct+LocalizedPrice.m

#import "SKProduct+LocalizedPrice.h"

@implementation SKProduct (LocalizedPrice)

- (NSString *)localizedPrice
    NSNumberFormatter *numberFormatter = [[NSNumberFormatter alloc] init];
    [numberFormatter setFormatterBehavior:NSNumberFormatterBehavior10_4];
    [numberFormatter setNumberStyle:NSNumberFormatterCurrencyStyle];
    [numberFormatter setLocale:self.priceLocale];
    NSString *formattedString = [numberFormatter stringFromNumber:self.price];
    [numberFormatter release];
    return formattedString;


After adding all the code above, give it a shot. You should see the product information gloriously regurgitated in your console window. However, you are more than likely getting back an invalid product ID. My next post addresses exactly how to go about debugging this problem, but the very next section may in fact hold your solution.

8. Wait a Few Hours

Have you followed all the steps above to the letter, and your product is still reported as invalid? Have you painstakingly double, triple, quadruple-checked to make sure you have followed every step? Have you despaired from finding frighteningly little in-app purchase information on the web?

Then, you may just need to wait.

It takes a while for the product you added to iTunes Connect to permeate Apple’s distributed in-app sandbox environment. For me, I gave up in despair after the umpteenth time my product came back as invalid. 24 hours later, I hadn’t changed a line a code, but my IDs were coming back valid. I think it really only took a few hours for the product to propagate through Apple’s distributed network, but if you can afford to wait, you may want to give it 24 hours like I did.

Purchase a Product

At this point, you should be able to successfully fetch an SKProduct description for your product. Adding support for purchasing the product is relatively simple compared to getting the description. There are only three steps required:

  1. Write code for supporting transactions
  2. Add an in app test user in iTunes Connect
  3. Sign out of your iTunes Store account on your phone
  4. Test the purchase

We’ll start off by taking a look at the code required to support transactions.

1. Write Code for Supporting Transactions

First, a word of warning: you are responsible for developing the user interface for purchasing your product. StoreKit offers absolutely zero interface elements. If you want your purchase view to look like the App Store’s, well, you have to build it yourself.

All the code below is for the backend of the transaction process. It is a single class with a simple API that an outside class (like a view controller) can call to make the purchase. I recommend a similar approach if you are figuring out how best to integrate in app purchases in your app.

First, you need to conform to the SKPaymentTransactionObserver protocol:

// InAppPurchaseManager.h

// add a couple notifications sent out when the transaction completes
#define kInAppPurchaseManagerTransactionFailedNotification @"kInAppPurchaseManagerTransactionFailedNotification"
#define kInAppPurchaseManagerTransactionSucceededNotification @"kInAppPurchaseManagerTransactionSucceededNotification"

@interface InAppPurchaseManager : NSObject <SKProductsRequestDelegate, SKPaymentTransactionObserver>

// public methods
- (void)loadStore;
- (BOOL)canMakePurchases;
- (void)purchaseProUpgrade;


Above, we have defined two more notifications that will be sent out with the result of the purchase transaction. For the sake of this example, we are using the InAppPurchaseManager class again, just as we did when when fetching the product description.

// InAppPurchaseManager.m

#define kInAppPurchaseProUpgradeProductId @"com.runmonster.runmonsterfree.upgradetopro"

#pragma -
#pragma Public methods

// call this method once on startup
- (void)loadStore
    // restarts any purchases if they were interrupted last time the app was open
    [[SKPaymentQueue defaultQueue] addTransactionObserver:self];
    // get the product description (defined in early sections)
    [self requestProUpgradeProductData];

// call this before making a purchase
- (BOOL)canMakePurchases
    return [SKPaymentQueue canMakePayments];

// kick off the upgrade transaction
- (void)purchaseProUpgrade
    SKPayment *payment = [SKPayment paymentWithProductIdentifier:kInAppPurchaseProUpgradeProductId];
    [[SKPaymentQueue defaultQueue] addPayment:payment];

#pragma -
#pragma Purchase helpers

// saves a record of the transaction by storing the receipt to disk
- (void)recordTransaction:(SKPaymentTransaction *)transaction
    if ([transaction.payment.productIdentifier isEqualToString:kInAppPurchaseProUpgradeProductId])
        // save the transaction receipt to disk
        [[NSUserDefaults standardUserDefaults] setValue:transaction.transactionReceipt forKey:@"proUpgradeTransactionReceipt" ];
        [[NSUserDefaults standardUserDefaults] synchronize];

// enable pro features
- (void)provideContent:(NSString *)productId
    if ([productId isEqualToString:kInAppPurchaseProUpgradeProductId])
        // enable the pro features
        [[NSUserDefaults standardUserDefaults] setBool:YES forKey:@"isProUpgradePurchased" ];
        [[NSUserDefaults standardUserDefaults] synchronize];

// removes the transaction from the queue and posts a notification with the transaction result
- (void)finishTransaction:(SKPaymentTransaction *)transaction wasSuccessful:(BOOL)wasSuccessful
    // remove the transaction from the payment queue.
    [[SKPaymentQueue defaultQueue] finishTransaction:transaction];
    NSDictionary *userInfo = [NSDictionary dictionaryWithObjectsAndKeys:transaction, @"transaction" , nil];
    if (wasSuccessful)
        // send out a notification that we’ve finished the transaction
        [[NSNotificationCenter defaultCenter] postNotificationName:kInAppPurchaseManagerTransactionSucceededNotification object:self userInfo:userInfo];
        // send out a notification for the failed transaction
        [[NSNotificationCenter defaultCenter] postNotificationName:kInAppPurchaseManagerTransactionFailedNotification object:self userInfo:userInfo];

// called when the transaction was successful
- (void)completeTransaction:(SKPaymentTransaction *)transaction
    [self recordTransaction:transaction];
    [self provideContent:transaction.payment.productIdentifier];
    [self finishTransaction:transaction wasSuccessful:YES];

// called when a transaction has been restored and and successfully completed
- (void)restoreTransaction:(SKPaymentTransaction *)transaction
    [self recordTransaction:transaction.originalTransaction];
    [self provideContent:transaction.originalTransaction.payment.productIdentifier];
    [self finishTransaction:transaction wasSuccessful:YES];

// called when a transaction has failed
- (void)failedTransaction:(SKPaymentTransaction *)transaction
    if (transaction.error.code != SKErrorPaymentCancelled)
        // error!
        [self finishTransaction:transaction wasSuccessful:NO];
        // this is fine, the user just cancelled, so don’t notify
        [[SKPaymentQueue defaultQueue] finishTransaction:transaction];

#pragma mark -
#pragma mark SKPaymentTransactionObserver methods

// called when the transaction status is updated
- (void)paymentQueue:(SKPaymentQueue *)queue updatedTransactions:(NSArray *)transactions
    for (SKPaymentTransaction *transaction in transactions)
        switch (transaction.transactionState)
            case SKPaymentTransactionStatePurchased:
                [self completeTransaction:transaction];
            case SKPaymentTransactionStateFailed:
                [self failedTransaction:transaction];
            case SKPaymentTransactionStateRestored:
                [self restoreTransaction:transaction];

In order to test this jumble of new code, you will need to write the code that calls the loadStore, canMakePurchases, and purchaseProUpgrade methods as well.

As you can see, there’s a good bit of code required to support transactions. For a full explanation of the code, see the official In App Purchase Programming Guide –

The code above has a few parts that are specific to my implementation. Most notably, in provideContent:, the @"isProUpgradePurchased" BOOL field of NSUserDefaults is set to YES. All throughout the rest of the application, this BOOL is checked to determine whether or not to enable the pro features. If you are also implementing a free to pro upgrade product, I recommend using the same approach.

2. Add a Test User

In order to try out the mess of code you just added to your project, you will need to create a user in iTunes Connect for testing in app purchases. You can use this test account to purchase a product without being charged by Apple.

To create a test user, follow these steps:

  1. Log in to
  2. Navigate to iTunes Connect
  3. Select “Manage Users” on the iTunes Conect home page
  4. Select “In App Purchase Test User”
  5. Select “Add New User”
  6. Fill out the user information. None of the information needs to be legit. I recommend a short, fake email address and a short password since you will need to type it in your phone during testing.
  7. Select “Save”

You will enter the email and password for this user on the iPhone during your testing.

3. Sign Out On Your Device

Before you can start testing in app purchases, you must sign out of the iTunes Store on your device. To sign out, follow these steps:

  1. Open the Settings App
  2. Tap the “Store” row
  3. Tap “Sign Out”

4. Test the Purchase

Now, you are finally ready to try out an in app purchase. Testing is simple:

  1. Run your app on your device
  2. Trigger the purchase
  3. When prompted for username and password, enter your test user details

If you repeat the purchase with the same account, you will be notified that you have already made the purchase. This is fine, just click “Yes” when prompted if you want to download the product again.

That’s a Wrap

Getting in app purchases to work is a lot more painful than it should be. It took several days of blood, sweat, and tears to get it working in my own application, and hopefully this post has helped short circuit that cycle of pain and suffering for you as well.