iOS SDK

The MapBox iOS SDK is a toolset for building mapping applications for iPhone and iPad devices. It is quite similar in behavior to Apple’s MapKit framework, but with much greater flexibility for visual styling, offline use, and general customizability – plus it’s open source.

SDK Installation

CocoaPods

Follow these steps in order to use the MapBox iOS SDK within your own Xcode 4 project using CocoaPods. This is the easiest installation method if you are familiar with CocoaPods.

1. Obtain the map ID for your hosted map by clicking Publish and copying the Map ID.
2. Ensure that your Podfile is targeting :ios and '5.0'.
3. Add a line containing pod 'MapBox' to your Podfile.
4. Run pod install in the Terminal.
5. At a minimum, #import <MapBox/MapBox.h> and instantiate an RMMapView in your code along with an RMMapBoxSource using -initWithMapID: and an NSString made from your Map ID obtained above.

Binary

Follow these steps in order to use the MapBox iOS SDK within your own Xcode 4 project as a statically linked framework. This is the installation method that is the most similar to using Apple-provided frameworks.

1. Obtain the map ID for your hosted map by clicking Publish and copying the Map ID.

2. Download the latest SDK binary release from the downloads and drag MapBox.framework into your project’s Frameworks section, making sure to link it in your target.

3. Add -ObjC to your app target’s Other Linker Flags build setting in order to ensure that the SDK’s static library has all symbols loaded, even for categories.

4. Add the following libraries to your app target’s Link Binary With Libraries build phase:

   • CoreLocation.framework (required for location services)
   • QuartzCore.framework (required because of advanced layer manipulation)
   • libsqlite3.dylib (required for MBTiles and caching support)
   • libz.dylib (required for UTFGrid interactivity)

5. Add MapBox.framework/Resources/MapBox.bundle to your project’s file sources, either by dragging it into your project from Finder or via File > Add Files.... Be sure that Copy items into destination group's folder (if needed) is unchecked and that Add to targets includes your app target. This way, the bundle will be copied at build time out of the framework folder and included as a resource in your app product.

6. At a minimum, #import <MapBox/MapBox.h> and instantiate an RMMapView in your code along with an RMMapBoxSource using -initWithMapID: and an NSString made from your Map ID obtained above.

Source

Follow these steps in order to use the MapBox iOS SDK within your own Xcode 4 project while retaining the ability to edit the SDK source as you go. This is the most flexible installation method if you want to be able to modify the source code of the SDK.

1. Obtain the map ID for your hosted map by clicking Publish and copying the Map ID.

2. Download the SDK source code from the repository and put it someplace in your project’s folder. We assume below that this is a top-level folder called MapBox-iOS-SDK.

3. Add MapView.xcodeproj to your project’s file sources, either by dragging it into your project from Finder or via File > Add Files..., in order to make the library available to your project.

4. Add -ObjC to your app target’s Other Linker Flags build setting in order to ensure that the SDK’s static library has all symbols loaded, even for categories.

5. Add "$(SRCROOT)/MapBox-iOS-SDK" (per your folder naming scheme) to the Header Search Paths build setting for your app target in order to gain access to the headers. Be sure to check the Recursive option.

6. Add the MapView target to your app target’s Target Dependencies build phase in order to build the library when you build your project.

7. Add the following libraries to your app target’s Link Binary With Libraries build phase:

   • CoreLocation.framework (required for location services)
   • QuartzCore.framework (required because of advanced layer manipulation)
   • libMapBox.a (required to include the SDK)
   • libsqlite3.dylib (required for MBTiles and caching support)
   • libz.dylib (required for UTFGrid interactivity)

8. Add the MapBox.bundle product from the SDK to the Copy Bundle Resources build phase of your app target. This way, the bundle will be copied at build time out of the SDK build products folder and included as a resource in your app product.

9. At a minimum, #import "MapBox.h" and instantiate an RMMapView in your code along with an RMMapBoxSource using -initWithMapID: and an NSString made from your Map ID obtained above.

API overview

Below we’ll talk about the major components used when building a map-based iOS app with our SDK. We’re assuming you have a general familiarity with Apple’s developer tools, the Cocoa framework, and the Objective-C language and conventions. Full API documentation is available as well, including as an embedded Xcode Atom feed.

Map view (RMMapView class)

The map view is the basic view that you’ll work with to display a map that pans and zooms in response to gestures. You can instantiate a map view in code or you can embed one in an Interface Builder (.xib) file, just like any other UIView subclass. By default, if not configured with a tile source (see SDK Installation above), the map view will display a watermarked example MapBox map, automatically detecting whether a retina or normal version should be used. There are options to control the map style (with tile sources), markers and shapes on the map, offline caching policy, zooming limits, retina display behavior, starting coordinate, and map view dragging deceleration, among other parameters.

Map view delegate (RMMapViewDelegate protocol)

Following Objective-C’s customary delegation design pattern, a map view can have an optional delegate object in order to help make interaction decisions. Some of these decisions include:

• Setup and display of markers and other annotations on the map view (see Markers & shapes below)
• Pre- and post-move and zoom response handlers in order to, for example, update another interface element in response to a map drag
• Gesture handlers for taps, double-taps, and long-presses on the map
• Interaction handlers for markers and other annotations

Tile sources (RMTileSource protocol)

Tile sources are a concept similar to changing between standard, satellite, and hybrid styles in MapKit, but with much more customizability. With tile sources, the map style can be changed by providing one or more online or offline tile-based layers to display on the map from a variety of providers. In addition, the MapBox SDK supports client-side compositing of tile layers for increased performance and responsiveness.

The tile sources that support MapBox’s core technology include RMMapBoxSource for online layers from MapBox Hosting or a TileStream server, and the RMMBTilesSource for use of offline-capable MBTiles layers.

Markers & shapes (RMMapLayer and subclasses)

Markers and other visual additions above the map tile layers are managed with RMMapLayer and its subclasses:

• RMMarker - points and images
• RMShape - vector lines and other custom shapes
• RMCircle - perfect vector circles

In addition, any RMMapLayer, as a CALayer subclass, can have its contents property set to a CGImage and the layer will be panned and zoomed with the map automatically. You may wish to use the map view’s delegate callbacks to respond to map zooms, however, in order to redraw the image according to zoom level in order to preserve the best visual appearance.

Markers and shapes are added in a manner similar to MapKit, where annotation data objects (RMAnnotation) are added to the map view, then the map view delegate answers requests for the actual layers to be displayed when they are first needed, providing better performance.

Embedded interactivity (RMInteractiveSource protocol)

Embedded interactivity (based on the UTFGrid specification) is a way to embed arbitrary point and region data with a tile map layer for fast and convenient recall when needed. See this map for an example. The primary advantage to this technology is fast interactivity in web browsers, but the MapBox iOS SDK also features easy support for it for cross-platform use of the same maps.

In order to make use of UTFGrid interactivity on iOS, any RMMapBoxSource (online) or RMMBTilesSource (offline) tile sources will have category methods added to them allowing querying of interactivity for a given map view and CGPoint, suitable for use when the map is tapped or other gestures are applied. For example, tapping a given map point within a country’s borders might return the HTML-formatted content necessary to display the country’s name and flag image in a popup.

Tile caching (RMTileCache class)

MapBox offers unrestricted control for caching our maps such as MapBox Streets on mobile devices with the MapBox iOS SDK, supporting both app developers who want fine-grained control of app storage size and performance, as well as for users who want the optimum use of bandwidth and the best performance for the maps in an app.

• You may cache maps as much as you’d like.
• You may cache maps for as long as you’d like.
• You may not run a proxy or intermediate cache between MapBox and devices.
• You may not further redistribute maps from a device cache.

For the full details see our Terms of Service.

In addition, background download of tiles directly into cache, without requiring a visible map view, can be performed in order to prepare for offline use. See the RMTileCache class and the RMTileCacheBackgroundDelegate protocol in the API reference for more information, including device- and processor architecture-based options for configuration.

How tiles are loaded

When a map view is shown and the user starts panning and zooming around to explore an area, the SDK requests the necessary tiles. The RMMapBoxSource tile source checks its local cache of tiles before ever trying to request data over the network, so if a tile has been downloaded recently, it is instantly recalled and used to load the map.

How the tile cache works

By default, the Route-Me rendering engine (upon which the SDK is based) stores the 1,000 most recently downloaded tile images. Once more room is needed, the oldest tiles are deleted from cache. You can also remove all tiles whenever desired with the removeAllCachedImages method on RMMapView.

You can also manage cache deletion based on the age of tiles in the cache. For example, creating the RMTileCache with an expiryPeriod of 604,800 (60 seconds x 60 minutes x 24 hours x 7 days) will cause tiles to stay in the cache no longer than a week, without regard to the number of tiles, before the SDK will automatically delete the older tiles to keep things tidy. Setting an expiryPeriod overrides any capacity-based configuration for the tile cache.

File-based cache configuration

Carried over from the Route-Me engine is the ability to configure cache behavior with a property list file included as a resource in your project. Below is a sample routeme.plist file structure with inline comments. See the source to RMTileCache.m for more information.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>caches</key>
    <array>
        <dict>
            <key>type</key>
            <string>db-cache</string> <!--(indicate that we're configuring the database cache)-->
            <key>capacity</key>
            <integer>10000</integer> <!--(maximum tiles to store; defaults to 1,000)-->
            <key>expiryPeriod</key>
            <integer>86400</integer> <!--(maximum seconds to store tiles; overrides capacity; 0 = unlimited; defaults to unset)-->
            <key>minimalPurge</key>
            <integer>10</integer> <!--(minimum number to purge at a time when clearing; defaults to 10% of capacity)-->
            <key>strategy</key>
            <string>FIFO</string> <!--(FIFO = first in, first out; LRU = least recently used; defaults to FIFO)-->
            <key>useCachesDirectory</key>
            <true/> <!--(use the app Caches folder instead of Documents; defaults to false)-->
        </dict>
        <dict>
            <key>type</key>
            <string>memory-cache</string> <!--(indicate that we're configuring the memory cache)-->
            <key>capacity</key>
            <integer>32</integer> <!--(maximum number of tiles to store in memory; defaults to 32)-->
        </dict>
    </array>
</dict>
</plist>

Attribution

You must comply with the licensing terms of any map data in your application, including MapBox Streets or other MapBox maps if used. A small attribution control will be displayed on the map view automatically if attribution info is available from the tile source.

Retina support

MapBox Streets has retina tile support that can be utilized by the iOS SDK. This brings high-DPI display support for devices such as the iPhone 4 and newer and the retina iPads.

Retina tiles use an enhanced look including wider streets and enlarged labels. The resulting image on retina-capable devices is incredibly sharp. Here’s a side-by-side comparison up close:

Using retina tiles with the iOS SDK

1. Create a custom styled map with the retina 2x option enabled and save your changes.
2. In the Objective-C code, use the newly saved map’s map ID (obtained from the Publish tab) to instantiate an RMMapBoxSource tile source. Ensure that the map view’s adjustTilesForRetinaDisplay property is set to NO (which is the default). Tiles will then draw at the normal 256px size instead of being magnified to 512px for legibility.
3. If you are supporting non-retina devices, you will want two versions of your maps, just as you have two versions of graphical assets, and detect which map to use via [[UIScreen mainScreen] scale].

For a quick video overview of editing map styles and embedding them in an iOS app, watch our feature on Custom Styled Maps for iOS Apps in 5 Minutes.