The Mapbox iOS SDK is our vector maps library for iOS. This guide will walk you through installing the Mapbox iOS SDK using Xcode and storyboards to load a map, change the map style, and place a pin and the user’s location on it. We’ll show you how to do this in both Objective-C and Swift.

Heads up! We’re still actively developing the Mapbox iOS SDK and will update this guide as we improve its amazing features. This guide was created using Xcode 8.3.1 and Mapbox iOS SDK v3.5.2.

Getting started

Here’s what you’ll need to get started:

• An access token. You can find your access tokens on your account page.
• Xcode and Apple’s iOS SDK. You can get these for free from the Mac App Store.
• Apple Developer Account (optional). You can use your personal devices or Xcode’s iOS Simulator for this guide without an Apple Developer Account. If you want to distribute your app to others, you’ll need to sign up and pay for an account.

Setting up in Xcode

Open Xcode and create a new Single View Application. You can use either Swift or Objective-C to create an iPhone app using this guide.

Setting your access token

To display maps hosted by Mapbox in your app, you need to place your access token inside the app’s Info.plist file:

1. In the Project navigator (in the left sidebar), find your app’s Info.plist.
2. Select the “Information Property List” row at the top, and go to Editor ‣ Add Item.
3. In the new row that is inserted, set the Key to MGLMapboxAccessToken and set the Value to your access token.

You only have to set the access token once in this file, no matter how many map views you put in your app. Access tokens help to ensure that only your apps are using your Mapbox account. Please remember to keep your access token token private, especially if you will be sharing your code publicly.

Downloading and installing the Mapbox iOS SDK

Now that you’ve created an Xcode project, you can install the Mapbox iOS SDK. Download the latest release as a dynamic framework, unzip the downloaded file, and then drag and drop Mapbox.framework into the Embedded Binaries section of your project:

Be sure to check Copy items if needed for the Destination.

With the Mapbox framework added to your project, you now have access to all the classes and methods available in our SDK.

Staying up-to-date

The current release of the Mapbox iOS SDK is v3.6.0. To keep up with new releases, check our GitHub releases page, read our blog, follow us on Twitter, or watch your inbox for our newsletters.

Note that, because you’re installing manually in this guide, you’ll have to download new versions of the Mapbox iOS SDK and drag them in again every time there’s an updated release. For a project you intend to develop and maintain over time, consider installing our SDK via a package manager, such as CocoaPods.

Adding a map using storyboards

In this guide, you’ll build the app’s interface using an Interface Builder storyboard. (Alternatively, you can create the interface entirely in code.) Select the existing view from your view controller, then in the Identity inspector tab in the right sidebar, change the class to MGLMapView. This adds the basic map into the view controller so you can do things like add custom styles, set the map’s center, and add annotations.

Add constraints to the MGLMapView so that it is equal to the width and height of the root view.

Now that you’ve added a map view to your app, try it out. Select an iPhone model, then click the Build and Run button.

Simulator will open, boot up, and then start the app you just created:

Customizing the map

To change the initial coordinate and zoom level, select the Map View in Interface Builder, then open the Attributes inspector tab in the right sidebar.

Set Latitude to 45.52245, Longitude to -122.67773, and Zoom Level to 14.

Run your app in Simulator to see a map centered on the city of Portland, Oregon:

Changing map style

The default style you’re seeing is the Mapbox Streets style. But what if you want satellite imagery underneath those roads? In the Attributes inspector, you can choose a different Mapbox style.

Enter mapbox://styles/mapbox/satellite-streets-v9 in the Style URL box.

Re-run your app in Simulator to see the newly applied Satellite Streets map style:

Creating your own styles

You can easily create your own custom, Mapbox-hosted styles in Mapbox Studio. Mapbox Studio produces styles that look great on iOS, Android, and in web apps powered by Mapbox GL JS.

Using Mapbox Studio Classic styles and maps

Raster maps and styles created with Mapbox Studio Classic aren’t directly compatible with the Mapbox iOS SDK, though you can still load these maps via a custom style. Note that the Mapbox iOS SDK doesn’t support markers, lines, and shapes associated with raster maps.

Adding an annotation with code

With this storyboard, you can keep adding controls and screens to your app, knowing that the map view will fit right in. You can add more functionality to the map view, though. To do that, you’ll need to dive into some code. Switch from Interface Builder to the View Controller’s code. In the Project navigator, open ViewController.m or ViewController.swift (depending on whether you chose Objective-C or Swift) to reveal the underlying code.

There’s already some code in the file to get you started. You’ll add some more code here to access the map view as well as add some annotations (also known as markers).

Connecting the map view to an outlet in Interface Builder

But first, use Interface Builder to add an outlet that allows you to refer to the map view from within your code. Switch to the Assistant Editor by clicking the button in the upper-right corner of the Xcode window. Whenever you select the view controller or anything within on the storyboard canvas, the other side of the window will show the view controller’s code.

Hold down the control key while dragging the mouse from the map view on the storyboard canvas to the view controller code. Release the mouse when you see a blue, horizontal line appear, indicating a valid insertion point. Name the outlet mapView. You could’ve written this line of code yourself, but why not do it visually!

You’ll notice that Xcode flags this new line with an error — that’s because you haven’t imported the Mapbox framework yet. On to the next section!

Importing the Mapbox framework in code

You’re done with Interface Builder and are ready to get down to coding. Import the Mapbox framework at the top of the view controller code:

import Mapbox

#import "ViewController.h"
@import Mapbox;

Setting the map view’s delegate

In order to configure various annotation properties, your view controller will need to conform to the MGLMapViewDelegate protocol:

class ViewController: UIViewController, MGLMapViewDelegate {

@interface ViewController () <MGLMapViewDelegate>

Then set the map view’s delegate property:

override func viewDidLoad() {
    super.viewDidLoad()

    mapView.delegate = self
}

- (void)viewDidLoad {
    [super viewDidLoad];

    self.mapView.delegate = self;
}

Defining the annotation and add it to the map

With everything hooked up, add an annotation — line by line. First, create an MGLPointAnnotation object at the end of the viewDidLoad method and assign it to the local variable point:

override func viewDidLoad() {
    super.viewDidLoad()

    mapView.delegate = self

    let point = MGLPointAnnotation()
}

- (void)viewDidLoad {
    [super viewDidLoad];

    self.mapView.delegate = self;

    MGLPointAnnotation *point = [[MGLPointAnnotation alloc] init];
}

Next, give the point annotation a coordinate:

override func viewDidLoad() {
    super.viewDidLoad()

    mapView.delegate = self

    let point = MGLPointAnnotation()
    point.coordinate = CLLocationCoordinate2D(latitude: 45.52258, longitude: -122.6732)
}

- (void)viewDidLoad {
    [super viewDidLoad];

    self.mapView.delegate = self;

    MGLPointAnnotation *point = [[MGLPointAnnotation alloc] init];
    point.coordinate = CLLocationCoordinate2DMake(45.52258, -122.6732);
}

Annotations have title and subtitle properties that provide text content for callout views, which we’ll get to in a moment:

override func viewDidLoad() {
    super.viewDidLoad()

    mapView.delegate = self

    let point = MGLPointAnnotation()
    point.coordinate = CLLocationCoordinate2D(latitude: 45.52258, longitude: -122.6732)
    point.title = "Voodoo Doughnut"
    point.subtitle = "22 SW 3rd Avenue Portland Oregon, U.S.A."
}

- (void)viewDidLoad {
    [super viewDidLoad];

    self.mapView.delegate = self;

    MGLPointAnnotation *point = [[MGLPointAnnotation alloc] init];
    point.coordinate = CLLocationCoordinate2DMake(45.52258, -122.6732);
    point.title = @"Voodoo Doughnut";
    point.subtitle = @"22 SW 3rd Avenue Portland Oregon, U.S.A.";
}

Finally, add the annotation to the map view:

override func viewDidLoad() {
    super.viewDidLoad()

    mapView.delegate = self

    let point = MGLPointAnnotation()
    point.coordinate = CLLocationCoordinate2D(latitude: 45.52258, longitude: -122.6732)
    point.title = "Voodoo Doughnut"
    point.subtitle = "22 SW 3rd Avenue Portland Oregon, U.S.A."

    mapView.addAnnotation(point)
}

- (void)viewDidLoad {
    [super viewDidLoad];

    self.mapView.delegate = self;

    MGLPointAnnotation *point = [[MGLPointAnnotation alloc] init];
    point.coordinate = CLLocationCoordinate2DMake(45.52258, -122.6732);
    point.title = @"Voodoo Doughnut";
    point.subtitle = @"22 SW 3rd Avenue Portland Oregon, U.S.A.";

    [self.mapView addAnnotation:point];
}

The full code should look like this:

import Mapbox

class ViewController: UIViewController, MGLMapViewDelegate {

    @IBOutlet var mapView: MGLMapView!

    override func viewDidLoad() {
        super.viewDidLoad()

        mapView.delegate = self

        let point = MGLPointAnnotation()
        point.coordinate = CLLocationCoordinate2D(latitude: 45.52258, longitude: -122.6732)
        point.title = "Voodoo Doughnut"
        point.subtitle = "22 SW 3rd Avenue Portland Oregon, U.S.A."

        mapView.addAnnotation(point)
    }

    // Note: You can remove this method, which lets you customize low-memory behavior.
    override func didReceiveMemoryWarning() {
        super.didReceiveMemoryWarning()
        // Dispose of any resources that can be recreated.
    }
}

#import "ViewController.h"
@import Mapbox;

@interface ViewController () <MGLMapViewDelegate>

@property (strong, nonatomic) IBOutlet MGLMapView *mapView;

@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];

    self.mapView.delegate = self;

    MGLPointAnnotation *point = [[MGLPointAnnotation alloc] init];
    point.coordinate = CLLocationCoordinate2DMake(45.52258, -122.6732);
    point.title = @"Voodoo Doughnut";
    point.subtitle = @"22 SW 3rd Avenue Portland Oregon, U.S.A.";

    [self.mapView addAnnotation:point];
}

// Note: You can remove this method, which lets you customize low-memory behavior.
- (void)didReceiveMemoryWarning {
    [super didReceiveMemoryWarning];
    // Dispose of any resources that can be recreated.
}

@end

Tapping the annotation

What if you want to display a title and subtitle when your user taps on an annotation? To do that, enable the annotation’s callout. After the viewDidLoad method, add the following method:

func mapView(_ mapView: MGLMapView, annotationCanShowCallout annotation: MGLAnnotation) -> Bool {
    // Always try to show a callout when an annotation is tapped.
    return true
}

- (BOOL)mapView:(MGLMapView *)mapView annotationCanShowCallout:(id <MGLAnnotation>)annotation {
    // Always try to show a callout when an annotation is tapped.
    return YES;
}

Re-run your code to test the annotation’s new interactivity.

Customizing the point annotation

You can use custom views for your annotations by implementing the -mapView:viewForAnnotation: delegate method. Custom view annotations are very versatile — they can easily be animated or dragged around the map. See our custom annotation view example for more information.

If you only plan to use small, static images for your annotations or you want to place tens of thousands of them at once, check out the -mapView:imageForAnnotation: delegate method and this example.

Showing the user’s location

Your users most likely want to orient themselves using your app, so let’s put the phone’s current location on the map. Back in Interface Builder’s Attributes inspector, find Shows User Location and set this to On.

Enabling location services

Before you can draw a user’s location on the map, you have to ask for their permission and give a brief explanation of how the app will use their location data.

For users of iOS 8 and above, set the NSLocationAlwaysUsageDescription or NSLocationWhenInUseUsageDescription key in the Info.plist file, which is also accessible via the Info tab of the project editor.

We recommend this location usage description: Shows your location on the map and helps improve OpenStreetMap.

For more about iOS location permissions, NSHipster has a good overview.

Simulating location

When you run your app in Simulator, you’ll be presented with a dialog box asking for permission to use Location Services:

You won’t see your location on the map until you go to Simulator’s menu bar and select Debug ‣ Location ‣ Custom Location. Enter 45.52258 for latitude, -122.6732 for longitude, and you’re right outside the doughnut shop!

Next steps

You just built a small app with Mapbox. Now you can create an Xcode project, add a map view using a storyboard, change the map style, and place a pin and the user’s location on it. Pat yourself on the back!

As you continue to develop your Mapbox app, we recommend that you read the following:

• Mapbox Telemetry — provide users with a way to individually opt out of Mapbox Telemetry
• Attribution — comply with the licensing terms of the map data used in your application

We’ll be adding and updating guides to help you learn all of Mapbox’s amazing features as we continue to develop it. Here are a few resources to keep you up-to-date with Mapbox:

• Mapbox iOS SDK documentation
• Mapbox GL Native on GitHub to follow the open source project behind Mapbox Mobile