intermediate
Swift or Objective-C
First steps with the Mapbox Maps SDK for iOS
Prerequisite
Familiarity with Xcode and either Swift or Objective-C, and completion of the Mapbox Maps SDK for iOS installation guide.

The Mapbox Maps SDK for iOS is our vector maps library for iOS. This guide will walk you through the basics of working with the Maps SDK for iOS, including how to customize your map, add markers with callouts, and display your user’s location on a map.

Getting started

Before you begin, install the Mapbox Maps SDK for iOS by following our installation guide. You can integrate the Mapbox Maps SDK for iOS using a dependency manager such as Carthage or CocoaPods, or you can install the SDK manually.

After you complete the installation flow, your view controller should look similar to the one below if you chose the “Add with code” option. If you selected the “Add with Storyboard” option during the installation process, you will need to connect your MGLMapView to an IBOutlet so it is accessible within your view controller to continue with this guide.

import Mapbox
 
class ViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()
      
        
        let mapView = MGLMapView(frame: view.bounds)
        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        mapView.setCenter(CLLocationCoordinate2D(latitude: 40.74699, longitude: -73.98742), zoomLevel: 9, animated: false)
        view.addSubview(mapView)
        
    }
}
#import "ViewController.h"

@import Mapbox;
@interface ViewController ()
@end

@implementation ViewController
 
- (void)viewDidLoad {
    [super viewDidLoad];
    
    
    MGLMapView *mapView = [[MGLMapView alloc] initWithFrame:self.view.bounds];
    mapView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
    [mapView setCenterCoordinate:CLLocationCoordinate2DMake(40.74699, -73.98742)
                       zoomLevel:9
                        animated:NO];
    [self.view addSubview:mapView];
    
}

@end

Changing the map style

To change your map style, set the MGLMapView.styleURL property to a style URL. This style URL can be any one of our beautiful template or designer styles, or you can create your own completely custom style in Mapbox Studio.

The MGLStyle class also provides a set of convenience methods that return the style URLs of default Mapbox styles.

For this guide, you will be using the Mapbox Satellite Streets style. Set the MGLMapView.styleURL property to the URL for this style using the provided convenience method, satelliteStreetsStyleURL.

import Mapbox
 
class ViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()
        
        
        let mapView = MGLMapView(frame: view.bounds)
        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        mapView.setCenter(CLLocationCoordinate2D(latitude: 40.74699, longitude: -73.98742), zoomLevel: 9, animated: false)
        view.addSubview(mapView)
        
        
        mapView.styleURL = MGLStyle.satelliteStyleURL
        
    }
}
#import "ViewController.h"

@import Mapbox;
@interface ViewController ()
@end

@implementation ViewController
 
- (void)viewDidLoad {
    [super viewDidLoad];
    
    
    MGLMapView *mapView = [[MGLMapView alloc] initWithFrame:self.view.bounds];
    mapView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
    [mapView setCenterCoordinate:CLLocationCoordinate2DMake(40.74699, -73.98742)
                       zoomLevel:9
                        animated:NO];
    [self.view addSubview:mapView];
    
    
    mapView.styleURL = [MGLStyle satelliteStreetsStyleURL];
    
}

@end

Then run your application to see the map’s new style.

Satellite map on iOS app

Adding a marker to the map

There are a number of ways to add a marker, also called an annotation, to your map. MGLPointAnnotation provides the simplest way to add a predefined point style to your map.

Your viewDidLoad method should look like the code below in order to place a point annotation on Central Park within New York City.

class ViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()
        
        
        let mapView = MGLMapView(frame: view.bounds)
        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        mapView.setCenter(CLLocationCoordinate2D(latitude: 40.74699, longitude: -73.98742), zoomLevel: 9, animated: false)
        view.addSubview(mapView)
        
        
        mapView.styleURL = MGLStyle.satelliteStyleURL
        
        
        // Add a point annotation
        let annotation = MGLPointAnnotation()
        annotation.coordinate = CLLocationCoordinate2D(latitude: 40.77014, longitude: -73.97480)
        annotation.title = "Central Park"
        annotation.subtitle = "The biggest park in New York City!"
        mapView.addAnnotation(annotation)
        
    }
}
- (void)viewDidLoad {
    [super viewDidLoad];
    
    
    MGLMapView *mapView = [[MGLMapView alloc] initWithFrame:self.view.bounds];
    mapView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
    [mapView setCenterCoordinate:CLLocationCoordinate2DMake(40.74699, -73.98742)
                       zoomLevel:9
                        animated:NO];
    [self.view addSubview:mapView];
    
    
    mapView.styleURL = [MGLStyle satelliteStreetsStyleURL];
    
    
    // Add a point annotation
    MGLPointAnnotation *annotation = [[MGLPointAnnotation alloc] init];
    annotation.coordinate = CLLocationCoordinate2DMake(40.77014, -73.97480);
    annotation.title = @"Central Park";
    annotation.subtitle = @"The best park in New York City!";
    [mapView addAnnotation:annotation];
    
}

Run your application and notice the new point annotation added.

Map with marker on Central Park

MGLPointAnnotation is the base class of all point annotations and can be additionally configured to use views or static images in place of the default annotation style. Check out MGLAnnotationView and MGLAnnotationImage for more information about working with these types of annotations.

If you’re looking to add a large number of points to a map, consider using runtime styling, which is another feature of the Mapbox Maps SDK for iOS geared towards creating rich data visualizations. For more information about the different ways to add points to a map and the differences between each approach, check out our Adding Points to a Map guide.

Adding a callout

To get the annotation to display a callout when a user taps on it, the view controller will need to conform to the MGLMapViewDelegate protocol in order to use the delegate methods MGLMapViewDelegate provides.

Once the view controller conforms to the MGLMapViewDelegate protocol and the map view’s delegate is set to the view controller itself, you can then implement the -mapView:annotationCanShowCallout: delegate method. This ensures that the map view knows that an annotation should display a callout when tapped. The full implementation of this is shown below:

import Mapbox

// Enable the view controller to conform to the MGLMapViewDelegate protocol
class ViewController: UIViewController, MGLMapViewDelegate {
    override func viewDidLoad() {
        super.viewDidLoad()
        
        
        let mapView = MGLMapView(frame: view.bounds)
        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        mapView.setCenter(CLLocationCoordinate2D(latitude: 40.74699, longitude: -73.98742), zoomLevel: 9, animated: false)
        view.addSubview(mapView)
        
        
        mapView.styleURL = MGLStyle.satelliteStyleURL
        
        
        // Add a point annotation
        let annotation = MGLPointAnnotation()
        annotation.coordinate = CLLocationCoordinate2D(latitude: 40.77014, longitude: -73.97480)
        annotation.title = "Central Park"
        annotation.subtitle = "The biggest park in New York City!"
        mapView.addAnnotation(annotation)
        
        
        // Set the map view's delegate
        mapView.delegate = self
        
    }

    
    func mapView(_ mapView: MGLMapView, annotationCanShowCallout annotation: MGLAnnotation) -> Bool {
        // Always allow callouts to popup when annotations are tapped.
        return true
    }
    
}
#import "ViewController.h"

@import Mapbox;
// Enable the view controller to conform to the MGLMapViewDelegate protocol
@interface ViewController () <MGLMapViewDelegate>
@end

@implementation ViewController
 
- (void)viewDidLoad {
    [super viewDidLoad];
    
    
    MGLMapView *mapView = [[MGLMapView alloc] initWithFrame:self.view.bounds];
    mapView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
    [mapView setCenterCoordinate:CLLocationCoordinate2DMake(40.74699, -73.98742)
                       zoomLevel:9
                        animated:NO];
    [self.view addSubview:mapView];
    
    
    mapView.styleURL = [MGLStyle satelliteStreetsStyleURL];
    
    
    // Add a point annotation
    MGLPointAnnotation *annotation = [[MGLPointAnnotation alloc] init];
    annotation.coordinate = CLLocationCoordinate2DMake(40.77014, -73.97480);
    annotation.title = @"Central Park";
    annotation.subtitle = @"The best park in New York City!";
    [mapView addAnnotation:annotation];
    
    
    // Set the map view's delegate
    mapView.delegate = self;
    
}


- (BOOL)mapView:(MGLMapView *)mapView annotationCanShowCallout:(id<MGLAnnotation>)annotation {
    // Always allow callouts to popup when annotations are tapped.
    return YES;
}


@end

Run the application, and then try to tap the annotation — it now displays a callout with your annotation’s title and subtitle when tapped!

satellite map on iOS app

Zooming to a marker

To center the map on the tapped marker, start by implementing the -mapView:didSelectAnnotation: delegate method. When the delegate method is called, initialize a new MGLMapCamera, which represents the map’s field of view. After creating the MGLMapCamera, call the -setCamera:animated: method on the MGLMapView to set the map’s viewport to the new camera, which will be centered on the annotation’s coordinate at a specified distance above ground level.

import Mapbox

// Enable the view controller to conform to the MGLMapViewDelegate protocol
class ViewController: UIViewController, MGLMapViewDelegate {
    override func viewDidLoad() {
        super.viewDidLoad()

        let mapView = MGLMapView(frame: view.bounds, styleURL: MGLStyle.satelliteStreetsStyleURL())
        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        mapView.setCenter(CLLocationCoordinate2D(latitude: 40.74699, longitude: -73.98742), zoomLevel: 9, animated: false)
        view.addSubview(mapView)

        // Add a point annotation
        let annotation = MGLPointAnnotation()
        annotation.coordinate = CLLocationCoordinate2D(latitude: 40.77014, longitude: -73.97480)
        annotation.title = "Central Park"
        annotation.subtitle = "The biggest park in New York City!"
        mapView.addAnnotation(annotation)

        // Set the map view's delegate to the view controller
        mapView.delegate = self
    }

    // Implement the delegate method that allows annotations to show callouts when tapped
    func mapView(_ mapView: MGLMapView, annotationCanShowCallout annotation: MGLAnnotation) -> Bool {
        return true
    }
    
    // Zoom to the annotation when it is selected
    func mapView(_ mapView: MGLMapView, didSelect annotation: MGLAnnotation) {
        let camera = MGLMapCamera(lookingAtCenter: annotation.coordinate, fromDistance: 4000, pitch: 0, heading: 0)
        mapView.setCamera(camera, animated: true)
    }
}
#import "ViewController.h"

@import Mapbox;
// Enable the view controller to conform to the MGLMapViewDelegate protocol
@interface ViewController () <MGLMapViewDelegate>
@end

@implementation ViewController
 
- (void)viewDidLoad {
    [super viewDidLoad];
 
    MGLMapView *mapView = [[MGLMapView alloc] initWithFrame:self.view.bounds
                                                   styleURL:[MGLStyle satelliteStreetsStyleURL]];
    mapView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
    [mapView setCenterCoordinate:CLLocationCoordinate2DMake(40.74699, -73.98742)
                       zoomLevel:9
                        animated:NO];
    [self.view addSubview:mapView];

    // Add a point annotation
    MGLPointAnnotation *annotation = [[MGLPointAnnotation alloc] init];
    annotation.coordinate = CLLocationCoordinate2DMake(40.77014, -73.97480);
    annotation.title = @"Central Park";
    annotation.subtitle = @"The biggest park in New York City!";
    [mapView addAnnotation:annotation];

    // Set the map view's delegate to the view controller
    mapView.delegate = self;
}

// Implement the delegate method that allows annotations to show callouts when tapped
- (BOOL)mapView:(MGLMapView *)mapView annotationCanShowCallout:(id<MGLAnnotation>)annotation {
    return YES;
}

// Zoom to the annotation when it is selected
- (void)mapView:(MGLMapView *)mapView didSelectAnnotation:(id<MGLAnnotation>)annotation {
    MGLMapCamera *camera = [MGLMapCamera cameraLookingAtCenterCoordinate: annotation.coordinate fromDistance:4000 pitch:0 heading:0];
    [mapView setCamera:camera animated:true];
}

@end
zooming to marker

Displaying the user’s location

If you haven’t configured location permissions already, you will need to do so in order to use the device’s location services. Before you can draw a user’s location on the map, you must ask for their permission and give a brief explanation of how your application will use their location data.

Configure location permissions by setting the NSLocationWhenInUseUsageDescription key in the Info.plist file. We recommend setting the value to the following string which represents the application’s location usage description: Shows your location on the map and helps improve OpenStreetMap. Additionally, you may also choose to include the NSLocationAlwaysAndWhenInUseUsageDescription within your Info.plist file. We recommend providing a different string when using this key to help your users decide which level of permission they wish to grant to your application. When a user opens your application for the first time, they will be presented with an alert that asks them if they would like to allow your application to access their location.

Once you have configured your application’s location permissions, display the device’s current location on the map by setting the showsUserLocation property on the map view to true.

import Mapbox
 
class ViewController: UIViewController, MGLMapViewDelegate {
    override func viewDidLoad() {
 
      
      let mapView = MGLMapView(frame: view.bounds)
      mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
      mapView.setCenter(CLLocationCoordinate2D(latitude: 40.74699, longitude: -73.98742), zoomLevel: 9, animated: false)
      view.addSubview(mapView)
      
      
      mapView.styleURL = MGLStyle.satelliteStyleURL
      
      
      // Add a point annotation
      let annotation = MGLPointAnnotation()
      annotation.coordinate = CLLocationCoordinate2D(latitude: 40.77014, longitude: -73.97480)
      annotation.title = "Central Park"
      annotation.subtitle = "The biggest park in New York City!"
      mapView.addAnnotation(annotation)
      
      
      // Set the map view's delegate
      mapView.delegate = self
      
      
      // Allow the map view to display the user's location
      mapView.showsUserLocation = true
      
    }
    
    // Zoom to the annotation when it is selected
    func mapView(_ mapView: MGLMapView, didSelect annotation: MGLAnnotation) {
        let camera = MGLMapCamera(lookingAtCenter: annotation.coordinate, fromDistance: 4000, pitch: 0, heading: 0)
        mapView.fly(to: camera, completionHandler: nil)
    }
}
#import "ViewController.h"

@import Mapbox;
// Enable the view controller to conform to the MGLMapViewDelegate protocol
@interface ViewController () <MGLMapViewDelegate>
@end

@implementation ViewController
 
- (void)viewDidLoad {
    [super viewDidLoad];
    
    
    MGLMapView *mapView = [[MGLMapView alloc] initWithFrame:self.view.bounds];
    mapView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
    [mapView setCenterCoordinate:CLLocationCoordinate2DMake(40.74699, -73.98742)
                       zoomLevel:9
                        animated:NO];
    [self.view addSubview:mapView];
    
    
    mapView.styleURL = [MGLStyle satelliteStreetsStyleURL];
    
    
    // Add a point annotation
    MGLPointAnnotation *annotation = [[MGLPointAnnotation alloc] init];
    annotation.coordinate = CLLocationCoordinate2DMake(40.77014, -73.97480);
    annotation.title = @"Central Park";
    annotation.subtitle = @"The best park in New York City!";
    [mapView addAnnotation:annotation];
    
    
    // Set the map view's delegate
    mapView.delegate = self;
    
    
    // Allow the map view to display the user's location
    mapView.showsUserLocation = YES;
    
}

// Zoom to the annotation when it is selected
- (void)mapView:(MGLMapView *)mapView didSelectAnnotation:(id<MGLAnnotation>)annotation {
    MGLMapCamera *camera = [MGLMapCamera cameraLookingAtCenterCoordinate: annotation.coordinate fromDistance:4000 pitch:0 heading:0];
    [mapView flyToCamera:camera completionHandler:nil];
}

@end

Simulating a location

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

Location permissions alert

You won’t see your location on the map until you go to Simulator’s menu bar and select Debug ‣ Location ‣ Custom Location. Enter 40.74699 for latitude, -73.98742 for longitude, and you’re right outside Central Park in New York City!

Map displaying user location

Next steps

You just built a small app with the Mapbox Maps SDK for iOS! You added a Mapbox map to an iOS application, changed the map style, placed an annotation on your map, and displayed the user’s location on it. Way to go!

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