Add Mapbox to your iPhone or iPad app

Start building

Once you've got Mapbox installed, start by building an application using an Interface Builder storyboard, or starting with a code example. If you run into any issues, don't hesistate to ask our support team.

API overview

Below we’ll talk about the major components used when building a map-based iOS app with Mapbox. We’re assuming you have a general familiarity with Apple’s developer tools, the UIKit framework, and the syntax and conventions of either Objective-C or Swift. If you're new to iOS development, check out our first steps guide.

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 view (MGLMapView 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 or .storyboard file, just like any other UIView subclass. It starts with a beautiful default map style, but you can change the style to another Mapbox-designed style using MGLStyle in conjunction with MGLMapView’s styleURL property. There are also options to control annotations on the map, zooming limits, starting coordinate, among other parameters.

Map view delegate (MGLMapViewDelegate protocol)

Following Cocoa’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
  • Pre- and post-move and zoom response handlers in order to, for example, update another interface element in response to a map drag
  • Interaction handlers for markers and other annotations

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:

  1. In the Info.plist file (in the Project Navigator, or in the Info tab of the project editor), set MGLMapboxAccessToken.
  2. 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:

  1. 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).
  2. 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.

Map style changes

All Mapbox accounts have access to six professionally-designed styles:

  • Mapbox Streets: Our signature style. Read the blog post for more on the mobile-specific considerations in this style.
  • Outdoors: A general-purpose style that emphasizes physical terrain and outdoor activities.
  • Light and Dark: Light- and dark-colored styles that are great for data overlays. Use them for day and night modes, underlays for bright data atop, and more.
  • Satellite and Satellite Streets: The best-looking, most accurate, and most up-to-date satellite imagery available anywhere — labels optional. Check out our blog for the latest on our cutting-edge techniques and data.

The Mapbox iOS SDK can view any style written in the open Mapbox Style Specification format. You can design your own styles visually within Mapbox Studio for use with the Mapbox iOS SDK.

The default style is Mapbox Streets. See our examples for using a different default style or a custom style designed in Studio.

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. The attribution control may be moved or removed as necessary, so long as the required attribution is reasonably provided in your app.

If you remove the attribution control, you must provide your users with an alternative way to opt out of Mapbox Telemetry.

For more information on Mapbox’s attribution requirements, click here.

Mapbox API libraries

In addition to the Mapbox iOS SDK, we also provide lightweight libraries that connect to our most popular REST APIs using a familiar, object-oriented interface. Each of these libraries works with both Swift and Objective-C on iOS, macOS, tvOS, and watchOS.

Geocoder

MapboxGeocoder.swift connects your application to the Mapbox Geocoding API. 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.

Directions

MapboxDirections.swift connects your application to the Mapbox Directions API. 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.

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

Static maps

MapboxStatic.swift connects your application to the classic Mapbox Static API. 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.