Mapbox iOS SDK

Current Version 3.6 View changelog

Eight ready-to-use styles

Offline maps

Performant vector maps

Design custom styles

Contribute on Github

Recommended

Download

Carthage

CocoaPods

Create a Podfile in your project root with the following:

platform :ios, '8.0'

target 'TargetNameForYourApp' do
  pod 'Mapbox-iOS-SDK', '~> 3.6'
end

In Terminal, run pod install. Open the resulting xcworkspace file in Xcode.
In your app’s Info.plist file (in the Project Navigator, or in the Info tab of the project editor), set MGLMapboxAccessToken to your Mapbox access token.

Download the latest SDK dynamic framework release (v3.6.2) and unzip it.
Drag Mapbox.framework into your project’s Embedded Binaries section in the project editor. This will add Mapbox.framework to your project’s linked libraries. In the sheet that appears, make sure “Copy items if needed” is checked, then click Finish.
In the Build Phases tab of the project editor, click the + button at the top and select “New Run Script Phase”. Enter the following code into the script text field:
```
bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/Mapbox.framework/strip-frameworks.sh"
```
In your app’s Info.plist file (in the Project Navigator, or in the Info tab of the project editor), set MGLMapboxAccessToken to your Mapbox access token:
```
// Your default Mapbox access token
<your access token here>
```

Create a Cartfile in your project root with the following:

binary "https://www.mapbox.com/ios-sdk/Mapbox-iOS-SDK.json" ~> 3.6

In Terminal, run carthage update.
In your app’s Info.plist file (in the Project Navigator, or in the Info tab of the project editor), set MGLMapboxAccessToken to your Mapbox access token.
In your app target’s General settings tab, in the Linked Frameworks and Libraries section, drag and drop Mapbox.framework from the Carthage/Build/iOS folder on disk.
In the Build Phases tab, click the + icon and choose New Run Script Phase. Create a Run Script phase and add the following to the script area below the shell:
```
/usr/local/bin/carthage copy-frameworks
```
Then add the framework’s path to the Input Files for this script phase:
```
$(SRCROOT)/Carthage/Build/iOS/Mapbox.framework
```

See the Carthage documentation for more information about project setup.

Start building

The Mapbox iOS SDK requires Xcode 8 or above. You will need to update your version of Xcode if you are using Xcode 7.x or below.

Access tokens

An access token is necessary to use Mapbox services and APIs, such as maps, directions, and telemetry. Your access tokens can be managed in your account settings, where you can retrieve current tokens and generate new ones. You should create a new token for each of your apps, which will help you track usage and minimize disruption in the event a token needs to be revoked.

There are two ways to provide an access token in your app:

In the Info.plist file (in the Project Navigator, or in the Info tab of the project editor), set MGLMapboxAccessToken.
In the app delegate method application:didFinishLaunchingWithOptions:, use -[MGLAccountManager setAccessToken:].

Telemetry opt out

Mapbox Telemetry is a powerful location analytics platform included in this SDK. By default, anonymized location and usage data is sent to Mapbox whenever the host app causes it to be gathered. The Mapbox Terms of Service require your app to provide users with a way to individually opt out of Mapbox Telemetry, which is provided automatically as part of the attribution control.

If you hide the attribution control, you must provide an alternative opt out in one of two ways:

Add a setting to your application’s section in the system Settings app using a Settings.bundle in your application bundle. An example Settings.bundle is included with the SDK. If you installed the SDK via CocoaPods or Carthage, download the example bundle (source code).
Integrate the setting directly into your app. Hook a UISwitch control up to the MGLMapboxMetricsEnabled Boolean user default, which should be YES by default. Then set MGLMapboxMetricsEnabledSettingShownInApp to YES in your app’s Info.plist file.

Location services

In order to show the user’s position on the map, you must first ask for their permission. In iOS 8 and above, this is accomplished by creating and setting the NSLocationAlwaysUsageDescription and/or NSLocationWhenInUseUsageDescription keys in the Info.plist file.

Enabling MGLMapView.showsUserLocation will automatically ask for the necessary permission and, once granted, will place an annotation on the map at the user’s location.

In most cases, you will only need to provide one usage description key. If both location usage description keys are defined and permission has not yet been granted by the user, this SDK will request "when in use" authorization. For more information on these keys and iOS location permissions in general, see NSHipster's comprehensive overview.

API introduction

Below are some of the major components used when building a map-based iOS app with Mapbox:

Map view (MGLMapView class) - The map view is an interactive world map that pans and zooms in response to gestures. Optionally, use the corresponding MGLMapViewDelegate protocol to customize annotations, respond to user interaction, and more. MGLMapViewDelegate follows Cocoa's delegation design pattern.
Annotations (MGLAnnotation protocol) - Use an annotation to present data points and custom points of interest atop the map view. The premade MGLPointAnnotation class makes it easy to add a basic, pin-like point annotation. Alternatively, have your own model class adopt the MGLAnnotation protocol to have the map view serve as a container for your data. Use the MGLAnnotationView class for further visual customization and tight integration with UIKit.
Style (MGLStyle class) - MGLStyle provides access to the runtime styling API, with options for controlling every aspect of the map’s content and appearance in real time. The runtime styling API offers a more powerful alternative to annotations for data visualizations.
Offline maps (MGLOfflineStorage class) - An offline pack makes a region of the map available even when a network connection is unavailable or unreliable. Use the singleton MGLOfflineStorage object to download and manage MGLOfflinePacks.

Full API documentation is available on the web, in the binary download package, or right in Xcode, either inline or in Xcode’s Quick Help inspector.

Map styles

All Mapbox accounts have access to our professionally-designed template styles. You can also design your own custom styles visually within Mapbox Studio for use with the Mapbox iOS SDK. See our examples for using one of our template styles or a custom style designed in Mapbox Studio.

Attribution

If your application displays a map using Mapbox map designs or data, you must display the Mapbox wordmark and text attribution. The Mapbox iOS SDK will add attribution to your maps automatically. For more information about required attribution, see our guidelines.

Additional Mapbox libraries

In addition to the Mapbox iOS SDK, we also provide libraries that connect to other Mapbox services using a familiar, object-oriented interface.

The Mapbox Navigation SDK for iOS gives you all the tools you need to add turn-by-turn navigation to your application, powered by MapboxDirections.swift. It works with both Swift and Objective-C on iOS to provide drop-in UI components for navigation while supporting routing profiles for driving, walking, and cycling directions. It also includes features such as maneuver announcements, traffic avoidance, and automatic rerouting. With the Mapbox Navigation SDK for iOS, you can integrate navigation within your own application without having to send your users to a third party navigation service.

Download the Mapbox Navigation SDK for iOS from GitHub or install it with CocoaPods or Carthage.

Directions

MapboxDirections.swift connects your application to the Mapbox Directions API. It is compatible with both Objective-C and Swift on iOS, macOS, tvOS, and watchOS. Quickly get driving, cycling, or walking directions, whether the trip is nonstop or it has multiple stopping points, all using a simple interface reminiscent of MapKit’s MKDirections.

Geocoder

MapboxGeocoder.swift connects your application to the Mapbox Geocoding API. It works with both Swift and Objective-C on iOS, macOS, tvOS, and watchOS. Easily convert an address or place name into a coordinate pair or vice versa, all using a simple interface similar to the Core Location framework’s CLGeocoder. MapboxGeocoder.swift integrates with both Core Location and the Contacts framework.

Download MapboxGeocoder.swift from GitHub or install it with CocoaPods or Carthage.

Static maps

MapboxStatic.swift connects your application to the Mapbox Static API. It works with both Swift and Objective-C on iOS, macOS, tvOS, and watchOS. Quickly generate a static map image with markers and other overlays. Static maps are best suited for table views and other space- or memory-constrained environments in which the map doesn’t need to respond to gestures. If the map still needs to work when the device is offline, consider using the Mapbox iOS SDK’s offline map feature instead.

Download MapboxStatic.swift from GitHub or install it with CocoaPods or Carthage.

Need help?

Our Help page is filled with how-to references and guides so you can master our tools.

Help docs and guides